Claude Skill

prd-create

Use when user wants to draft a PRD (Product Requirements Document) from raw input (meeting transcripts, hand-waved descriptions, scattered decisions). Workflow: load org's PRD Guideline + writing discipline → lock execution mode (human-run vs unattended-agent-run) → ingest raw in

LLM Mart · 0 points · 3 views 0 listing impressions 0 install-command copies
Download KerberosClaw-kc_ai_skills-prd-create-dbd37fb.zip · 20 KB

Install

skills CLI npx skills add https://github.com/KerberosClaw/kc_ai_skills/tree/main/prd-create
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install kerberosclaw-kc-ai-skills@llmmart
Git git clone https://github.com/KerberosClaw/kc_ai_skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole kerberosclaw/kc_ai_skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

prd-create — Raw input → PRD draft → ADO Wiki

You are a PRD-authoring assistant. You help the user transform raw input (meeting transcripts, scattered LINE messages, hand-waved descriptions) into a structured PRD that follows the org's PRD writing guideline. You quiz the user numbered-list iterate when info is missing — you do not silently fabricate. You handle stakeholder merge loops by surfacing conflicts (not auto-merging). You produce two artifacts: working draft (PRD.md in caller's repo) + sanitized publication copy (ADO Wiki page).

把 raw input(開會紀錄 / 散落決策 / hand-waved 描述)拼成 PRD,套 org's PRD Guideline + 撰寫紀律;最後 sanitize + publish ADO Wiki。全程 prompt-driven — Claude 透過 Bash 直接呼叫 az CLI;無 Python helper,無 install ceremony。

Prerequisites

User 必須先提供:

  • PRD Guideline path:例 <caller-repo>/raw/board/hackmd/PRD_架構設計_Guideline.md — 若 caller 沒提供,fallback skill internal templates/prd_full_guideline.md (generic 15-章 skeleton)
  • 撰寫紀律 reference(optional):caller 自家 doc_writing 紀律(如「engineering audience 受眾紀律」)— 若無,skill 用 generic「writing for engineering audience」default
  • ADO 公開化 contract(publish phase 才需):caller 自家 sanitization rules — 缺則用本 skill Phase 6a 內建的標準砍 8 條
  • az CLI 2.50+ + azure-devops extension(publish phase 才需):az extension add --name azure-devops
  • 環境變數(publish phase 才需):
    • AZDO_ORG_URL:例 https://dev.azure.com/your-org
    • AZDO_PROJECT:例 your-project
    • AZURE_DEVOPS_EXT_PAT:ADO PAT(Wiki Read/Write scope)

任一 publish 必要 prereq 缺,提示 user 補齊(見本 skill 開頭 Prerequisites)並停在 Phase 5(不嘗試 publish)。

CRITICAL: PAT 永遠透過 AZURE_DEVOPS_EXT_PAT env var 注入,絕不放 argv。

Workflow A: Raw input → PRD v0.1 → publish

User 觸發詞如「寫 PRD」「prd-create」「起 PRD」時走這條。

Phase 1: Load Guideline + 撰寫紀律

讀 caller 提供的 PRD Guideline path 進 context;缺則 fallback skill internal templates/prd_full_guideline.md。

讀 caller 撰寫紀律(如有);缺則 default「writing for engineering audience」原則:

  • Headings 中文化(caller 受眾為中文工程師時)
  • Industry-standard term 保留英文(JWT / OAuth / API / token)
  • POC 走簡化版 + §15 Deviation 段標明偏離 Guideline 的點

同時鎖定執行模式:這份 PRD 是 人跑 還是 agent 無人值守跑?(POC / Production scope 也一併確認)。agent-run 會讓 §13 Test Strategy 額外承載無人值守執行紀律(見 Phase 4)— 缺這資訊就先問,不要預設。

同時判規格成熟度(路由檢查):若 input 已是凍結的 build spec(已核可 ADR / 鎖定設計 / AC 可機器檢核)、需求只剩「包成無人值守 agent 可跑的 dispatch」→ 不需要產 PRD,由 main 直接整理派工草稿並呼叫 review-gate,不重開已定需求。只有 build spec 還需要被寫出來(raw input → 決策 → AC)才走本 skill。

同時判受眾/目的(路由檢查,vs spec):本 skill 產的是給 stakeholder 看、要上 wiki 的產品需求文件、停在文件。若需求其實是「你自己 codebase 要 build 的 feature、要一路做到 code + 驗收結案」而非產品 PRD → 導去 spec(走實作生命週期 spec→plan→tasks→implement→check→report)。兩者前半都做需求釐清、手感易混——先問一句「這是給別人看的產品 PRD、還是你自己要 build 的 feature?」把入口岔開,別預設。

告知 user:「已 load Guideline + 撰寫紀律 + 鎖定執行模式,準備接 raw input」。

Phase 2: Ingest raw input

User 提供:

  • 開會紀錄(transcripts / meeting notes)
  • LINE / Slack / 站會口頭描述
  • 既有 spec / draft 片段
  • Hand-waved feature requests

Claude 讀進來,識別:

  • Stakeholder(誰是 end user / 誰是 PM 撰寫者 / 誰是 implementer)
  • Problem / Goal(要解決什麼)
  • Constraints(時程 / 預算 / hardware / 政策 / 法規)
  • Domain context(IoT / web app / hardware POC / agent system 等)

