tea-sdlc/prompts/sdlc-analyze.md

name: sdlc-analyze description: 僅由 /sdlc-analyze 指令叫用。對一顆需求議題執行可行性檢查，逐題問到共識後產生工作包議題並排上時程。

sdlc-analyze

對一顆需求議題執行可行性檢查，把疑點一題一題問到雙方有共識，再把共識變成一批工作包議題。

分成三段：可行性分析到共識摘要為止，除了起錶之外完全不寫入 Gitea；使用者看過摘要 點頭之後，才進入產生工作包建立議題；最後排上時程與看板，把相依、截止日、 Milestone、看板與人天估算補上。

這份檔案是流程正本。各平台的轉接檔只是指回這裡，不要把規則抄過去。

輸入

一個需求議題編號。

計時範圍

錶起在它分析的那顆需求議題上：在「起錶」那一步起，在「停錶並回報」那一步停， 涵蓋整道 /sdlc-analyze。

起點放在第一段開頭，因為分析最耗時的正是共識之前那一段——四類疑點逐題問到收斂。 從第二段才起錶的話，那段時間永遠是零，而報表上「分析不花時間」會直接餵給下一次估算。

錶已經跑在同一顆議題上時起錶什麼都不做，所以 plan 接著跑 analyze 不會把累積的時間 切成兩段。錶不跨階段跑，也不碰別顆議題上的錶。

第一段：可行性分析

1. 讀議題

node scripts/issue-extract.js --repo <owner/name> --index <編號>

拿到的是結構化欄位，不必再讀整份議題全文。

先看 未處理留言數。 只要不是 0，就代表議題描述可能是過期的——留言裡有決策還沒被 整併回描述。這時先停下來告訴使用者有幾則未整併的留言，問他要不要現在整併。

要整併的話直接走 /sdlc-sync 的流程（prompts/sdlc-sync.md），做完自動接回這裡： 重新抽取一次拿到更新後的描述，再往下走。不要要求使用者重打指令——他已經說要整併了。

使用者選擇不整併就繼續，但要記下這件事，並在共識摘要裡註明「分析基於未整併留言前的描述」。

2. 起錶

議題確認存在之後，在這顆需求議題上起錶：

node scripts/timer.js --repo <owner/name> --index <需求議題編號> --dry-run

確認無誤後拿掉 --dry-run 再跑一次。錶已經跑在同一顆上時它什麼都不做，重跑不會把 已經累積的時間切成兩段。

錶跑在別顆議題上時會被擋下（STOPWATCH_ON_OTHER_ISSUE）。照實告訴使用者是哪一顆， 請他自己去停，不要代勞：那一段時間該記在哪顆議題上只有他知道。順帶說明停錶不會動到 任何既有的工作樹——碼錶只管時間、工作樹只管檔案。

3. 對四份清單列出疑點

依序讀這四份規則正本，逐條對照議題內容：

1. references/feasibility-architecture.md — 架構：放錯 repo、循環相依、穿越邊界。
2. references/feasibility-logic.md — 邏輯：既有功能是不是已經做過同一件事。
3. references/feasibility-data.md — 資料：schema 變更、遷移、交易邊界。
4. references/feasibility-schedule.md — 時程：相依鏈最長路徑、未知數最大的一項。

每一條檢查若在議題裡找不到答案，就轉成一個問題。能在程式碼裡查證的就自己去查， 不要拿去問使用者——把問題留給只有人能回答的事。

4. 逐題問到共識

一次問一題。 問完等使用者回答，再問下一題，讓他能看著前一題的答案回答下一題。 不要一次丟出五個問題，也不要把多個問題包成一題的多個選項。

順序固定為架構 → 邏輯 → 資料 → 時程，前一類的問題全部清空才進入下一類。 前面的答案常常會讓後面的問題消失或改寫；每問完一題，重新檢視剩下的問題還成不成立。

每一題固定給兩個選項：

• 建議 — 你的答案，附上理由。理由要寫「為什麼是這個」，不是複述問題。
• 手動輸入 — 讓使用者自己寫。任何一題都必須能手動作答，不被選項限制。

問題本身要具體到能用一句話回答。問不出收斂答案的問題，多半是問題本身太大，拆開再問。

5. 輸出共識摘要

全部問完後，輸出一份摘要讓使用者做最後確認，內容包含：

