jiantw83andClaude Opus 5
9a67c8074f
兩份正本原本都只寫「不畫：一行說明為什麼不畫」，讀起來像是隨時可以跳過。 議題 #1 的原意是「超過上限即拆圖或不畫」——退路是給畫不下的情況用的。 改成只在超過上限拆不開、或畫了不會比文字更清楚時才選，兩份正本一起改， 免得兩邊講法不同。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
154 lines
7.6 KiB
Markdown
154 lines
7.6 KiB
Markdown
name: sdlc-analyze
|
||
description: 僅由 /sdlc-analyze 指令叫用。對一顆需求議題執行可行性檢查，逐題問到共識後產生工作包議題。
|
||
|
||
# sdlc-analyze
|
||
|
||
對一顆需求議題執行可行性檢查，把疑點一題一題問到雙方有共識，再把共識變成一批工作包議題。
|
||
|
||
分成兩段：**可行性分析**到共識摘要為止，完全不寫入 Gitea；使用者看過摘要點頭之後，
|
||
才進入**產生工作包**，那一段才會建立議題。
|
||
|
||
這份檔案是流程正本。各平台的轉接檔只是指回這裡，不要把規則抄過去。
|
||
|
||
## 輸入
|
||
|
||
一個需求議題編號。
|
||
|
||
## 第一段：可行性分析
|
||
|
||
### 1. 讀議題
|
||
|
||
```
|
||
node scripts/issue-extract.js --repo <owner/name> --index <編號>
|
||
```
|
||
|
||
拿到的是結構化欄位，不必再讀整份議題全文。
|
||
|
||
**先看 `未處理留言數`。** 只要不是 0，就代表議題描述可能是過期的——留言裡有決策還沒被
|
||
整併回描述。這時**先停下來**告訴使用者有幾則未整併的留言，建議先執行 `/sdlc-sync`
|
||
把它們整併回描述，再回來做分析。使用者堅持要繼續就繼續，但要記下這件事，
|
||
並在共識摘要裡註明「分析基於未整併留言前的描述」。
|
||
|
||
### 2. 對四份清單列出疑點
|
||
|
||
依序讀這四份規則正本，逐條對照議題內容：
|
||
|
||
1. `references/feasibility-architecture.md` — 架構：放錯 repo、循環相依、穿越邊界。
|
||
2. `references/feasibility-logic.md` — 邏輯：既有功能是不是已經做過同一件事。
|
||
3. `references/feasibility-data.md` — 資料：schema 變更、遷移、交易邊界。
|
||
4. `references/feasibility-schedule.md` — 時程：相依鏈最長路徑、未知數最大的一項。
|
||
|
||
每一條檢查若在議題裡找不到答案，就轉成一個問題。**能在程式碼裡查證的就自己去查，
|
||
不要拿去問使用者**——把問題留給只有人能回答的事。
|
||
|
||
### 3. 逐題問到共識
|
||
|
||
**一次問一題。** 問完等使用者回答，再問下一題，讓他能看著前一題的答案回答下一題。
|
||
不要一次丟出五個問題，也不要把多個問題包成一題的多個選項。
|
||
|
||
順序固定為**架構 → 邏輯 → 資料 → 時程**，前一類的問題全部清空才進入下一類。
|
||
前面的答案常常會讓後面的問題消失或改寫；每問完一題，重新檢視剩下的問題還成不成立。
|
||
|
||
每一題固定給兩個選項：
|
||
|
||
- **建議** — 你的答案，附上理由。理由要寫「為什麼是這個」，不是複述問題。
|
||
- **手動輸入** — 讓使用者自己寫。任何一題都必須能手動作答，不被選項限制。
|
||
|
||
問題本身要具體到能用一句話回答。問不出收斂答案的問題，多半是問題本身太大，拆開再問。
|
||
|
||
### 4. 輸出共識摘要
|
||
|
||
全部問完後，輸出一份摘要讓使用者做最後確認，內容包含：
|
||
|
||
- **每一類的結論** — 架構／邏輯／資料／時程各自問出了什麼，逐條列出「問題 → 答案」。
|
||
- **改變了什麼** — 分析過程中翻掉或修正了需求議題裡的哪些假設。
|
||
- **仍然未決的事** — 問了但沒有答案、或使用者明確說「之後再說」的事。
|
||
- **人天估算** — 每一項的估算與最沒把握的那一項。
|
||
|
||
摘要只印在終端，**不寫回議題、不建立任何東西**。使用者看過點頭之後，才進入下一段。
|
||
|
||
## 第二段：產生工作包
|
||
|
||
**使用者對共識摘要點頭之後才開始。** 摘要沒有經過確認就不要往下走。
|
||
|
||
### 5. 切出工作包
|
||
|
||
把需求切成幾顆工作包。一顆工作包是**開發者拿了就能動手、做完有明確結果**的單位：
|
||
它有自己的驗收標準，做完能單獨被檢視，不必等別的工作包一起才看得出成果。
|
||
|
||
切的依據是第一段問出來的共識，特別是時程清單那份暫定拆法——那本來就是這一段的草稿。
|
||
|
||
**標題格式為「{動詞}{名詞}」**，例如「建立工作包的抽取契約」、「產生圖解版總覽網頁」。
|
||
**禁止流水編號與任何無意義代號**（`WP-01`、`任務三`、`第一階段`）：命名本身就要說明用途，
|
||
看標題就知道這顆在做什麼，不必點進去。
|
||
|
||
### 6. 組出每顆工作包的內容
|
||
|
||
套用 `templates/work-package-issue.md`，依序填滿九個段落：
|
||
|
||
1. **這個工作包在做什麼** — 一句話。讓人掃過標題與這一行就決定要不要點進來。
|
||
2. **描述** — 從使用者的角度說這顆做完之後什麼事變得可能，不要寫成逐層的實作清單。
|
||
3. **架構圖** — 見下方「架構圖的限制」。
|
||
4. **範圍邊界** — 明列**不做什麼**。這一段的用途是抵抗範圍蔓延，寫得越具體越有用。
|
||
5. **介面契約** — 表格，四欄：介面／產出者／消費者／形狀。讓人知道自己產出的東西誰會消費。
|
||
這顆不產出對外介面就寫一列「無」，不要留空表。
|
||
6. **待辦** — 巢狀結構：每一項待辦底下掛**它自己的**驗收標準，讓人知道這一項做到什麼程度算完成。
|
||
|
||
```
|
||
- [ ] 建立共用函式庫
|
||
- [ ] 具名 flag 解析可拒絕未知參數
|
||
- [ ] 單行 JSON 輸出格式固定
|
||
- [ ] 加上前置檢查
|
||
- [ ] 四層各自回傳可區分的錯誤碼
|
||
```
|
||
|
||
上層是待辦、縮排一層是該項的驗收，不要再往下巢狀。兩者都用 checkbox，實作時會被逐項勾選。
|
||
7. **整體驗收** — 整顆工作包做完才驗得出來的事，與個別待辦的驗收不重複。
|
||
8. **repo 列表** — 這顆會動到哪些 repo。
|
||
9. **關聯** — 至少要有一行 `需求議題：#<編號>` 指回來源。阻擋、先決與人天估算由後續流程補上。
|
||
|
||
### 7. 先試跑，再寫入
|
||
|
||
每顆工作包各寫一個暫存檔，然後逐顆：
|
||
|
||
```
|
||
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`。
|
||
|
||
### 8. 回報
|
||
|
||
列出每顆工作包的編號、標題與網址。不要把議題內容再貼一次。
|
||
|
||
## 架構圖的限制
|
||
|
||
依工作包的性質選圖：
|
||
|
||
- **`sequenceDiagram`** — 重點在「誰呼叫誰、順序為何」時用。
|
||
- **`flowchart`** — 重點在「條件分支與資料流向」時用。
|
||
- **`stateDiagram-v2`** — 重點在「狀態怎麼轉移」時用。
|
||
|
||
節點數上限 **12**，每個節點的文字上限 **8 字**。超過就拆成多張圖，或者乾脆不畫。
|
||
|
||
模板的 `{{架構圖}}` 要填入**完整的內容**，兩種形式擇一：
|
||
|
||
- 要畫：一個或多個完整的 ```mermaid 圍欄區塊。
|
||
- 不畫：**只在超過上限拆不開、或畫了不會比文字更清楚時**才選這個，填一行說明為什麼不畫，**不要加圍欄**。
|
||
|
||
## 邊界
|
||
|
||
- **共識摘要之前不對 Gitea 產生任何寫入**：不建議題、不改描述、不貼標籤、不留留言。
|
||
- 第二段只建立工作包議題。不建相依、不掛 Milestone、不加看板、不寫人天估算——那是後續流程的事。
|
||
- 不自行建立標籤、Milestone 或專案看板。
|
||
- 不修改使用者的專案檔案。查證既有功能時只讀不寫。
|
||
- 不替使用者決定他沒回答的事。問不到答案就進「仍然未決的事」。
|
||
- 不關閉或刪除任何既有議題。
|