From 7804247dd9deff52592103870978b49c7fb18b1e Mon Sep 17 00:00:00 2001 From: Jeffery Date: Fri, 28 Aug 2026 16:07:45 +0800 Subject: [PATCH] =?UTF-8?q?feat(analyze):=20=E4=BE=9D=E4=BD=BF=E7=94=A8?= =?UTF-8?q?=E8=80=85=E6=95=85=E4=BA=8B=E7=94=A2=E7=94=9F=E9=A9=97=E6=94=B6?= =?UTF-8?q?=E8=A8=88=E7=95=AB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- plugin.json | 2 +- skills/analyze/SKILL.md | 2 +- templates/analyze-page.md | 18 +++++++++++++++--- 5 files changed, 19 insertions(+), 7 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index dd5eb5c..39da49c 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-sdlc", - "version": "0.2.3", + "version": "0.2.4", "description": "開發生命週期：規劃、分析、實作、維護（wiki 追蹤）", "skills": "./skills", "author": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 8e1cbe9..0a2012f 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-sdlc", - "version": "0.2.3", + "version": "0.2.4", "description": "開發生命週期：規劃、分析、實作、維護（wiki 追蹤）", "skills": "./skills", "jsc": { diff --git a/plugin.json b/plugin.json index 3116696..5cd9d08 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-sdlc", - "version": "0.2.3", + "version": "0.2.4", "description": "開發生命週期：規劃、分析、實作、維護（wiki 追蹤）", "skills": "./skills/", "jsc": { diff --git a/skills/analyze/SKILL.md b/skills/analyze/SKILL.md index db4f905..c68de74 100644 --- a/skills/analyze/SKILL.md +++ b/skills/analyze/SKILL.md @@ -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. 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`). -9. Split every work package into the **測試計畫（TDD）** section, formatted `[ ]` (open) / `[x]` (done). 每個待辦都是一個垂直切片：一個接縫、一個紅燈測試、一個最小實作，以及測試通過後最小的重構驗證。接縫與反模式見 `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). 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. diff --git a/templates/analyze-page.md b/templates/analyze-page.md index 6a7ae02..64d8f6d 100644 --- a/templates/analyze-page.md +++ b/templates/analyze-page.md @@ -56,19 +56,31 @@ gantt WP-02 {名稱} :crit, wp02, after wp01, {h}h ``` +## 使用者故事驗收計畫 + +每個使用者故事都要列出驗收情境。驗收方式只能填 `真實資料` 或 `邏輯推論`。 +簡單故事至少 1 個情境；中等故事至少 2 個情境，含主要流程與邊界或錯誤流程；複雜故事至少 3 個情境，含主要流程、邊界流程與失敗流程。 +資料來源要寫可查證來源；沒有外部來源時填 `邏輯推論：{推論依據}`。 + +| 使用者故事 | 複雜度 | 情境 | 驗收方式 | 輸入 | 預期結果 | 資料來源 | 對應工作包 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| {故事名稱} | 簡單 | 主要流程：{情境名稱} | 真實資料 | {輸入資料} | {可驗收結果} | 真實資料：{來源} | WP-02 | +| {故事名稱} | 中等 | 邊界流程：{情境名稱} | 邏輯推論 | {輸入資料} | {可驗收結果} | 邏輯推論：{推論依據} | WP-02 | +| {故事名稱} | 複雜 | 失敗流程：{情境名稱} | 邏輯推論 | {輸入資料} | {錯誤狀態或拒絕原因} | 邏輯推論：{推論依據} | WP-03 | + ## 測試計畫（TDD） -每個實作工作包都要列出紅燈測試、最小實作、綠燈驗證。每個待辦都要寫出受測接縫與測試斷言的行為。 +每個實作工作包都要列出紅燈測試、最小實作、綠燈驗證。每個待辦都要寫出受測接縫、測試斷言的行為，以及對應的驗收情境。 交付、交接工作包也要列出規格審查、範例資料驗證、相依工作包可用性證據。 ### WP-01 {交付、交接工作包名稱} -- [ ] 規格接縫：盤點 {對象} 的端點、參數、回應與錯誤狀態 +- [ ] 規格接縫：盤點 {對象} 的端點、參數、回應與錯誤狀態，覆蓋驗收情境 {情境名稱} - [ ] 範例資料驗證：產出真實與推論來源標籤，確認相依工作包能直接使用 - [ ] 交付證據：與使用者確認交付內容並產出交付文件 ### WP-02 {工作包名稱} -- [ ] 紅燈測試：在 {接縫} 撰寫測試，斷言 {預期行為} +- [ ] 紅燈測試：在 {接縫} 撰寫測試，斷言 {預期行為}，覆蓋驗收情境 {情境名稱} - [ ] 最小實作：讓 {接縫} 通過該測試 - [ ] 綠燈驗證：重跑相關測試，確認 {預期行為} 維持通過