docs(sdlc-plan,sdlc-analyze): 兩份正本各自起停自己的錶
起錶與停錶寫在同一份正本裡成對出現，讀的人一眼看得出這段計時涵蓋到哪；兩份各加一節 「計時範圍」把兩端指出來。 sdlc-plan 記兩段：議題建立之前那段在第一步記下開始時間、議題建立之後以補登記上去； 之後起錶，回報那一步停錶。補登排在議題建立之後、起錶之前，順序反過來的話補登會被 time-log 當成「這一步做過了」而跳過。 sdlc-analyze 在它分析的那顆需求議題上起錶，起點放在第一段開頭——分析最耗時的正是 共識之前那一段，從第二段才起的話那段時間永遠是零。因此「共識摘要之前不對 Gitea 產生任何寫入」改寫成「不寫入任何**內容**」，並把碼錶明文除外、寫上理由：它記的是 工時，不是內容。這一條與 repo 擁有者確認過。 sdlc-feat 的「碼錶一律由使用者自己停」收斂成「**別顆議題上的**錶一律由使用者自己停」 ——它原本讀起來像全域規則，而現在每道指令都會停自己起的那一支。 正本之間改以步驟**名稱**互指，不用編號：編號會整批位移，名字不會。測試跟著改用新的 promptStep 輔助函式，以名字框出某一步的內容，別人插一步時不會無聲地框到另一段上。 議題 #57 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5
+56
-15
@@ -5,9 +5,9 @@ description: 僅由 /sdlc-analyze 指令叫用。對一顆需求議題執行可
|
||||
|
||||
對一顆需求議題執行可行性檢查，把疑點一題一題問到雙方有共識，再把共識變成一批工作包議題。
|
||||
|
||||
分成三段：**可行性分析**到共識摘要為止，完全不寫入 Gitea；使用者看過摘要點頭之後，
|
||||
才進入**產生工作包**建立議題；最後**排上時程與看板**，把相依、截止日、Milestone、
|
||||
看板與人天估算補上。
|
||||
分成三段：**可行性分析**到共識摘要為止，除了起錶之外完全不寫入 Gitea；使用者看過摘要
|
||||
點頭之後，才進入**產生工作包**建立議題；最後**排上時程與看板**，把相依、截止日、
|
||||
Milestone、看板與人天估算補上。
|
||||
|
||||
這份檔案是流程正本。各平台的轉接檔只是指回這裡，不要把規則抄過去。
|
||||
|
||||
@@ -15,6 +15,17 @@ description: 僅由 /sdlc-analyze 指令叫用。對一顆需求議題執行可
|
||||
|
||||
一個需求議題編號。
|
||||
|
||||
## 計時範圍
|
||||
|
||||
錶起在**它分析的那顆需求議題**上：在「起錶」那一步起，在「停錶並回報」那一步停，
|
||||
涵蓋整道 /sdlc-analyze。
|
||||
|
||||
起點放在第一段開頭，因為分析最耗時的正是共識之前那一段——四類疑點逐題問到收斂。
|
||||
從第二段才起錶的話，那段時間永遠是零，而報表上「分析不花時間」會直接餵給下一次估算。
|
||||
|
||||
錶已經跑在同一顆議題上時起錶什麼都不做，所以 plan 接著跑 analyze 不會把累積的時間
|
||||
切成兩段。**錶不跨階段跑**，也**不碰別顆議題上的錶**。
|
||||
|
||||
## 第一段：可行性分析
|
||||
|
||||
### 1. 讀議題
|
||||
@@ -33,7 +44,22 @@ node scripts/issue-extract.js --repo <owner/name> --index <編號>
|
||||
|
||||
使用者選擇不整併就繼續，但要記下這件事，並在共識摘要裡註明「分析基於未整併留言前的描述」。
|
||||
|
||||
### 2. 對四份清單列出疑點
|
||||
### 2. 起錶
|
||||
|
||||
議題確認存在之後，在**這顆需求議題**上起錶：
|
||||
|
||||
```
|
||||
node scripts/timer.js --repo <owner/name> --index <需求議題編號> --dry-run
|
||||
```
|
||||
|
||||
確認無誤後拿掉 `--dry-run` 再跑一次。錶已經跑在同一顆上時它什麼都不做，重跑不會把
|
||||
已經累積的時間切成兩段。
|
||||
|
||||
錶跑在別顆議題上時會被擋下（`STOPWATCH_ON_OTHER_ISSUE`）。**照實告訴使用者是哪一顆，
|
||||
請他自己去停**，不要代勞：那一段時間該記在哪顆議題上只有他知道。順帶說明停錶不會動到
|
||||
任何既有的工作樹——碼錶只管時間、工作樹只管檔案。
|
||||
|
||||
### 3. 對四份清單列出疑點
|
||||
|
||||
依序讀這四份規則正本，逐條對照議題內容：
|
||||
|
||||
@@ -45,7 +71,7 @@ node scripts/issue-extract.js --repo <owner/name> --index <編號>
|
||||
每一條檢查若在議題裡找不到答案，就轉成一個問題。**能在程式碼裡查證的就自己去查，
|
||||
不要拿去問使用者**——把問題留給只有人能回答的事。
|
||||
|
||||
### 3. 逐題問到共識
|
||||
### 4. 逐題問到共識
|
||||
|
||||
**一次問一題。** 問完等使用者回答，再問下一題，讓他能看著前一題的答案回答下一題。
|
||||
不要一次丟出五個問題，也不要把多個問題包成一題的多個選項。
|
||||
@@ -60,7 +86,7 @@ node scripts/issue-extract.js --repo <owner/name> --index <編號>
|
||||
|
||||
問題本身要具體到能用一句話回答。問不出收斂答案的問題，多半是問題本身太大，拆開再問。
|
||||
|
||||
### 4. 輸出共識摘要
|
||||
### 5. 輸出共識摘要
|
||||
|
||||
全部問完後，輸出一份摘要讓使用者做最後確認，內容包含：
|
||||
|
||||
@@ -75,7 +101,7 @@ node scripts/issue-extract.js --repo <owner/name> --index <編號>
|
||||
|
||||
**使用者對共識摘要點頭之後才開始。** 摘要沒有經過確認就不要往下走。
|
||||
|
||||
### 5. 切出工作包
|
||||
### 6. 切出工作包
|
||||
|
||||
把需求切成幾顆工作包。一顆工作包是**開發者拿了就能動手、做完有明確結果**的單位：
|
||||
它有自己的驗收標準，做完能單獨被檢視，不必等別的工作包一起才看得出成果。
|
||||
@@ -86,7 +112,7 @@ node scripts/issue-extract.js --repo <owner/name> --index <編號>
|
||||
**禁止流水編號與任何無意義代號**（`WP-01`、`任務三`、`第一階段`）：命名本身就要說明用途，
|
||||
看標題就知道這顆在做什麼，不必點進去。
|
||||
|
||||
### 6. 組出每顆工作包的內容
|
||||
### 7. 組出每顆工作包的內容
|
||||
|
||||
套用 `templates/work-package-issue.md`，依序填滿九個段落：
|
||||
|
||||
@@ -111,7 +137,7 @@ node scripts/issue-extract.js --repo <owner/name> --index <編號>
|
||||
8. **repo 列表** — 這顆會動到哪些 repo。
|
||||
9. **關聯** — 至少要有一行 `需求議題：#<編號>` 指回來源。阻擋、先決與人天估算由後續流程補上。
|
||||
|
||||
### 7. 先試跑，再寫入
|
||||
### 8. 先試跑，再寫入
|
||||
|
||||
每顆工作包各寫一個暫存檔，然後逐顆：
|
||||
|
||||
@@ -128,16 +154,18 @@ no-op」。確認無誤後拿掉該旗標再跑一次。
|
||||
中斷後重跑不會產生重複工作包：`issue-create` 以標題查重，發現同名議題就回傳既有那一顆
|
||||
並把 `created` 設為 `false`。
|
||||
|
||||
### 8. 回報
|
||||
### 9. 回報
|
||||
|
||||
列出每顆工作包的編號、標題與網址。不要把議題內容再貼一次。
|
||||
|
||||
**這裡不停錶**——指令還沒跑完，第三段還要排時程。停錶在最後的「停錶並回報」那一步。
|
||||
|
||||
## 第三段：排上時程與看板
|
||||
|
||||
工作包建好之後，把它們之間的關係與時程補上。做完這一段，看板上呈現的才是真實的
|
||||
開發順序，而不是一堆平鋪的議題。
|
||||
|
||||
### 9. 算出截止日
|
||||
### 10. 算出截止日
|
||||
|
||||
把每顆工作包的編號、人天估算與先決關係寫成一份計畫檔：
|
||||
|
||||
@@ -161,7 +189,7 @@ node scripts/schedule.js --plan-file <計畫檔>
|
||||
|
||||
日期以日曆日累加，不跳週末也不扣假日。要跳的話自己把 `startDate` 或人天調整過再算。
|
||||
|
||||
### 10. 逐顆補上關係與時程
|
||||
### 11. 逐顆補上關係與時程
|
||||
|
||||
對每一顆工作包，依序：
|
||||
|
||||
@@ -179,7 +207,7 @@ node scripts/project-add.js --repo <owner/name> --index <編號> --project "<看
|
||||
看板名稱靠掃最近 50 筆議題反查 id，反查不到就會請你直接貼專案網址（結尾即 id）。
|
||||
本流程不建立 Milestone，也不建立專案。
|
||||
|
||||
### 11. 產生分析版的圖解總覽
|
||||
### 12. 產生分析版的圖解總覽
|
||||
|
||||
用同一份 `templates/overview-artifact.html` 再產一份，但這一份要多出**工作包全景**：
|
||||
把工作包之間的相依與截止日畫成一張圖，讓開發者看得出自己這一項在整體中的位置。
|
||||
@@ -205,7 +233,16 @@ node scripts/issue-update.js --repo <owner/name> --index <需求議題編號> --
|
||||
**重跑會就地更新同一行**，不會在議題上留下兩個連結。規劃階段產生的那一份會被這一份取代，
|
||||
這是預期行為——同一顆需求議題只掛一個總覽網址。
|
||||
|
||||
### 12. 回報
|
||||
### 13. 停錶並回報
|
||||
|
||||
回報之前先停錶，這一段計時到此為止：
|
||||
|
||||
```
|
||||
node scripts/timer.js --repo <owner/name> --index <需求議題編號> --stop
|
||||
```
|
||||
|
||||
它**只停這一顆**上的錶，與「起錶」那一步起的是同一顆。錶本來就沒在跑不算失敗
|
||||
（`碼錶已停` 會是 `false` 並附一句說明），回報照樣做完。
|
||||
|
||||
列出每顆工作包的編號、標題、截止日與所屬 Milestone，並指出**相依鏈最長路徑**上的那幾顆
|
||||
——那條路徑決定整體交期。
|
||||
@@ -236,9 +273,13 @@ Gitea 1.27 的 API 沒有任何請求定義接受 `time_estimate`，該欄位只
|
||||
|
||||
## 邊界
|
||||
|
||||
- **共識摘要之前不對 Gitea 產生任何寫入**：不建議題、不改描述、不貼標籤、不留留言。
|
||||
- **共識摘要之前不對 Gitea 寫入任何內容**：不建議題、不改描述、不貼標籤、不留留言。
|
||||
**碼錶除外**——它記的是工時，不是內容；而分析最耗時的正是共識之前那一段，不從那裡
|
||||
起錶，那段時間就永遠是零。
|
||||
- 第二段只建立工作包議題。不建相依、不掛 Milestone、不加看板、不寫人天估算——那是第三段的事。
|
||||
- 第三段只掛既有的 Milestone 與看板。不自行建立標籤、Milestone 或專案看板。
|
||||
- 不修改使用者的專案檔案。查證既有功能時只讀不寫。
|
||||
- 不替使用者決定他沒回答的事。問不到答案就進「仍然未決的事」。
|
||||
- 計時只動這顆需求議題：在它上面起錶、在它上面停錶。**不停別顆議題上的錶**，
|
||||
被別顆的錶擋下時交還給使用者決定，不繞過去。
|
||||
- 不關閉或刪除任何既有議題。
|
||||
|
||||
@@ -65,7 +65,8 @@ node scripts/claim.js --repo <owner/name> --index <編號> --dry-run
|
||||
不講清楚，使用者會以為停錶等於放棄那顆工作包，於是寧可不停——工時就記到別顆去了。
|
||||
| 沒有鎖 | —— | 放行。自己已認領但沒起錶也算沒有鎖，那正是中斷後重跑的情形 |
|
||||
|
||||
碼錶一律由使用者自己停。哪一段時間該記在哪顆議題上只有他知道，代勞會把工時記錯地方。
|
||||
**別顆議題上的錶一律由使用者自己停。** 哪一段時間該記在哪顆議題上只有他知道，代勞會把
|
||||
工時記錯地方。每道指令停掉的只有自己起的那一支——這一道停在「開 PR 並停錶」那一步。
|
||||
|
||||
鎖以外還有一個前置條件：repo 上要有「進行中」標籤。缺了會得到 `LABEL_NOT_FOUND`，
|
||||
請使用者自己去建立——**不要自己建**，標籤體系不該在多個 repo 之間長出雜草。
|
||||
|
||||
+70
-7
@@ -19,13 +19,36 @@ description: 僅由 /sdlc-plan 指令叫用。把一段口語需求轉成結構
|
||||
`scripts/issue-extract.js` 取（若該腳本尚未可用，改用 `scripts/issue-create.js` 以外的
|
||||
既有讀取途徑，並在摘要中註明資料來源）。
|
||||
|
||||
## 計時範圍
|
||||
|
||||
這份正本把整個 /sdlc-plan 的耗時記成兩段，合起來就是這道指令實際花掉的時間：
|
||||
|
||||
- **議題建立之前** — 在「記下開始時間」記下起點，在「補登規劃時間，然後起錶」補上去。
|
||||
議題還不存在，沒有標的可起錶。
|
||||
- **議題建立之後** — 在「補登規劃時間，然後起錶」起錶，在「停錶並回報」停錶。
|
||||
|
||||
起與停都寫在這一份裡，**錶不跨階段跑**：跑完就去開會而錶跑一整天，報表當場失真。
|
||||
反過來，別顆議題上的錶一律不碰——那一段時間該記在哪顆議題上只有使用者知道。
|
||||
|
||||
## 步驟
|
||||
|
||||
### 1. 讀齊輸入，列出還缺什麼
|
||||
### 1. 記下開始時間
|
||||
|
||||
讀齊輸入、逐項詢問、組出議題內容，往往是整個 plan 最耗時的一段，而它發生在議題建立
|
||||
**之前**——那時候沒有標的可起錶。所以先把此刻的時間記下來，等議題建立之後補登上去：
|
||||
|
||||
```
|
||||
node -e "console.log(new Date().toISOString())"
|
||||
```
|
||||
|
||||
記下它，一路帶到「補登規劃時間，然後起錶」那一步。**不要憑印象回推**：補登的長度就是
|
||||
報表上規劃階段的數字。
|
||||
|
||||
### 2. 讀齊輸入，列出還缺什麼
|
||||
|
||||
把九個段落逐一對照使用者給的材料，列出哪些段落已經有依據、哪些沒有。
|
||||
|
||||
### 2. 逐項詢問
|
||||
### 3. 逐項詢問
|
||||
|
||||
**一次問一題**，等使用者回答完再問下一題，讓他能看著前一題的答案回答下一題。
|
||||
|
||||
@@ -34,7 +57,7 @@ description: 僅由 /sdlc-plan 指令叫用。把一段口語需求轉成結構
|
||||
**未獲得答覆的欄位不得自行編造。** 使用者沒說過的目標、沒提過的驗收標準，一個字都不能自己
|
||||
填。問不到就放進「未決事項」，那一段本來就是給未決的東西用的。
|
||||
|
||||
### 3. 組出議題內容
|
||||
### 4. 組出議題內容
|
||||
|
||||
套用 `templates/requirement-issue.md`，依序填滿九個段落：
|
||||
|
||||
@@ -49,13 +72,13 @@ description: 僅由 /sdlc-plan 指令叫用。把一段口語需求轉成結構
|
||||
8. **影響範圍** — 會動到哪些 repo、哪些既有功能。
|
||||
9. **未決事項** — 問不到答案、或需要他人拍板的事。
|
||||
|
||||
### 4. 挑標籤
|
||||
### 5. 挑標籤
|
||||
|
||||
先用 `scripts/labels-list.js --repo <owner/name>` 取得該 repo 的既有標籤，**只能從這份清單裡
|
||||
挑**。找不到合適的就不貼。**不得自行建立新標籤** —— 標籤體系由專案維護者決定，不該在多個
|
||||
repo 之間長出雜草。
|
||||
|
||||
### 5. 先試跑，再寫入
|
||||
### 6. 先試跑，再寫入
|
||||
|
||||
把組好的內容寫到一個暫存檔，然後：
|
||||
|
||||
@@ -69,7 +92,36 @@ node scripts/issue-create.js --repo <owner/name> --title "<標題>" --body-file
|
||||
同一段需求重跑不會產生第二顆議題：`issue-create` 以標題查重，發現同名議題就回傳既有那一顆
|
||||
並把 `created` 設為 `false`。
|
||||
|
||||
### 6. 產生圖解版總覽
|
||||
### 7. 補登規劃時間，然後起錶
|
||||
|
||||
議題有了，計時才有標的。**先補登、再起錶**，兩步指向同一顆議題。
|
||||
|
||||
先把「記下開始時間」到議題建立那一段補上去：
|
||||
|
||||
```
|
||||
node scripts/time-log.js --repo <owner/name> --index <編號> --since <記下的開始時間> --dry-run
|
||||
```
|
||||
|
||||
長度由腳本自己算——它讀議題的建立時間減掉 `--since`，所以不必自己做減法，也不會讓
|
||||
兩邊的時鐘各算一次。確認無誤後拿掉 `--dry-run` 再跑一次。
|
||||
|
||||
**不設時間上限，照實補登。** 中途去開會的那兩個小時會一起被算進去，這是刻意的：換來
|
||||
這個流程不必為此多長一題出來問使用者。時間記多了看得出來，記不到就永遠找不回來。
|
||||
|
||||
補登完才起錶：
|
||||
|
||||
```
|
||||
node scripts/timer.js --repo <owner/name> --index <編號> --dry-run
|
||||
```
|
||||
|
||||
一樣先試跑，確認無誤後拿掉 `--dry-run` 再跑一次。順序反過來的話補登會被當成「這一步做過了」而跳過——錶在這顆議題上跑著，正是
|
||||
`time-log` 判斷補過了的依據之一，它也因此重跑不會愈補愈多。
|
||||
|
||||
錶已經跑在別顆議題上時起錶會被擋下（`STOPWATCH_ON_OTHER_ISSUE`）。**照實告訴使用者
|
||||
是哪一顆，請他自己去停**，不要代勞：那一段時間該記在哪顆議題上只有他知道。順帶說明
|
||||
停錶不會動到任何既有的工作樹——碼錶只管時間、工作樹只管檔案。
|
||||
|
||||
### 8. 產生圖解版總覽
|
||||
|
||||
套用 `templates/overview-artifact.html`，把議題的總覽、目標與流程圖填成一份可以直接投影的
|
||||
網頁。這一份是給**非技術的利害關係人**看的：他們不必讀完技術細節就知道這件事在做什麼。
|
||||
@@ -96,7 +148,16 @@ node scripts/issue-update.js --repo <owner/name> --index <編號> --overview-url
|
||||
議題原本的 markdown 白話總覽一字不動——網頁是補充，不是取代。連結旁會自動附上
|
||||
「此連結預設為私有，組織外無法開啟」，因為讀到的人多半會想轉寄給組織外的人。
|
||||
|
||||
### 7. 回報
|
||||
### 9. 停錶並回報
|
||||
|
||||
回報之前先停錶，這一段計時到此為止：
|
||||
|
||||
```
|
||||
node scripts/timer.js --repo <owner/name> --index <編號> --stop
|
||||
```
|
||||
|
||||
它**只停這一顆**上的錶。錶本來就沒在跑不算失敗（`碼錶已停` 會是 `false` 並附一句
|
||||
說明），回報照樣做完。
|
||||
|
||||
把議題編號與網址告訴使用者。不要把整份議題內容再貼一次 —— 連結點進去就看得到。
|
||||
|
||||
@@ -122,3 +183,5 @@ node scripts/issue-update.js --repo <owner/name> --index <編號> --overview-url
|
||||
- 不建立標籤、不建立 Milestone、不建立專案看板。
|
||||
- 不關閉或刪除任何既有議題。
|
||||
- 規劃階段本身已含問題釐清，因此寫入 Gitea 前不再設額外的確認點；`--dry-run` 就是那道關卡。
|
||||
- 計時只動這顆需求議題：在它上面起錶、在它上面停錶、把規劃時間補登在它上面。
|
||||
**不停別顆議題上的錶**，被別顆的錶擋下時交還給使用者決定，不繞過去。
|
||||
|
||||
Reference in New Issue
Block a user