fix(analyze): 讓測試計畫符合 TDD 循環

This commit is contained in:
2026-08-28 16:10:20 +08:00
parent 7804247dd9
commit 19d873d19a
6 changed files with 8 additions and 9 deletions
+1 -1
View File
@@ -1,6 +1,6 @@
{ {
"name": "jsc-sdlc", "name": "jsc-sdlc",
"version": "0.2.4", "version": "0.2.5",
"description": "開發生命週期:規劃、分析、實作、維護(wiki 追蹤)", "description": "開發生命週期:規劃、分析、實作、維護(wiki 追蹤)",
"skills": "./skills", "skills": "./skills",
"author": { "author": {
+1 -1
View File
@@ -1,6 +1,6 @@
{ {
"name": "jsc-sdlc", "name": "jsc-sdlc",
"version": "0.2.4", "version": "0.2.5",
"description": "開發生命週期:規劃、分析、實作、維護(wiki 追蹤)", "description": "開發生命週期:規劃、分析、實作、維護(wiki 追蹤)",
"skills": "./skills", "skills": "./skills",
"jsc": { "jsc": {
+1 -1
View File
@@ -1,6 +1,6 @@
{ {
"name": "jsc-sdlc", "name": "jsc-sdlc",
"version": "0.2.4", "version": "0.2.5",
"description": "開發生命週期:規劃、分析、實作、維護(wiki 追蹤)", "description": "開發生命週期:規劃、分析、實作、維護(wiki 追蹤)",
"skills": "./skills/", "skills": "./skills/",
"jsc": { "jsc": {
+1 -1
View File
@@ -8,7 +8,7 @@
1. **先紅後綠**:先寫會失敗的測試,再寫剛好通過的實作;不預寫未來的測試、不加投機功能。 1. **先紅後綠**:先寫會失敗的測試,再寫剛好通過的實作;不預寫未來的測試、不加投機功能。
2. **一次一片(vertical slice)**:一個接縫、一個測試、一個最小實作為一個循環;下一片依上一片學到的調整。 2. **一次一片(vertical slice)**:一個接縫、一個測試、一個最小實作為一個循環;下一片依上一片學到的調整。
3. **重構不在循環內**:重構屬於審查階段(`jsc-review:code-review`),不混入紅綠循環。 3. **綠燈後重構**:測試通過後才能重構;重構只改善設計,不改變可觀察行為,並且要重跑同一組測試保持綠燈。
4. **註解只寫原因**:一個待辦要算完成,該次 diff 的註解不得夾帶追蹤編號與文件位置。完整清單與白名單見 `jsc-review` 的 `references/comment-scope.md`。 4. **註解只寫原因**:一個待辦要算完成,該次 diff 的註解不得夾帶追蹤編號與文件位置。完整清單與白名單見 `jsc-review` 的 `references/comment-scope.md`。
## 反模式(發現即重寫該測試) ## 反模式(發現即重寫該測試)
+1 -1
View File
@@ -32,7 +32,7 @@ All wiki reads and writes go through `jsc-gitea:wiki`.
6. Run a **Work Breakdown Structure (WBS)**: split the user stories into work packages, number them sequentially (`WP-01`, `WP-02`, ...) and mark dependencies. Completion condition: every user story on the plan page maps to at least one numbered work package, and every dependency edge is recorded in the WBS table's 相依 column. 6. Run a **Work Breakdown Structure (WBS)**: split the user stories into work packages, number them sequentially (`WP-01`, `WP-02`, ...) and mark dependencies. Completion condition: every user story on the plan page maps to at least one numbered work package, and every dependency edge is recorded in the WBS table's 相依 column.
7. **`WP-01` is always the delivery/handover work package** — see "Delivery package is WP-01" below. It stands alone, never merged into an implementation package, and every implementation package that consumes its spec depends on it. Completion condition: `WP-01` is marked 交付 `是` and holds only spec-shaped items, and every implementation package that consumes its spec names `WP-01` in its 相依 column — or the no-handover case below is confirmed with the user and its reason is written on the page. 7. **`WP-01` is always the delivery/handover work package** — see "Delivery package is WP-01" below. It stands alone, never merged into an implementation package, and every implementation package that consumes its spec depends on it. Completion condition: `WP-01` is marked 交付 `是` and holds only spec-shaped items, and every implementation package that consumes its spec names `WP-01` in its 相依 column — or the no-handover case below is confirmed with the user and its reason is written on the page.
8. Estimate every work package's effort in hours and days with the **Critical Path Method (CPM)**, and mark the critical path. Draw the critical path as a mermaid gantt chart per `references/cpm-chart.md` — its date/duration rules are mandatory, not a suggestion; skipping them is how the `Invalid date` rendering failure happens. Completion condition: every work package carries an hours figure and a days figure, the critical path plus its total days are written on the page, and the gantt chart follows `references/cpm-chart.md` exactly (integer-hour durations, `after` chaining, no `dateFormat X`). 8. Estimate every work package's effort in hours and days with the **Critical Path Method (CPM)**, and mark the critical path. Draw the critical path as a mermaid gantt chart per `references/cpm-chart.md` — its date/duration rules are mandatory, not a suggestion; skipping them is how the `Invalid date` rendering failure happens. Completion condition: every work package carries an hours figure and a days figure, the critical path plus its total days are written on the page, and the gantt chart follows `references/cpm-chart.md` exactly (integer-hour durations, `after` chaining, no `dateFormat X`).
9. 在 TDD 待辦前先產生 **使用者故事驗收計畫**,再把每個工作包拆進 **測試計畫(TDD)** 區塊,格式用 `[ ]`(未完成)與 `[x]`(完成)。每個使用者故事都要有驗收情境,並標明驗收方式是 `真實資料` 或 `邏輯推論`。簡單故事至少 1 個情境;中等故事至少 2 個情境,含 1 個主要流程與 1 個邊界或錯誤流程;複雜故事至少 3 個情境,含主要流程、邊界流程與失敗流程。每個情境都要寫出輸入、預期結果、資料來源與對應工作包。每個 TDD 待辦都是一個垂直切片:一個接縫、一個紅燈測試、一個最小實作,以及測試通過後最小的重構驗證。接縫與反模式見 `references/tdd.md`。完成條件:每個使用者故事都在 `## 使用者故事驗收計畫` 有情境;每個情境都有明確驗收方式與資料來源;情境數量符合複雜度;每個工作包都在 `## 測試計畫(TDD)` 下有自己的小節;每個實作工作包至少有一個測試先行的 `[ ]` 待辦;每個待辦都寫出接縫與測試斷言的行為。純交付工作包可以寫文件驗證或範例資料驗證待辦,但仍要寫出能證明規格可用的測試證據或審查證據。 9. 在 TDD 待辦前先產生 **使用者故事驗收計畫**,再把每個工作包拆進 **測試計畫(TDD)** 區塊,格式用 `[ ]`(未完成)與 `[x]`(完成)。每個使用者故事都要有驗收情境,並標明驗收方式是 `真實資料` 或 `邏輯推論`。簡單故事至少 1 個情境;中等故事至少 2 個情境,含 1 個主要流程與 1 個邊界或錯誤流程;複雜故事至少 3 個情境,含主要流程、邊界流程與失敗流程。每個情境都要寫出輸入、預期結果、資料來源與對應工作包。每個 TDD 待辦都是一個完整循環:一個接縫、一個先失敗的測試、一個最小實作、一次綠燈驗證,以及必要時的綠燈後重構。不要把紅燈測試、最小實作、綠燈驗證拆成不同待辦。接縫與反模式見 `references/tdd.md`。完成條件:每個使用者故事都在 `## 使用者故事驗收計畫` 有情境;每個情境都有明確驗收方式與資料來源;情境數量符合複雜度;每個工作包都在 `## 測試計畫(TDD)` 下有自己的小節;每個實作工作包至少有一個測試先行的 `[ ]` 待辦;每個待辦都寫出接縫、驗收情境、測試斷言行為、最小實作範圍與綠燈驗證方式。純交付工作包可以寫文件驗證或範例資料驗證待辦,但仍要寫出能證明規格可用的測試證據或審查證據。
10. Apply `templates/analyze-page.md` to create or update the analysis page and write it back via `jsc-gitea:wiki`. The page content is Traditional Chinese, exactly as the template dictates. Completion condition: the page is saved on the wiki and carries every section the template dictates, including the source branch, the head sha and the 未決項 section (「無」 when there is none). 10. Apply `templates/analyze-page.md` to create or update the analysis page and write it back via `jsc-gitea:wiki`. The page content is Traditional Chinese, exactly as the template dictates. Completion condition: the page is saved on the wiki and carries every section the template dictates, including the source branch, the head sha and the 未決項 section (「無」 when there is none).
11. If the analysis page is new: add it to `ANALYZE_CONTENTS` per `templates/analyze-contents.md`, and flip the plan's status in `PLAN_CONTENTS` to the literal 「已分析」. Completion condition: `ANALYZE_CONTENTS` shows the new row and `PLAN_CONTENTS` shows the literal 「已分析」, both saved on the wiki. 11. If the analysis page is new: add it to `ANALYZE_CONTENTS` per `templates/analyze-contents.md`, and flip the plan's status in `PLAN_CONTENTS` to the literal 「已分析」. Completion condition: `ANALYZE_CONTENTS` shows the new row and `PLAN_CONTENTS` shows the literal 「已分析」, both saved on the wiki.
12. **Stage report — the last thing this stage does, including every early stop** (the model gate blocked, the working tree did not match `origin/{source-branch}`, no plan was selectable). Run `tools/stage-report.sh analyze` with one `--page TYPE:{page}` per wiki page this run wrote — `ANALYZE_{HASH}`, `ANALYZE_CONTENTS`, `PLAN_CONTENTS`, and `REPO_{HASH}` plus `REPO_CONTENTS` when a re-inventory happened — plus `--worklog` and `--worklog-heading` when a work log entry exists. No work log yet: write this stage's log content to a file and pass `--pending-file {file} --log-hash {HASH}` so it is held for the next `jsc-log:worklog` run. Rules and exit codes: `references/stage-report.md`. Exit 1 is a warning, never a block. Completion condition: the script's output is reported to the user verbatim, and every wiki page this run wrote appears in it. 12. **Stage report — the last thing this stage does, including every early stop** (the model gate blocked, the working tree did not match `origin/{source-branch}`, no plan was selectable). Run `tools/stage-report.sh analyze` with one `--page TYPE:{page}` per wiki page this run wrote — `ANALYZE_{HASH}`, `ANALYZE_CONTENTS`, `PLAN_CONTENTS`, and `REPO_{HASH}` plus `REPO_CONTENTS` when a re-inventory happened — plus `--worklog` and `--worklog-heading` when a work log entry exists. No work log yet: write this stage's log content to a file and pass `--pending-file {file} --log-hash {HASH}` so it is held for the next `jsc-log:worklog` run. Rules and exit codes: `references/stage-report.md`. Exit 1 is a warning, never a block. Completion condition: the script's output is reported to the user verbatim, and every wiki page this run wrote appears in it.
+3 -4
View File
@@ -70,7 +70,8 @@ gantt
## 測試計畫(TDD) ## 測試計畫(TDD)
每個實作工作包都要列出紅燈測試、最小實作、綠燈驗證。每個待辦都要寫出受測接縫、測試斷言的行為,以及對應的驗收情境。 每個實作工作包都要列出完整 TDD 循環。每個待辦都要寫出受測接縫、對應驗收情境、測試斷言行為、最小實作範圍、綠燈驗證方式。
不要把紅燈測試、最小實作、綠燈驗證拆成不同待辦。
交付、交接工作包也要列出規格審查、範例資料驗證、相依工作包可用性證據。 交付、交接工作包也要列出規格審查、範例資料驗證、相依工作包可用性證據。
### WP-01 {交付、交接工作包名稱} ### WP-01 {交付、交接工作包名稱}
@@ -81,6 +82,4 @@ gantt
### WP-02 {工作包名稱} ### WP-02 {工作包名稱}
- [ ] 紅燈測試:在 {接縫} 撰寫測試,斷言 {預期行為},覆蓋驗收情境 {情境名稱} - [ ] TDD 循環:驗收情境 {情境名稱};接縫 {接縫};先寫會失敗的測試,斷言 {預期行為};最小實作範圍 {實作範圍};重跑 {測試指令或測試集合} 確認綠燈;必要時重構並保持綠燈
- [ ] 最小實作:讓 {接縫} 通過該測試
- [ ] 綠燈驗證:重跑相關測試,確認 {預期行為} 維持通過