• 每一類的結論 — 架構／邏輯／資料／時程各自問出了什麼，逐條列出「問題 → 答案」。
• 改變了什麼 — 分析過程中翻掉或修正了需求議題裡的哪些假設。
• 仍然未決的事 — 問了但沒有答案、或使用者明確說「之後再說」的事。
• 人天估算 — 每一項的估算與最沒把握的那一項。

摘要只印在終端，不寫回議題、不建立任何東西。使用者看過點頭之後，才進入下一段。

第二段：產生工作包

使用者對共識摘要點頭之後才開始。 摘要沒有經過確認就不要往下走。

6. 切出工作包

把需求切成幾顆工作包。一顆工作包是開發者拿了就能動手、做完有明確結果的單位： 它有自己的驗收標準，做完能單獨被檢視，不必等別的工作包一起才看得出成果。

切的依據是第一段問出來的共識，特別是時程清單那份暫定拆法——那本來就是這一段的草稿。

標題格式為「{動詞}{名詞}」，例如「建立工作包的抽取契約」、「產生圖解版總覽網頁」。 禁止流水編號與任何無意義代號（WP-01、任務三、第一階段）：命名本身就要說明用途， 看標題就知道這顆在做什麼，不必點進去。

7. 組出每顆工作包的內容

套用 templates/work-package-issue.md，依序填滿九個段落：

1. 這個工作包在做什麼 — 一句話。讓人掃過標題與這一行就決定要不要點進來。

2. 描述 — 從使用者的角度說這顆做完之後什麼事變得可能，不要寫成逐層的實作清單。

3. 架構圖 — 見下方「架構圖的限制」。

4. 範圍邊界 — 明列不做什麼。這一段的用途是抵抗範圍蔓延，寫得越具體越有用。

5. 介面契約 — 表格，四欄：介面／產出者／消費者／形狀。讓人知道自己產出的東西誰會消費。 這顆不產出對外介面就寫一列「無」，不要留空表。

6. 待辦 — 巢狀結構：每一項待辦底下掛它自己的驗收標準，讓人知道這一項做到什麼程度算完成。

   - [ ] 建立共用函式庫
     - [ ] 具名 flag 解析可拒絕未知參數
     - [ ] 單行 JSON 輸出格式固定
   - [ ] 加上前置檢查
     - [ ] 四層各自回傳可區分的錯誤碼
   

   上層是待辦、縮排一層是該項的驗收，不要再往下巢狀。兩者都用 checkbox，實作時會被逐項勾選。

7. 整體驗收 — 整顆工作包做完才驗得出來的事，與個別待辦的驗收不重複。

8. repo 列表 — 這顆會動到哪些 repo。

9. 關聯 — 至少要有一行 需求議題：#<編號> 指回來源。阻擋、先決與人天估算由後續流程補上。

8. 先試跑，再寫入

每顆工作包各寫一個暫存檔，然後逐顆：

node scripts/issue-create.js --repo <owner/name> --title "<標題>" --body-file <暫存檔> \
  --labels "<標籤>" --dry-run

--dry-run 會印出將送出的請求、把標籤名稱換成 id，並在標題已存在時如實顯示「實跑會是 no-op」。確認無誤後拿掉該旗標再跑一次。

標籤一樣只能從 scripts/labels-list.js 回傳的既有標籤裡挑，不得自行建立新標籤。

中斷後重跑不會產生重複工作包：issue-create 以標題查重，發現同名議題就回傳既有那一顆 並把 created 設為 false。

9. 回報

列出每顆工作包的編號、標題與網址。不要把議題內容再貼一次。

這裡不停錶——指令還沒跑完，第三段還要排時程。停錶在最後的「停錶並回報」那一步。

第三段：排上時程與看板

工作包建好之後，把它們之間的關係與時程補上。做完這一段，看板上呈現的才是真實的 開發順序，而不是一堆平鋪的議題。

10. 算出截止日

把每顆工作包的編號、人天估算與先決關係寫成一份計畫檔：

{
  "startDate": "2026-09-21",
  "workPackages": [
    { "index": 12, "title": "建立共用函式庫", "days": 3 },
    { "index": 13, "title": "建立抽取契約", "days": 2, "depends": [12] }
  ]
}

node scripts/schedule.js --plan-file <計畫檔>

它依相依關係做拓撲排序，保證任一工作包的截止日都不早於它的先決——人工排時程 最常見的矛盾就是前置工作比後續還晚到期。相依成環時它會直接報錯並指出環上的成員， 那代表拆法有問題，回頭改拆法，不要硬排。

日期以日曆日累加，不跳週末也不扣假日。要跳的話自己把 startDate 或人天調整過再算。

