jiantw83andClaude Opus 5
6b30552ee2
規劃版填總覽、目標、流程圖，工作包全景填空字串；分析版沿用同一份模板，額外把 工作包的相依與截止日畫成 graph TD 的全景圖。節點一樣以 12 個為上限，超過就只畫 相依鏈最長路徑上的那幾顆。 兩份都寫回同一顆需求議題的同一行，所以分析版會取代規劃版——同一顆需求議題只掛 一個總覽網址，這是預期行為，正本裡寫明免得被當成 bug。 另外交代填模板時流程圖不帶圍欄：圍欄是議題 markdown 用的，填進 HTML 會多出一段 沒有意義的字。 Closes #10 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
125 lines
5.8 KiB
Markdown
125 lines
5.8 KiB
Markdown
name: sdlc-plan
|
|
description: 僅由 /sdlc-plan 指令叫用。把一段口語需求轉成結構化的需求議題，寫入 Gitea。
|
|
|
|
# sdlc-plan
|
|
|
|
把使用者給的一段需求，變成一顆結構完整、下游指令讀得動的需求議題。
|
|
|
|
這份檔案是流程正本。各平台的轉接檔只是指回這裡，不要把規則抄過去。
|
|
|
|
## 輸入
|
|
|
|
使用者給的東西可能是下列任一種，也可能三種混用：
|
|
|
|
- **自由文字** — 一段口語描述。
|
|
- **規格檔** — 一個檔案路徑，內容是既有的規格或筆記。
|
|
- **議題編號** — 既有議題的編號，用來補充脈絡或作為延伸的起點。
|
|
|
|
先把三種來源讀齊，再開始問問題。規格檔用檔案讀取工具讀；議題編號用
|
|
`scripts/issue-extract.js` 取（若該腳本尚未可用，改用 `scripts/issue-create.js` 以外的
|
|
既有讀取途徑，並在摘要中註明資料來源）。
|
|
|
|
## 步驟
|
|
|
|
### 1. 讀齊輸入，列出還缺什麼
|
|
|
|
把九個段落逐一對照使用者給的材料，列出哪些段落已經有依據、哪些沒有。
|
|
|
|
### 2. 逐項詢問
|
|
|
|
**一次問一題**，等使用者回答完再問下一題，讓他能看著前一題的答案回答下一題。
|
|
|
|
每一題都附上你的建議與理由，讓使用者多數時候只要點頭；同時保留讓他自己寫答案的餘地。
|
|
|
|
**未獲得答覆的欄位不得自行編造。** 使用者沒說過的目標、沒提過的驗收標準，一個字都不能自己
|
|
填。問不到就放進「未決事項」，那一段本來就是給未決的東西用的。
|
|
|
|
### 3. 組出議題內容
|
|
|
|
套用 `templates/requirement-issue.md`，依序填滿九個段落：
|
|
|
|
1. **總覽** — 一句話講完這件事在做什麼，讓非技術的利害關係人不必讀完技術細節。圖解版總覽的
|
|
連結此時先留空，由後續流程回填。
|
|
2. **背景** — 不超過三行。為什麼現在要做這件事。
|
|
3. **目標** — 可量測。寫得出「怎樣算達成」才算數。
|
|
4. **非目標** — 明列這次不做什麼，用來抵抗範圍蔓延。
|
|
5. **領域名詞表** — 這份需求裡會反覆出現的詞，各給一行定義，讓團隊對同一個詞的理解一致。
|
|
6. **流程圖** — 見下方「流程圖的限制」。
|
|
7. **驗收標準** — 逐條列出，每一條都要能被驗證。
|
|
8. **影響範圍** — 會動到哪些 repo、哪些既有功能。
|
|
9. **未決事項** — 問不到答案、或需要他人拍板的事。
|
|
|
|
### 4. 挑標籤
|
|
|
|
先用 `scripts/labels-list.js --repo <owner/name>` 取得該 repo 的既有標籤，**只能從這份清單裡
|
|
挑**。找不到合適的就不貼。**不得自行建立新標籤** —— 標籤體系由專案維護者決定，不該在多個
|
|
repo 之間長出雜草。
|
|
|
|
### 5. 先試跑，再寫入
|
|
|
|
把組好的內容寫到一個暫存檔，然後：
|
|
|
|
```
|
|
node scripts/issue-create.js --repo <owner/name> --title "<標題>" --body-file <暫存檔> \
|
|
--labels "<標籤1,標籤2>" --dry-run
|
|
```
|
|
|
|
`--dry-run` 會印出將要送出的請求而不真的寫入。確認無誤後拿掉該旗標再跑一次。
|
|
|
|
同一段需求重跑不會產生第二顆議題：`issue-create` 以標題查重，發現同名議題就回傳既有那一顆
|
|
並把 `created` 設為 `false`。
|
|
|
|
### 6. 產生圖解版總覽
|
|
|
|
套用 `templates/overview-artifact.html`，把議題的總覽、目標與流程圖填成一份可以直接投影的
|
|
網頁。這一份是給**非技術的利害關係人**看的：他們不必讀完技術細節就知道這件事在做什麼。
|
|
|
|
模板的佔位對應如下，樣式不要動——版面與內容分開，改一邊不必碰另一邊：
|
|
|
|
- `{{標題}}` 需求議題標題
|
|
- `{{來源議題}}` 指回議題的連結
|
|
- `{{總覽}}` 一句話總覽
|
|
- `{{目標}}` 目標，逐條包成 `<li>`
|
|
- `{{流程圖}}` 流程圖的 Mermaid 原始碼（**不含**圍欄，圍欄是議題 markdown 用的）
|
|
- `{{工作包全景}}` 規劃階段還沒有工作包，**填空字串**；這一段由分析階段補上
|
|
- `{{頁尾}}` 產生時間與產生者
|
|
|
|
若執行環境能把 HTML 發佈成可分享的網址，就發佈；不能的話存成檔案，把路徑當成網址用。
|
|
|
|
拿到網址後寫回議題：
|
|
|
|
```
|
|
node scripts/issue-update.js --repo <owner/name> --index <編號> --overview-url <網址>
|
|
```
|
|
|
|
它把連結以固定前綴寫成總覽段落裡的一行，**重跑時就地更新同一行**，不會長出第二個連結；
|
|
議題原本的 markdown 白話總覽一字不動——網頁是補充，不是取代。連結旁會自動附上
|
|
「此連結預設為私有，組織外無法開啟」，因為讀到的人多半會想轉寄給組織外的人。
|
|
|
|
### 7. 回報
|
|
|
|
把議題編號與網址告訴使用者。不要把整份議題內容再貼一次 —— 連結點進去就看得到。
|
|
|
|
## 流程圖的限制
|
|
|
|
用 Mermaid 的 `flowchart`。節點數上限 **12**，每個節點的文字上限 **8 字**。
|
|
|
|
超過就拆成多張圖，或者乾脆不畫 —— 一張塞了二十個節點的圖，比沒有圖更難懂。
|
|
|
|
節點文字寫該步驟在做什麼，不要寫成編號或代號。
|
|
|
|
模板的 `{{流程圖}}` 要填入**完整的內容**，兩種形式擇一：
|
|
|
|
- 要畫：一個或多個完整的 ```mermaid 圍欄區塊。
|
|
- 不畫：**只在超過上限拆不開、或畫了不會比文字更清楚時**才選這個，填一行說明為什麼不畫（例如「流程為單一直線，畫圖無助理解」），**不要加圍欄**。
|
|
|
|
圍欄寫在填入的內容裡而不是模板裡，否則不畫圖時會留下一個空的 mermaid 區塊，
|
|
在議題頁上是一塊渲染失敗的紅字。
|
|
|
|
## 邊界
|
|
|
|
- 不修改使用者的專案檔案。這個流程只讀輸入、寫 Gitea 議題。
|
|
- 不建立標籤、不建立 Milestone、不建立專案看板。
|
|
- 不關閉或刪除任何既有議題。
|
|
- 規劃階段本身已含問題釐清，因此寫入 Gitea 前不再設額外的確認點；`--dry-run` 就是那道關卡。
|