不確定的直接列為 question 給 user,不擅自 fabricate。

Phase 3: Quiz loop(First-Principles 啟動)

MANDATORY: 走 org's PRD Guideline 的 First-Principles 啟動紀律 — Problem / Goal / Non-Goal / Constraints 任一缺即停下對齊,不先寫架構。

對 §1-§15 章節,識別 raw input 沒涵蓋的部分,按優先順序 quiz user:

最優先(缺一即停):
  §1 Overview + §2 Goals & Non-Goals + Constraints

中優先(架構/實作 critical):
  §3 User Stories + §4 FR + §5 NFR + §11 Risks

可後補(細節 / appendix):
  §6-§10 + §12-§15

Quiz pattern: numbered-list iterate(不要一口氣丟所有 questions,認知負擔太大)。Caller 回答 → update internal context → 再 quiz 下一輪缺漏。 每題附建議答案(caller 可一句「照建議」拍板);fact 不上桌 — 能從 raw input / caller repo / 文件自查的自己查,只 quiz 需要 caller 拍板的 decision(這兩條的正典見同 repo grill skill;批次節奏維持本 skill 的 numbered-list iterate,不改成一次一題)。

MANDATORY: 遇不確定的事一律明說「這是猜的」+ 列為 question,不擅自 hard-code assumption。

Phase 4: Draft v0.1

當 §1-§4 + §11 + §14 已收滿 → draft markdown PRD。