11. 逐顆補上關係與時程

對每一顆工作包，依序：

node scripts/issue-link.js --repo <owner/name> --index <編號> --depends <先決編號清單>
node scripts/issue-update.js --repo <owner/name> --index <編號> \
  --milestone "<既有 Milestone 名稱>" --due-date <schedule 算出的日期> --estimate-days <人天>
node scripts/project-add.js --repo <owner/name> --index <編號> --project "<看板名稱或網址>"

三支都先用 --dry-run 看過再實跑。三支都是冪等的：相依已存在就跳過、已在看板上就不重發、 估算沒變就不改 body。

Milestone 與看板都只掛既有的。 指到不存在的 Milestone 會中止並列出可選項目； 看板名稱靠掃最近 50 筆議題反查 id，反查不到就會請你直接貼專案網址（結尾即 id）。 本流程不建立 Milestone，也不建立專案。

12. 產生分析版的圖解總覽

用同一份 templates/overview-artifact.html 再產一份，但這一份要多出工作包全景： 把工作包之間的相依與截止日畫成一張圖，讓開發者看得出自己這一項在整體中的位置。

全景圖用 graph TD，填進 {{工作包全景}}，連同段落標題一起：

<section><h2>工作包全景</h2>
<figure><div class="mermaid">graph TD
  A[建立共用函式庫<br/>09-25] --> B[建立抽取契約<br/>09-27]
</div></figure></section>

節點寫工作包標題與截止日，箭頭方向是「先決 → 後續」。節點一樣以 12 個為上限， 超過就只畫相依鏈最長路徑上的那幾顆，其餘在頁尾列成文字。

網址一樣寫回需求議題：

node scripts/issue-update.js --repo <owner/name> --index <需求議題編號> --overview-url <網址>

重跑會就地更新同一行，不會在議題上留下兩個連結。規劃階段產生的那一份會被這一份取代， 這是預期行為——同一顆需求議題只掛一個總覽網址。

13. 停錶並回報

回報之前先停錶，這一段計時到此為止：

node scripts/timer.js --repo <owner/name> --index <需求議題編號> --stop

它只停這一顆上的錶，與「起錶」那一步起的是同一顆。錶本來就沒在跑不算失敗 （碼錶已停 會是 false 並附一句說明），回報照樣做完。

列出每顆工作包的編號、標題、截止日與所屬 Milestone，並指出相依鏈最長路徑上的那幾顆 ——那條路徑決定整體交期。

已知限制：人天估算只寫得進 body

Gitea 1.27 的 API 沒有任何請求定義接受 time_estimate，該欄位只出現在議題的回應裡。 也就是說議題的估算欄位無法由 API 寫入，只能靠人在網頁上填。

因此 issue-update --estimate-days 只把估算寫成議題 body 裡人類可讀的一行 （估算人天：N，放在「關聯」段落）。之後 sdlc-report 要比對估算與實際工時時， 讀的也是這一行。

架構圖的限制

依工作包的性質選圖：

• sequenceDiagram — 重點在「誰呼叫誰、順序為何」時用。
• flowchart — 重點在「條件分支與資料流向」時用。
• stateDiagram-v2 — 重點在「狀態怎麼轉移」時用。

節點數上限 12，每個節點的文字上限 8 字。超過就拆成多張圖，或者乾脆不畫。

模板的 {{架構圖}} 要填入完整的內容，兩種形式擇一：

• 要畫：一個或多個完整的 ```mermaid 圍欄區塊。
• 不畫：只在超過上限拆不開、或畫了不會比文字更清楚時才選這個，填一行說明為什麼不畫，不要加圍欄。

邊界

• 共識摘要之前不對 Gitea 寫入任何內容：不建議題、不改描述、不貼標籤、不留留言。 碼錶除外——它記的是工時，不是內容；而分析最耗時的正是共識之前那一段，不從那裡 起錶，那段時間就永遠是零。
• 第二段只建立工作包議題。不建相依、不掛 Milestone、不加看板、不寫人天估算——那是第三段的事。
• 第三段只掛既有的 Milestone 與看板。不自行建立標籤、Milestone 或專案看板。
• 不修改使用者的專案檔案。查證既有功能時只讀不寫。
• 不替使用者決定他沒回答的事。問不到答案就進「仍然未決的事」。
• 計時只動這顆需求議題：在它上面起錶、在它上面停錶。不停別顆議題上的錶， 被別顆的錶擋下時交還給使用者決定，不繞過去。
• 不關閉或刪除任何既有議題。