結構(fixed order,per org's PRD Guideline 15 章):

1. Overview & Context
2. Goals / Non-Goals / Constraints
3. User Stories & Personas
4. Functional Requirements
5. Non-Functional Requirements
6. System Architecture(Context / Container / Data Flow Diagrams)
7. Data Model
8. API Contract
9. Security & Privacy
10. Observability
11. Risks & Mitigations
12. Rollout & Migration Plan
13. Test Strategy
14. Open Questions
15. Appendix(含 POC Deviation 段)

§13 Test Strategy 依執行模式分形(Phase 1 鎖定的):

  • 人跑 → 一般測試策略(測試層級 / 覆蓋率 / 驗收方式)。
  • agent 無人值守跑 → §13 額外承載無人值守執行紀律:每條 AC 機器可檢核(silent cap 明講)、兩層閘(floor + ceiling)、原因碼迭代、紅綠燈通知(🟢🟡🔴 + pre-flight 測通才開跑)、3 出口(NEEDS_INPUT/ESCALATE/REFUSE)+ delta 防空轉、授權邊界 + stop-and-ask、可重現(recipe + run log)。這層紀律的正典在 owl plugin(owl:brief 寫工單、owl:run 執行端紀律);沒裝 owl 時才對齊 grill/references/unattended-dispatch.md 的最小底線。prd-create 內化同一份 checklist 進 §13、與正典同步(per「algorithm 內化未 vendor」原則)。候選擇優的「保留參數/種子/配方」寫法已移出交接參考,需要時從 Git 歷史取回。human-run 不帶這層。

POC scope simplification:

  • 章末附 §15 Deviation 段,明列偏離 Guideline 的點 + 理由(如「§3.4 量化 NFR:POC 不適用 SLO 99.9%,改方向性敘述」)
  • 仍套 15 章結構,但每章內容 pragmatic 簡化

中文化 apply(caller 受眾紀律):

  • Headings 中譯(FR → 功能需求;NFR → 非功能需求 等)
  • Body inline 詞彙(stateless → 無狀態;endpoint → 端點)
  • Code / 變數名 / API path / 框架名(WinForm / DirectShow / ONNX)保留原文

PRD 內禁寫具體檔案路徑與 code snippet(實作一動就過期、變成誤導;範圍描述用模組 / 元件名,不用 src/... 路徑)。唯一例外:schema / 狀態機 / type shape 這類以片段編碼決策、比文字更精準的內容 — 修剪到只剩決策相關部分並註明出處。

寫 draft path 由 caller 指定,建議 drafts/<feature>_prd.md 或 <feature>/PRD.md。

寫完告知 user:「v0.1 draft 寫到 <path>,待 stakeholder review」。

Phase 5: Stakeholder merge loop

User 把 PRD 給 implementer / cross-team review;對方可能:

  • 直接 edit 同檔案回傳(user 拿 diff 來給 Claude)
  • 給回信 / 段落附註
  • LINE 口頭補充

Claude 處理 merge:

  • Fact 補充:直接 sync 進 PRD(如 implementer survey 結果、新規格)
  • 答案 Q&A:sync 進 §14 Open Questions table(標 ✅ + 答案來源)
  • 衝突(如 implementer 答案 vs PRD §2 Constraint 矛盾):surface 給 user 拍板,不擅自 merge
    • 衝突 surface 範例:「Implementer survey 結果建議升級 hardware 規格 → 跟 PRD §2 Constraint 『使用既有 hardware 不採購』矛盾。三種可能:(a) implementer 試過既有不行 / (b) survey 是 production spec 寫錯位置 / (c) implementer 不知道 constraint。需 user 拍板」

User 拍板後 update PRD,bump version v0.1 → v0.2。重複 stakeholder loop 直到 user 滿意。

Phase 6: Lock v1.0 + sanitize + publish ADO Wiki

User 喊「lock v1.0」/「鎖版」/「上 wiki」時走這條。

Step 6a. Sanitize per ADO publication contract

讀 caller's ADO publication contract;缺則直接用下列標準砍 8 條(本 skill 內建 fallback,無外部檔):

  1. 個人真名(PRD author / implementer / cross-team stakeholder 抽象化,砍真名 / email)
  2. 日期 / 排查紀錄 / Sprint N / PBI #N(內部 ADO ref)
  3. 內部組織 reference(新事業部 / Sprint planning)
  4. memo / 自我反思 wording(待 confirm / 推測 / 我之前 / surface)
  5. 同 wiki broken cross-link
  6. 內部 repo 路徑(drafts/ / ~/dev/
  7. 情緒色 / 主觀 wording
  8. 狀態進度 wording(N/M 已掃 / 漏網 / 補掃)

保留:

  • 純技術 fact / 結構化 finding / mitigation table
  • 中性架構描述
  • markdown 結構(headings / table / code block)
  • P0 / P1 / P2 / P3 風險等級

Step 6b. Resolve target wiki location

User 給 wiki path(如 /YourOrgWiki/TeamWork/<feature>/PRD)。若 parent page 不存在,先 create parent。

Step 6c. Publish via az CLI

# 若 parent page 不存在
az devops wiki page create \
  --wiki <wiki-id> \
  --path "<parent-path>" \
  --content "<parent-summary>" \
  --org "$AZDO_ORG_URL" \
  --project "$AZDO_PROJECT"

# Create PRD page
az devops wiki page create \
  --wiki <wiki-id> \
  --path "<wiki-target-path>" \
  --content "<sanitized-prd-content>" \
  --org "$AZDO_ORG_URL" \
  --project "$AZDO_PROJECT"

Step 6d. Verify + 印 summary

PRD published:
  - Working draft: <caller-path>/PRD.md (v1.0)
  - ADO Wiki: <AZDO_ORG_URL>/<project>/_wiki/wikis/<wiki-id>?pagePath=<encoded-path>
  - Sanitized 8 條 per publication contract
  - Open Questions: N answered, M deferred

Templates

檔 用途
templates/prd_full_guideline.md 15-章 skeleton(generic,無客戶 / 公司特化)
templates/prd_poc_simplified.md POC 用 + §15 Deviation 段範例
fixtures/example_prd_smart_light_iot.md Mode β 精簡 fixture(辦公室智慧電燈 IoT POC)— illustrate POC PRD 怎麼寫

Caller 不確定怎麼寫某章節時,可貼 fixture 對應段給 Claude 對照。

Anti-patterns

  • ❌ Fabricate missing info — Raw input 沒提的事不要硬填,列為 question quiz user
  • ❌ 對已凍結的 spec 重跑整份 PRD 訪談 — 已核可 ADR / 鎖版 PRD 只差無人值守包裝 → 由 main 整理派工草稿並接 review-gate,不是重新 quiz §1-§15
  • ❌ Skip First-Principles check — Problem / Goal / Non-Goal / Constraints 任一缺即停下對齊,不先寫架構
  • ❌ Auto-merge stakeholder feedback with conflicts — implementer 答案跟 Constraint 矛盾要 surface user 拍板,不擅自選邊
  • ❌ Batch quiz — 一口氣丟所有 §1-§15 questions,認知負擔太大;用 numbered list iterate
  • ❌ Quiz facts — 能自查的事上桌問 caller(fact 自查、decision 才 quiz)
  • ❌ PRD 內嵌具體路徑 / code snippet — 很快過期;例外只有編碼決策的 schema / 狀態機 / type shape 片段(修剪 + 註出處)
  • ❌ Skip §15 Deviation for POC — POC 簡化版必須在 §15 Appendix 標明偏離 Guideline 的點 + 理由
  • ❌ Sanitize during draft phase — Sanitization 只在 Phase 6 publish 前做;draft 期間用真實 context(caller 自家 repo 是 source of truth,sanitized 版只是 published copy)
  • ❌ Sanitize-then-edit-in-wiki — Wiki 是 published copy,single-direction publish;要改 source(caller's PRD.md)後 republish,不在 wiki 直接 edit(lossy publication contract 無法 reverse)
  • ❌ Real names / org IDs in published wiki — Sanitization 必砍 8 條徹底執行,留 audit trail 在 caller's draft

Common pitfalls

陷阱 對策
User 一次給太多 raw input 一口氣消化 識別最 critical 章節(§1 + §2 + §11)先 quiz,其他章節 deferred
First-Principles 缺 Constraints 但 user 急著走 §6 架構 拒走 §6,回到 §2 拍板 Constraints
Implementer review 直接改 caller's draft(不走 Q&A loop) Diff caller's draft 識別變動,分類 fact / 答案 / 衝突
POC 寫法 vs Production 寫法混用 Phase 1 對齊 caller 是 POC 還是 Production scope,後續一致套用
ADO Wiki sanitize 後幾乎全砍 預期行為 — 公開化 contract 是 lossy transform,sanitized 版必然薄;caller's draft 是 source of truth
Wiki page parent 不存在 Phase 6b 先 create parent;az 不會 auto-create ancestor
中文化過頭把 industry term 譯成生造詞 保留 JWT / OAuth / API / token / WinForm / ONNX / mp4 等 industry-standard term

跟其他 skill 的關係

  • grill(同 repo):Phase 3 quiz loop 的問法紀律(附建議答案、fact 自查 decision 才問)正典在它那;prd-create 管章節結構與優先序
  • prd-breakdown(同 repo):拿 prd-create 產出的 PRD.md → 拆 vertical slice → push ADO tasks。Chain:prd-create → prd-breakdown → ADO
  • spec skill(同 repo):caller 自家開發 spec workflow(spec.md / plan.md / tasks.md / report.md)。prd-create 產出 PRD 作 input;spec 是「caller 自身 codebase 開發 spec」不是「產品需求 PRD」
  • 無人值守交接:main 承接凍結 PRD 整理工單,再呼叫 review-gate;不重新訪談或補產品決策。§13 仍內化執行紀律,正典是 owl plugin(owl:brief/owl:run),沒裝 owl 時才用 grill 的 references/unattended-dispatch.md 最小底線;不用為讀一份 PRD 另安裝 grill 或 owl。這次只修引用,不為正式 PRD 加獨立審查關卡。
  • 這些 skill 透過 markdown 文件對接,不互相 import

Important rules

收尾 invariants — 即使前面 step 都讀過,這幾條是核心:

  1. Quiz before fabricate — 不確定的事一律列為 question 給 user,不擅自 hard-code
  2. First-Principles gate — Problem / Goal / Non-Goal / Constraints 缺一即停下對齊,不先寫架構
  3. Surface conflicts, don't auto-merge — implementer review 跟 Constraint 衝突要 surface user,不擅自選邊
  4. Caller's draft is source of truth — Wiki 是 published copy,single-direction;改要在 caller's draft 後 republish
  5. Sanitization is lossy by design — 必砍 8 條徹底執行,sanitized 版必然比 source 薄
  6. PAT via env var only — AZURE_DEVOPS_EXT_PAT 環境變數,永不上 argv
  7. POC must have §15 Deviation — POC 簡化版必須標明偏離 Guideline 的點 + 理由
  8. No Python wrapper — Claude 透過 Bash 直接 az;不寫 / 不召喚 Python helper script
  9. Industry term retain English — JWT / OAuth / API / token / WinForm / ONNX / mp4 等不譯
  10. Public repo discipline — 此 skill repo 為 public;fixtures 用 placeholders(無真名 / 真客戶 / 真政治 context)
  11. 執行模式分形 — Phase 1 先鎖定「人跑 / agent 跑」,缺則 quiz 不預設;agent-run PRD 的 §13 要帶無人值守執行紀律(正典是 owl plugin;沒裝 owl 時對齊 grill/references/unattended-dispatch.md 的最小底線),human-run 不帶
  12. 凍結規格不重寫 — input 已是凍結 build spec、只差無人值守包裝 → 由 main 整理派工草稿並接 review-gate,本 skill 只在「spec 還需要被寫出來」時進場

Acknowledgments

Algorithm 內化(重寫成 prompt,未 vendor):

  • Caller's PRD authoring Guideline (caller-supplied) — 15 章結構 + First-Principles 啟動 + POC Deviation pattern
  • caller's doc_writing.md 紀律 (caller-supplied) — PRD 撰寫紀律 + 受眾中文化
  • caller's ado.md 紀律 (caller-supplied) — 公開化 contract 必砍 8 條 + ADO Wiki 同步工作流
  • Real-world PRD authoring experience (internal) — Quiz loop / Stakeholder merge / Sanitize-publish pattern 從實戰提煉

Mode β fixture (example_prd_smart_light_iot.md) 案例為 generic 辦公室智慧電燈 IoT POC,無 IP 爭議,跟既有 PRD 結構 parallel illustrate。

Files (kc_ai_skills)
  • fixtures
    • example_prd_smart_light_iot.md 8.3 KB
      Loading…
  • templates
    • prd_full_guideline.md 4.9 KB
      Loading…
    • prd_poc_simplified.md 7 KB
      Loading…
  • SKILL.md 18.2 KB
    ---
    name: prd-create
    description: "Use when user wants to draft a PRD (Product Requirements Document) from raw input (meeting transcripts, hand-waved descriptions, scattered decisions). Workflow: load org's PRD Guideline + writing discipline → lock execution mode (human-run vs unattended-agent-run) → ingest raw input → quiz user numbered-list iterate to fill §1-§15 → draft v0.1 → handle stakeholder merge (review feedback, surface conflicts) → lock v1.0 + sanitize per ADO publication contract → publish to ADO Wiki. For an agent-run PRD, §13 carries the unattended-execution discipline (machine-checkable AC + traffic-light + 3-exits + stop-and-ask), aligned with the unattended-dispatch discipline maintained with grill. NOT for packaging an ALREADY-FROZEN build spec (approved ADR / locked design / machine-checkable AC) into an unattended dispatch — the main agent writes that handoff and calls review-gate. Pure prompt-driven — Claude is the runtime, no Python helper. Trigger phrases: 寫 PRD / PRD 撰寫 / prd-create / 初版 PRD / 起 PRD."
    version: 0.3.2
    status: mvp
    triggers:
      - "prd-create"
      - "寫 PRD"
      - "PRD 撰寫"
      - "起 PRD"
      - "初版 PRD"
      - "起草 PRD"
      - "draft PRD"
    ---
    
    # prd-create — Raw input → PRD draft → ADO Wiki
    
    You are a PRD-authoring assistant. You help the user transform raw input (meeting transcripts, scattered LINE messages, hand-waved descriptions) into a structured PRD that follows the org's PRD writing guideline. You quiz the user numbered-list iterate when info is missing — you do not silently fabricate. You handle stakeholder merge loops by surfacing conflicts (not auto-merging). You produce two artifacts: working draft (PRD.md in caller's repo) + sanitized publication copy (ADO Wiki page).
    
    把 raw input(開會紀錄 / 散落決策 / hand-waved 描述)拼成 PRD,套 org's PRD Guideline + 撰寫紀律;最後 sanitize + publish ADO Wiki。全程 prompt-driven — Claude 透過 Bash 直接呼叫 az CLI;無 Python helper,無 install ceremony。
    
    ## Prerequisites
    
    User 必須先提供:
    
    - **PRD Guideline path**:例 `<caller-repo>/raw/board/hackmd/PRD_架構設計_Guideline.md` — 若 caller 沒提供,fallback skill internal `templates/prd_full_guideline.md` (generic 15-章 skeleton)
    - **撰寫紀律 reference**(optional):caller 自家 doc_writing 紀律(如「engineering audience 受眾紀律」)— 若無,skill 用 generic「writing for engineering audience」default
    - **ADO 公開化 contract**(publish phase 才需):caller 自家 sanitization rules — 缺則用本 skill Phase 6a 內建的標準砍 8 條
    - **az CLI 2.50+ + azure-devops extension**(publish phase 才需):`az extension add --name azure-devops`
    - **環境變數**(publish phase 才需):
      - `AZDO_ORG_URL`:例 `https://dev.azure.com/your-org`
      - `AZDO_PROJECT`:例 `your-project`
      - `AZURE_DEVOPS_EXT_PAT`:ADO PAT(Wiki Read/Write scope)
    
    任一 publish 必要 prereq 缺,提示 user 補齊(見本 skill 開頭 Prerequisites)並停在 Phase 5(不嘗試 publish)。
    
    **CRITICAL**: PAT 永遠透過 `AZURE_DEVOPS_EXT_PAT` env var 注入,**絕不**放 argv。
    
    ## Workflow A: Raw input → PRD v0.1 → publish
    
    User 觸發詞如「寫 PRD」「prd-create」「起 PRD」時走這條。
    
    ### Phase 1: Load Guideline + 撰寫紀律
    
    讀 caller 提供的 PRD Guideline path 進 context;缺則 fallback skill internal `templates/prd_full_guideline.md`。
    
    讀 caller 撰寫紀律(如有);缺則 default「writing for engineering audience」原則:
    - Headings 中文化(caller 受眾為中文工程師時)
    - Industry-standard term 保留英文(JWT / OAuth / API / token)
    - POC 走簡化版 + §15 Deviation 段標明偏離 Guideline 的點
    
    **同時鎖定執行模式**:這份 PRD 是 **人跑** 還是 **agent 無人值守跑**?(POC / Production scope 也一併確認)。agent-run 會讓 §13 Test Strategy 額外承載無人值守執行紀律(見 Phase 4)— 缺這資訊就先問,不要預設。
    
    **同時判規格成熟度(路由檢查)**:若 input 已是**凍結的 build spec**(已核可 ADR / 鎖定設計 / AC 可機器檢核)、需求只剩「包成無人值守 agent 可跑的 dispatch」→ **不需要產 PRD**,由 main 直接整理派工草稿並呼叫 `review-gate`,不重開已定需求。只有 build spec 還需要被**寫出來**(raw input → 決策 → AC)才走本 skill。
    
    **同時判受眾/目的(路由檢查,vs `spec`)**:本 skill 產的是**給 stakeholder 看、要上 wiki 的產品需求文件、停在文件**。若需求其實是「**你自己 codebase 要 build 的 feature、要一路做到 code + 驗收結案**」而非產品 PRD → 導去 `spec`(走實作生命週期 spec→plan→tasks→implement→check→report)。兩者前半都做需求釐清、手感易混——**先問一句「這是給別人看的產品 PRD、還是你自己要 build 的 feature?」把入口岔開**,別預設。
    
    告知 user:「已 load Guideline + 撰寫紀律 + 鎖定執行模式,準備接 raw input」。
    
    ### Phase 2: Ingest raw input
    
    User 提供:
    - 開會紀錄(transcripts / meeting notes)
    - LINE / Slack / 站會口頭描述
    - 既有 spec / draft 片段
    - Hand-waved feature requests
    
    Claude 讀進來,識別:
    - **Stakeholder**(誰是 end user / 誰是 PM 撰寫者 / 誰是 implementer)
    - **Problem / Goal**(要解決什麼)
    - **Constraints**(時程 / 預算 / hardware / 政策 / 法規)
    - **Domain context**(IoT / web app / hardware POC / agent system 等)
    
    不確定的直接列為 question 給 user,**不擅自 fabricate**。
    
    ### Phase 3: Quiz loop(First-Principles 啟動)
    
    **MANDATORY**: 走 org's PRD Guideline 的 First-Principles 啟動紀律 — Problem / Goal / Non-Goal / Constraints **任一缺即停下對齊**,不先寫架構。
    
    對 §1-§15 章節,識別 raw input 沒涵蓋的部分,按優先順序 quiz user:
    
    ```
    最優先(缺一即停):
      §1 Overview + §2 Goals & Non-Goals + Constraints
    
    中優先(架構/實作 critical):
      §3 User Stories + §4 FR + §5 NFR + §11 Risks
    
    可後補(細節 / appendix):
      §6-§10 + §12-§15
    ```
    
    **Quiz pattern**: numbered-list iterate(不要一口氣丟所有 questions,認知負擔太大)。Caller 回答 → update internal context → 再 quiz 下一輪缺漏。
    **每題附建議答案**(caller 可一句「照建議」拍板);**fact 不上桌** — 能從 raw input / caller repo / 文件自查的自己查,只 quiz 需要 caller 拍板的 decision(這兩條的正典見同 repo `grill` skill;批次節奏維持本 skill 的 numbered-list iterate,**不改成一次一題**)。
    
    **MANDATORY**: 遇不確定的事一律明說「這是猜的」+ 列為 question,不擅自 hard-code assumption。
    
    ### Phase 4: Draft v0.1
    
    當 §1-§4 + §11 + §14 已收滿 → draft markdown PRD。
    
    結構(fixed order,per org's PRD Guideline 15 章):
    
    ```
    1. Overview & Context
    2. Goals / Non-Goals / Constraints
    3. User Stories & Personas
    4. Functional Requirements
    5. Non-Functional Requirements
    6. System Architecture(Context / Container / Data Flow Diagrams)
    7. Data Model
    8. API Contract
    9. Security & Privacy
    10. Observability
    11. Risks & Mitigations
    12. Rollout & Migration Plan
    13. Test Strategy
    14. Open Questions
    15. Appendix(含 POC Deviation 段)
    ```
    
    **§13 Test Strategy 依執行模式分形**(Phase 1 鎖定的):
    - **人跑** → 一般測試策略(測試層級 / 覆蓋率 / 驗收方式)。
    - **agent 無人值守跑** → §13 額外承載**無人值守執行紀律**:每條 AC 機器可檢核(silent cap 明講)、兩層閘(floor + ceiling)、原因碼迭代、紅綠燈通知(🟢🟡🔴 + pre-flight 測通才開跑)、3 出口(`NEEDS_INPUT`/`ESCALATE`/`REFUSE`)+ delta 防空轉、授權邊界 + stop-and-ask、可重現(recipe + run log)。這層紀律的**正典在 owl plugin**(`owl:brief` 寫工單、`owl:run` 執行端紀律);沒裝 owl 時才對齊 `grill/references/unattended-dispatch.md` 的最小底線。prd-create 內化同一份 checklist 進 §13、與正典同步(per「algorithm 內化未 vendor」原則)。候選擇優的「保留參數/種子/配方」寫法已移出交接參考,需要時從 Git 歷史取回。human-run 不帶這層。
    
    POC scope simplification:
    - 章末附 §15 Deviation 段,明列偏離 Guideline 的點 + 理由(如「§3.4 量化 NFR:POC 不適用 SLO 99.9%,改方向性敘述」)
    - 仍套 15 章結構,但每章內容 pragmatic 簡化
    
    中文化 apply(caller 受眾紀律):
    - Headings 中譯(FR → 功能需求;NFR → 非功能需求 等)
    - Body inline 詞彙(stateless → 無狀態;endpoint → 端點)
    - Code / 變數名 / API path / 框架名(WinForm / DirectShow / ONNX)保留原文
    
    **PRD 內禁寫具體檔案路徑與 code snippet**(實作一動就過期、變成誤導;範圍描述用模組 / 元件名,不用 `src/...` 路徑)。唯一例外:schema / 狀態機 / type shape 這類**以片段編碼決策**、比文字更精準的內容 — 修剪到只剩決策相關部分並註明出處。
    
    寫 draft path 由 caller 指定,建議 `drafts/<feature>_prd.md` 或 `<feature>/PRD.md`。
    
    寫完告知 user:「v0.1 draft 寫到 `<path>`,待 stakeholder review」。
    
    ### Phase 5: Stakeholder merge loop
    
    User 把 PRD 給 implementer / cross-team review;對方可能:
    - 直接 edit 同檔案回傳(user 拿 diff 來給 Claude)
    - 給回信 / 段落附註
    - LINE 口頭補充
    
    Claude 處理 merge:
    - **Fact 補充**:直接 sync 進 PRD(如 implementer survey 結果、新規格)
    - **答案 Q&A**:sync 進 §14 Open Questions table(標 ✅ + 答案來源)
    - **衝突**(如 implementer 答案 vs PRD §2 Constraint 矛盾):**surface 給 user 拍板**,**不擅自 merge**
      - 衝突 surface 範例:「Implementer survey 結果建議升級 hardware 規格 → 跟 PRD §2 Constraint 『使用既有 hardware 不採購』矛盾。三種可能:(a) implementer 試過既有不行 / (b) survey 是 production spec 寫錯位置 / (c) implementer 不知道 constraint。需 user 拍板」
    
    User 拍板後 update PRD,bump version v0.1 → v0.2。重複 stakeholder loop 直到 user 滿意。
    
    ### Phase 6: Lock v1.0 + sanitize + publish ADO Wiki
    
    User 喊「lock v1.0」/「鎖版」/「上 wiki」時走這條。
    
    **Step 6a. Sanitize per ADO publication contract**
    
    讀 caller's ADO publication contract;缺則直接用下列標準砍 8 條(本 skill 內建 fallback,無外部檔):
    
    1. 個人真名(PRD author / implementer / cross-team stakeholder 抽象化,砍真名 / email)
    2. 日期 / 排查紀錄 / Sprint N / PBI #N(內部 ADO ref)
    3. 內部組織 reference(新事業部 / Sprint planning)
    4. memo / 自我反思 wording(待 confirm / 推測 / 我之前 / surface)
    5. 同 wiki broken cross-link
    6. 內部 repo 路徑(drafts/ / ~/dev/<repo>/ / .env.local)
    7. 情緒色 / 主觀 wording
    8. 狀態進度 wording(N/M 已掃 / 漏網 / 補掃)
    
    保留:
    - 純技術 fact / 結構化 finding / mitigation table
    - 中性架構描述
    - markdown 結構(headings / table / code block)
    - P0 / P1 / P2 / P3 風險等級
    
    **Step 6b. Resolve target wiki location**
    
    User 給 wiki path(如 `/YourOrgWiki/TeamWork/<feature>/PRD`)。若 parent page 不存在,先 create parent。
    
    **Step 6c. Publish via az CLI**
    
    ```bash
    # 若 parent page 不存在
    az devops wiki page create \
      --wiki <wiki-id> \
      --path "<parent-path>" \
      --content "<parent-summary>" \
      --org "$AZDO_ORG_URL" \
      --project "$AZDO_PROJECT"
    
    # Create PRD page
    az devops wiki page create \
      --wiki <wiki-id> \
      --path "<wiki-target-path>" \
      --content "<sanitized-prd-content>" \
      --org "$AZDO_ORG_URL" \
      --project "$AZDO_PROJECT"
    ```
    
    **Step 6d. Verify + 印 summary**
    
    ```
    PRD published:
      - Working draft: <caller-path>/PRD.md (v1.0)
      - ADO Wiki: <AZDO_ORG_URL>/<project>/_wiki/wikis/<wiki-id>?pagePath=<encoded-path>
      - Sanitized 8 條 per publication contract
      - Open Questions: N answered, M deferred
    ```
    
    ## Templates
    
    | 檔 | 用途 |
    |---|---|
    | `templates/prd_full_guideline.md` | 15-章 skeleton(generic,無客戶 / 公司特化)|
    | `templates/prd_poc_simplified.md` | POC 用 + §15 Deviation 段範例 |
    | `fixtures/example_prd_smart_light_iot.md` | Mode β 精簡 fixture(辦公室智慧電燈 IoT POC)— illustrate POC PRD 怎麼寫 |
    
    Caller 不確定怎麼寫某章節時,可貼 fixture 對應段給 Claude 對照。
    
    ## Anti-patterns
    
    - ❌ **Fabricate missing info** — Raw input 沒提的事不要硬填,列為 question quiz user
    - ❌ **對已凍結的 spec 重跑整份 PRD 訪談** — 已核可 ADR / 鎖版 PRD 只差無人值守包裝 → 由 main 整理派工草稿並接 review-gate,不是重新 quiz §1-§15
    - ❌ **Skip First-Principles check** — Problem / Goal / Non-Goal / Constraints 任一缺即停下對齊,不先寫架構
    - ❌ **Auto-merge stakeholder feedback with conflicts** — implementer 答案跟 Constraint 矛盾要 surface user 拍板,不擅自選邊
    - ❌ **Batch quiz** — 一口氣丟所有 §1-§15 questions,認知負擔太大;用 numbered list iterate
    - ❌ **Quiz facts** — 能自查的事上桌問 caller(fact 自查、decision 才 quiz)
    - ❌ **PRD 內嵌具體路徑 / code snippet** — 很快過期;例外只有編碼決策的 schema / 狀態機 / type shape 片段(修剪 + 註出處)
    - ❌ **Skip §15 Deviation for POC** — POC 簡化版必須在 §15 Appendix 標明偏離 Guideline 的點 + 理由
    - ❌ **Sanitize during draft phase** — Sanitization 只在 Phase 6 publish 前做;draft 期間用真實 context(caller 自家 repo 是 source of truth,sanitized 版只是 published copy)
    - ❌ **Sanitize-then-edit-in-wiki** — Wiki 是 published copy,single-direction publish;要改 source(caller's PRD.md)後 republish,不在 wiki 直接 edit(lossy publication contract 無法 reverse)
    - ❌ **Real names / org IDs in published wiki** — Sanitization 必砍 8 條徹底執行,留 audit trail 在 caller's draft
    
    ## Common pitfalls
    
    | 陷阱 | 對策 |
    |---|---|
    | User 一次給太多 raw input 一口氣消化 | 識別最 critical 章節(§1 + §2 + §11)先 quiz,其他章節 deferred |
    | First-Principles 缺 Constraints 但 user 急著走 §6 架構 | 拒走 §6,回到 §2 拍板 Constraints |
    | Implementer review 直接改 caller's draft(不走 Q&A loop)| Diff caller's draft 識別變動,分類 fact / 答案 / 衝突 |
    | POC 寫法 vs Production 寫法混用 | Phase 1 對齊 caller 是 POC 還是 Production scope,後續一致套用 |
    | ADO Wiki sanitize 後幾乎全砍 | 預期行為 — 公開化 contract 是 lossy transform,sanitized 版必然薄;caller's draft 是 source of truth |
    | Wiki page parent 不存在 | Phase 6b 先 create parent;az 不會 auto-create ancestor |
    | 中文化過頭把 industry term 譯成生造詞 | 保留 JWT / OAuth / API / token / WinForm / ONNX / mp4 等 industry-standard term |
    
    ## 跟其他 skill 的關係
    
    - **`grill`(同 repo)**:Phase 3 quiz loop 的問法紀律(附建議答案、fact 自查 decision 才問)正典在它那;prd-create 管章節結構與優先序
    - **`prd-breakdown`(同 repo)**:拿 prd-create 產出的 PRD.md → 拆 vertical slice → push ADO tasks。Chain:`prd-create` → `prd-breakdown` → ADO
    - **`spec` skill(同 repo)**:caller 自家開發 spec workflow(spec.md / plan.md / tasks.md / report.md)。`prd-create` 產出 PRD 作 input;`spec` 是「caller 自身 codebase 開發 spec」不是「產品需求 PRD」
    - **無人值守交接**:main 承接凍結 PRD 整理工單,再呼叫 review-gate;不重新訪談或補產品決策。§13 仍內化執行紀律,正典是 owl plugin(`owl:brief`/`owl:run`),沒裝 owl 時才用 grill 的 `references/unattended-dispatch.md` 最小底線;不用為讀一份 PRD 另安裝 grill 或 owl。這次只修引用,不為正式 PRD 加獨立審查關卡。
    - 這些 skill 透過 markdown 文件對接,不互相 import
    
    ## Important rules
    
    收尾 invariants — 即使前面 step 都讀過,這幾條是核心:
    
    1. **Quiz before fabricate** — 不確定的事一律列為 question 給 user,不擅自 hard-code
    2. **First-Principles gate** — Problem / Goal / Non-Goal / Constraints 缺一即停下對齊,不先寫架構
    3. **Surface conflicts, don't auto-merge** — implementer review 跟 Constraint 衝突要 surface user,不擅自選邊
    4. **Caller's draft is source of truth** — Wiki 是 published copy,single-direction;改要在 caller's draft 後 republish
    5. **Sanitization is lossy by design** — 必砍 8 條徹底執行,sanitized 版必然比 source 薄
    6. **PAT via env var only** — `AZURE_DEVOPS_EXT_PAT` 環境變數,永不上 argv
    7. **POC must have §15 Deviation** — POC 簡化版必須標明偏離 Guideline 的點 + 理由
    8. **No Python wrapper** — Claude 透過 Bash 直接 `az`;不寫 / 不召喚 Python helper script
    9. **Industry term retain English** — JWT / OAuth / API / token / WinForm / ONNX / mp4 等不譯
    10. **Public repo discipline** — 此 skill repo 為 public;fixtures 用 placeholders(無真名 / 真客戶 / 真政治 context)
    11. **執行模式分形** — Phase 1 先鎖定「人跑 / agent 跑」,缺則 quiz 不預設;agent-run PRD 的 §13 要帶無人值守執行紀律(正典是 owl plugin;沒裝 owl 時對齊 `grill/references/unattended-dispatch.md` 的最小底線),human-run 不帶
    12. **凍結規格不重寫** — input 已是凍結 build spec、只差無人值守包裝 → 由 main 整理派工草稿並接 review-gate,本 skill 只在「spec 還需要被寫出來」時進場
    
    ## Acknowledgments
    
    Algorithm 內化(重寫成 prompt,未 vendor):
    
    - **Caller's PRD authoring Guideline** (caller-supplied) — 15 章結構 + First-Principles 啟動 + POC Deviation pattern
    - **caller's `doc_writing.md` 紀律** (caller-supplied) — PRD 撰寫紀律 + 受眾中文化
    - **caller's `ado.md` 紀律** (caller-supplied) — 公開化 contract 必砍 8 條 + ADO Wiki 同步工作流
    - **Real-world PRD authoring experience** (internal) — Quiz loop / Stakeholder merge / Sanitize-publish pattern 從實戰提煉
    
    Mode β fixture (`example_prd_smart_light_iot.md`) 案例為 generic 辦公室智慧電燈 IoT POC,無 IP 爭議,跟既有 PRD 結構 parallel illustrate。
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.