From 62fd2a60223be1c94279f1e5e73cebb8d652964f Mon Sep 17 00:00:00 2001 From: Jeffery Date: Mon, 24 Aug 2026 17:24:31 +0800 Subject: [PATCH] =?UTF-8?q?feat(=E4=BA=A4=E4=BB=98=E8=88=87=E5=85=B1?= =?UTF-8?q?=E8=AD=98):=20=E4=BA=A4=E4=BB=98=E5=B7=A5=E4=BD=9C=E5=8C=85?= =?UTF-8?q?=E7=8D=A8=E7=AB=8B=E7=82=BA=20WP-01=E3=80=81=E6=96=B0=E5=A2=9E?= =?UTF-8?q?=E4=BA=A4=E4=BB=98=E5=85=A7=E5=AE=B9=E5=9E=8B=E5=88=A5=E8=88=87?= =?UTF-8?q?=E5=85=B1=E8=AD=98=E5=88=A4=E5=AE=9A=E8=A6=8F=E5=89=87?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5 (1M context) --- references/consensus.md | 38 ++++++++++++++++ references/deliver-formats.md | 58 +++++++++++++++++++++++++ skills/analyze/SKILL.md | 20 +++++---- skills/implement/SKILL.md | 22 +++++++--- skills/plan/SKILL.md | 5 ++- templates/analyze-page.md | 37 ++++++++++------ templates/deliver-contents.md | 7 +++ templates/deliver-page.md | 81 +++++++++++++++++++++++++++++++++++ 8 files changed, 240 insertions(+), 28 deletions(-) create mode 100644 references/consensus.md create mode 100644 references/deliver-formats.md create mode 100644 templates/deliver-contents.md create mode 100644 templates/deliver-page.md diff --git a/references/consensus.md b/references/consensus.md new file mode 100644 index 0000000..4042f1a --- /dev/null +++ b/references/consensus.md @@ -0,0 +1,38 @@ +# 共識判定 — 規劃與分析階段的提問規則 + +`plan` 與 `analyze` 都靠提問把需求問清楚。兩個階段共用本規則，各自不再重寫一份。 + +## 一輪不算問完 + +- **每個回答都要生出下一個問題**：從使用者的答案往下推，找出它新暴露的未知，繼續問。答完一輪就收工是最常見的失敗。 +- 問題一次只問一件事，選項一律標明影響範圍（依 `jsc-ask:ask`）。 +- 問過的別再問：先查 wiki 的 `QUESTION_CONTENTS` 與 `QUESTION_{HASH}`，已答的直接沿用。 + +## 達成共識的兩個條件 + +同時滿足才算共識，缺一不可： + +1. **沒有未知會改變產出**——任何還沒問清楚的細節，都不足以改變使用者故事、工作包切分或工時估算。 +2. **使用者明確確認**——把整理過的結論讀回去，使用者明確表示同意。 + +## 每輪都要讓共識可見 + +提問前先攤開現況，不要讓使用者自己記： + +| 區塊 | 內容 | +| --- | --- | +| 已達成共識 | 已確認的項目與結論 | +| 尚未釐清 | 還開著的項目，以及它會影響什麼 | +| 本輪要問 | 這一輪要解決哪一項 | + +## 不可以做的事 + +- **不得用自己的假設補洞**。缺資訊就問，不能先寫下去再說。 +- **不得把沉默或「都可以」當成答案**——只要該項會改變範圍或切分，就要追問到具體選項。 +- **不得在還有開著的項目時往下走**（規劃不得產出使用者故事，分析不得開始 WBS）。 +- 使用者確實不想決定時：把它當**未決項**寫進頁面，註明影響與預設處理方式，並問使用者要不要接受那個預設值。未決項不得靜默消失。 + +## 收尾 + +- 共識達成後，把「問了什麼、答了什麼」依 `jsc-ask:ask` 規則回存 wiki，讓下一階段不必重問。 +- 頁面上的未決項要能追：誰要決定、什麼時候決定、不決定會怎樣。 diff --git a/references/deliver-formats.md b/references/deliver-formats.md new file mode 100644 index 0000000..ec78004 --- /dev/null +++ b/references/deliver-formats.md @@ -0,0 +1,58 @@ +# 交付內容型別 + +交付／交接工作包開工時，先跟使用者確認這份交付要產出什麼內容。預設選項固定兩個，其餘由使用者輸入。 + +| 選項 | 內容 | +| --- | --- | +| 1. API 文件 | 端點路徑、輸入參數（**全部**）、輸出參數（**全部**）；見下節 | +| 2. 由使用者輸入 | 使用者自己講要什麼內容；照使用者說的做，不套 API 文件格式 | + +選項一律依 `jsc-ask:ask` 規則呈現，並標明影響範圍。**不得自行預設，也不得跳過詢問。** + +## API 文件 + +### 必備欄位 + +| 區塊 | 要求 | +| --- | --- | +| 端點路徑 | 方法與完整路徑（例 `GET /v1/members/{id}`），含版本前綴 | +| 輸入參數 | **列出全部**——路徑、查詢字串、標頭、請求主體逐層列，不可只列「主要的幾個」 | +| 輸出參數 | **列出全部**——回應主體逐層列，含錯誤回應的結構與狀態碼 | + +每個參數都要有：名稱、型別、必填與否、範例、資料來源、新舊狀態。 + +### 參數範例：真實資料優先 + +1. 先找真實來源：資料庫欄位與實際資料列、實際 API 回應、既有設定檔或 fixture、日誌。標成 `真實：{來源}`。 +2. 找不到來源才由邏輯推理，標成 `推論：無來源`，讓接手者知道那個值還沒被驗證。 +3. **不得**編一個看起來合理的值當成真實資料。 +4. 範例只保留**結構與格式**。個資一律遮蔽或改寫成格式描述，不把真實個資寫進交付文件。 + +### 既有端點：新舊參數必須明顯區分 + +改的是既有端點時，接手者最需要知道「哪些是這次動到的」。用兩種標示，兩者都要： + +**一、參數表加狀態欄** + +| 狀態 | 標示 | 意義 | +| --- | --- | --- | +| 新增 | 🆕 **新增** | 這次新增的參數 | +| 變更 | ⚠️ **變更** | 既有參數改了型別、必填性、預設值或語意 | +| 既有 | （留空） | 這次沒動 | +| 移除 | ❌ **移除** | 這次移除，含淘汰時程 | + +**二、差異區塊用 `diff` 語法標色** + +Gitea 與 GitHub 的 markdown 都會替 `diff` 程式碼區塊上色，`+` 綠、`-` 紅，是最可靠的「顏色」做法（HTML 的 `style` 屬性會被 wiki 過濾掉，不要用）： + +````markdown +```diff + GET /v1/members/{id} + id string 必填 ++ include_tags boolean 選填 預設 false（本次新增） +- legacy_flag boolean 選填 （本次移除，2026-12-31 前相容） +! status string 必填 列舉值新增 suspended（本次變更） +``` +```` + +新端點不需要狀態欄與差異區塊，但要註明「本次新增端點」。 diff --git a/skills/analyze/SKILL.md b/skills/analyze/SKILL.md index f1a5919..a69aa7b 100644 --- a/skills/analyze/SKILL.md +++ b/skills/analyze/SKILL.md @@ -1,6 +1,6 @@ --- name: analyze -description: SDLC analysis stage. Gate on capability tags enforced in code by sdlc-gate (analyze requires reasoning-max, verified against the transcript's actual model id), confirm the source branch with the user, pick a plan from PLAN_CONTENTS, analyze user stories against the current state (working directory plus REPO_{HASH} inventory for reuse). Run WBS with handover work packages ranked first (spec before implementation), estimate them with CPM, split each into TDD todos, and write wiki page ANALYZE_{HASH} with real sample data. Logic only - never write code or modify files. Use after planning and before implementation. +description: SDLC analysis stage. Gate on capability tags enforced in code by sdlc-gate (analyze requires reasoning-max, verified against the transcript's actual model id), confirm the source branch with the user, pick a plan from PLAN_CONTENTS, analyze user stories against the current state (working directory plus REPO_{HASH} inventory for reuse). Keep questioning until consensus per references/consensus.md, run WBS with the delivery/handover package as a standalone WP-01 that implementation packages depend on, estimate them with CPM, split each into TDD todos, and write wiki page ANALYZE_{HASH} with real sample data. Logic only - never write code or modify files. Use after planning and before implementation. --- # analyze @@ -25,27 +25,28 @@ All wiki reads and writes go through `jsc-gitea:wiki`. 4. Record the confirmed branch and its head sha on the analysis page. Completion condition: the user has confirmed the branch explicitly; never infer it from the current checkout alone. 3. Read `PLAN_CONTENTS` via `jsc-gitea:wiki` for plans whose status is the literal 「未分析」 (name and HASH), and read `ANALYZE_CONTENTS` for existing analyses. 4. Let the user choose per `jsc-ask:ask` rules: **extend an existing analysis** or **analyze a new plan**. State the impact scope on every option. -5. Analyze the plan page's user stories one by one against the **current state**, questioning via the `jsc-ask:ask` decision tree until no doubt remains; keep asking while consensus is missing. Current state means: +5. Analyze the plan page's user stories one by one against the **current state**, **questioning until consensus** per `references/consensus.md` (the single authority for both planning and analysis): every answer produces the next question, and consensus needs both no output-changing unknown **and** the user's explicit confirmation. Never assume a missing detail, and never start the WBS while any item is still open. Current state means: 1. Every file in the working directory, on the branch confirmed in step 2. 2. **Reuse existing methods and endpoints whenever possible**: - Check the `REPO_{HASH}` inventory page first. Re-inventory when the feature or endpoint is missing, or when the recorded commit sha differs from the current one. - Re-inventory **MUST run as a sub agent**: analyze the repository's features and endpoints, attach the current commit sha, write back to `REPO_{HASH}` with `templates/repo-page.md`, and update `REPO_CONTENTS` per `templates/repo-contents.md`. - For each reuse candidate, confirm the file path and method name first, then analyze whether its logic fits the requirement. 6. Run a **Work Breakdown Structure (WBS)**: split the user stories into work packages, number them sequentially (`WP-01`, `WP-02`, ...) and mark dependencies. -7. **Rank handover work packages first** — see 「交接優先」 below. Spec-shaped packages ship before implementation-shaped ones. +7. **`WP-01` is always the delivery/handover work package** — see 「交付工作包最優先」 below. It stands alone, never merged into an implementation package, and every implementation package that consumes its spec depends on it. 8. Estimate every work package's effort in hours and days with the **Critical Path Method (CPM)**, and mark the critical path. 9. Split every work package into todos with **Test-Driven Development (TDD)**, formatted `[ ]` (open) / `[x]` (done). Each todo is one vertical slice: one seam, one test, one minimal implementation. Seams and anti-patterns: `references/tdd.md`. 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. 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 「已分析」. -## 交接優先（handover first） +## 交付工作包最優先（delivery package is WP-01） -A work package is a **handover package** when someone else — another person, another CLI, another team — has to act on its output. Interfaces, schemas, spec documents, acceptance criteria and sample payloads are handover output; endpoint bodies and UI wiring are not. +A work package is a **delivery/handover package** when someone else — another person, another CLI, another team — has to act on its output. Interfaces, schemas, spec documents, acceptance criteria and sample payloads are delivery output; endpoint bodies and UI wiring are not. -- Mark every work package as 交接 `是` / `否` in the WBS table. -- **Order handover packages before implementation packages**, so the receiving side gets the spec while implementation is still open. Implementation packages are the backup queue (實作候補): they are still numbered, estimated and kept on the page, just ranked later. -- Dependencies still win: never place a package before one it depends on. Within the same dependency level, handover packages come first. -- Do not merge a spec and its implementation into one package — that removes the ability to hand the spec over early. Split them. +- **`WP-01` is the delivery/handover package, always first, always standalone.** Pull every spec-shaped item out of the implementation packages and put it here. Never merge a spec into the package that implements it — merging removes the ability to hand the spec over early, which is the whole point. +- **Implementation packages depend on `WP-01`** when they consume its spec, and they are the backup queue (實作候補): still numbered, still estimated, still on the page, just ranked after it. +- Mark every work package as 交付 `是` / `否` in the WBS table, and record `WP-01`'s intended content type in the 交付型別 column when the user has already decided it (options in `references/deliver-formats.md`; the type is confirmed for real when `implement` starts that package). +- Dependencies still win among the rest: never place a package before one it depends on. Within the same dependency level, delivery-shaped packages come first. +- **When nothing is genuinely deliverable** (say, an internal refactor with no interface change), do not invent an empty `WP-01`: confirm with the user per `jsc-ask:ask` that this analysis has no handover output, then note the reason on the page and number the implementation packages from `WP-01`. ## 範例資料（sample data） @@ -55,6 +56,7 @@ Every sample value on the analysis page — request and response payloads, field 2. **Only when no source exists**, derive the value by reasoning from the surrounding logic — and label it as inferred (for example `推論：無來源`), so the receiving side knows it is unverified. 3. Never invent a plausible-looking value and present it as real, and never leave the origin of a sample unstated. 4. Real data goes on the page as **structure and format only**: field names, types, shapes. Never copy personal data onto the wiki — mask any personal identifier, and prefer describing the format over pasting the value. +5. When `WP-01`'s content type is an API document, the required fields and the new-versus-existing parameter marking are defined in `references/deliver-formats.md`; follow it rather than inventing a layout. ## Hard limits diff --git a/skills/implement/SKILL.md b/skills/implement/SKILL.md index 82f7b4d..d64c6e4 100644 --- a/skills/implement/SKILL.md +++ b/skills/implement/SKILL.md @@ -1,6 +1,6 @@ --- name: implement -description: SDLC implementation stage. Gate on capability tags enforced in code by sdlc-gate (implement requires coding, verified against the transcript's actual model id), confirm the target branch with the user before writing any file, then claim a ready work package from ANALYZE_CONTENTS with a work ticket and complete its TDD todos one by one, updating the wiki after every item. Ends with jsc-review code-review and an optional MAINTAIN_CONTENTS entry. Use when analysis is done and code must be written; not for planning or analysis. +description: SDLC implementation stage. Gate on capability tags enforced in code by sdlc-gate (implement requires coding), confirm the target branch before writing any file, then claim a ready work package from ANALYZE_CONTENTS with a work ticket and complete its TDD todos one by one, updating the wiki after every item. A delivery package confirms its content type (API document or user-defined) before its first todo. Ends with jsc-review code-review, then always asks which delivery-document format to produce (DELIVER_{HASH} wiki page or Gitea issue comment) before an optional MAINTAIN_CONTENTS entry. Use when analysis is done and code must be written; not for planning or analysis. --- # implement @@ -23,12 +23,24 @@ All wiki reads and writes go through `jsc-gitea:wiki`. 5. Record the confirmed target branch on the analysis page next to the work ticket, and reuse it as the PR target in `jsc-git:pr`. Completion condition: the user has confirmed the target branch explicitly; never fall back to `develop` silently. 3. **Generate a work ticket**: format `TICKET_{yyyyMMdd}_{HHmmss}_{HASH}`. `{HASH}` = the shared wiki hash for `{owner}/{repo}`, computed by `jsc-gitea/tools/hash-id` (see `jsc-gitea:wiki`). Try to rename the current session to the ticket name (skip when the CLI does not support it). 4. Read `ANALYZE_CONTENTS` via `jsc-gitea:wiki` and list what is unfinished: plan name, HASH, work package number, count of open items. A selectable work package must satisfy all three: **unfinished, dependency-free (or all dependencies done), and not holding a work ticket**. -5. Let the user pick a work package per `jsc-ask:ask` rules (options state open-item count and estimated effort). **List handover packages (交接 `是`) first** — the analysis page ranks spec delivery ahead of implementation, so keep that order in the options. Write the ticket into that work package's ticket column (the zh-TW field 「工作證」) on the analysis page and save it back to the wiki. **Only after the ticket is saved successfully may you proceed.** -6. List every open item of the work package and implement them **one at a time**: +5. Let the user pick a work package per `jsc-ask:ask` rules (options state open-item count and estimated effort). **List delivery packages (交付 `是`) first** — the analysis page makes `WP-01` the standalone delivery package, so keep that order in the options. Write the ticket into that work package's ticket column (the zh-TW field 「工作證」) on the analysis page and save it back to the wiki. **Only after the ticket is saved successfully may you proceed.** +6. **When the package taken is a delivery/handover package, confirm its content before doing any of its todos**: + 1. Ask per `jsc-ask:ask` rules what this delivery must contain. The default options are fixed: **1. API 文件** (endpoint path, **every** input parameter, **every** output parameter) and **2. 由使用者輸入** (the user states the content themselves). State the impact scope on each. **Never assume the type, and never skip this — the answer decides what the whole package produces.** + 2. Chose API 文件 → follow `references/deliver-formats.md`: all parameters listed (not just the main ones), each with name, type, required flag, example, data source and new-versus-existing status; sample values take real sources first and are labelled `真實：{來源}` or `推論：無來源`; **an existing endpoint must mark new versus old parameters both ways** — the status column (🆕 新增 / ⚠️ 變更 / ❌ 移除 / blank for untouched) and a `diff` code block for colour. HTML `style` attributes get filtered by the wiki, so never rely on them. + 3. Chose 由使用者輸入 → produce exactly what the user described; do not force the API document layout onto it. + 4. Record the confirmed type in the analysis page's 交付型別 column and save it before starting the todos. +7. List every open item of the work package and implement them **one at a time**: - Follow the TDD loop: red before green, one slice at a time; rules and anti-patterns in `references/tdd.md` (refactoring belongs to the review stage). - After each item, flip its `[ ]` to `[x]` on the analysis page and save to the wiki before starting the next item. -7. When all items are done, call `jsc-review:code-review` and wait for the review; on failure, fix and re-review until it passes. -8. Ask per `jsc-ask:ask` rules whether to register this project for maintenance: append to `MAINTAIN_CONTENTS` with `templates/maintain-contents.md`. Required: repository `{owner}/{repo}`, maintenance method, start date. Optional: end date (NULL = maintain forever), last-maintained time. +8. When all items are done, call `jsc-review:code-review` and wait for the review; on failure, fix and re-review until it passes. +9. **Delivery document** — a finished work package is a delivery, so **always ask before producing it; never pick a format silently and never skip this step**: + 1. Ask per `jsc-ask:ask` rules which format to produce. The options are fixed: **a `DELIVER_{HASH}` wiki page** or **a Gitea issue comment**. State the impact scope on each (the wiki page lives beside the plan and analysis pages; the issue comment reaches whoever follows that issue). + 2. Both formats use the same structure — `templates/deliver-page.md`, in Traditional Chinese. Only the destination differs. + 3. Wiki page: write `DELIVER_{HASH}` through `jsc-gitea:wiki`, where `{HASH}` comes from `jsc-gitea/tools/hash-id` over `{owner}/{repo}` plus the work package number (for example `plugins/sdlc#WP-01`), so each work package gets its own page instead of overwriting the previous one. A new page is added to `DELIVER_CONTENTS` per `templates/deliver-contents.md`. + 4. Issue comment: confirm the issue number with the user (propose the one referenced by the work package or the PR; never guess), then post via `gitea/tools/gitea.sh api POST /repos/{owner}/{repo}/issues/{n}/comments` with the body passed in as a UTF-8 file — real newlines, never a literal `\n`. + 5. Sample values follow the analysis page's 資料來源 column: `真實：{來源}` for real sources, `推論：無來源` for reasoned ones. Personal data never goes in — keep the field and format, drop the value. + 6. Completion condition: the chosen format has actually been produced, and you have reported where it landed (wiki page name, or the comment URL). +10. Ask per `jsc-ask:ask` rules whether to register this project for maintenance: append to `MAINTAIN_CONTENTS` with `templates/maintain-contents.md`. Required: repository `{owner}/{repo}`, maintenance method, start date. Optional: end date (NULL = maintain forever), last-maintained time. ## Rules diff --git a/skills/plan/SKILL.md b/skills/plan/SKILL.md index a2e1b59..4461828 100644 --- a/skills/plan/SKILL.md +++ b/skills/plan/SKILL.md @@ -20,10 +20,12 @@ All wiki reads and writes go through `jsc-gitea:wiki`. 4. Exit 0 means the stage is locked. From now until the next stage's gate runs, the sdlc-gate hook blocks every prompt whose model stops satisfying the tags. 2. Read `PLAN_CONTENTS` via `jsc-gitea:wiki` and list the plans whose status is the literal 「未分析」 (not analyzed), with names and HASH. 3. Let the user choose per `jsc-ask:ask` rules: **extend an existing plan** (list the not-analyzed plans as options) or **create a new plan**. State the impact scope on every option. -4. Question via the `jsc-ask:ask` decision tree until no doubt remains on all three items; keep asking while consensus is missing: +4. **Keep questioning until consensus** — rules in `references/consensus.md`, which is the single authority for both planning and analysis. Cover all three items: - Goal: the problem to solve and the criteria for success. - Scope: what is included, what is excluded, which repositories are involved. - Feasibility: whether the system architecture and data sources support the goal. + + **One round is never enough**: every answer must produce the next question, derived from what that answer just exposed. Consensus needs both conditions from `references/consensus.md` — no remaining unknown that would change the output, **and** the user's explicit confirmation of the summary you read back. Never fill a gap with your own assumption, and never move on to user stories while any item is still open. 5. Turn the consensus into **user stories** (the zh-TW pattern 「身為⋯⋯我想要⋯⋯以便⋯⋯」), one per line. 6. Apply `templates/plan-page.md` to create or update the plan page, and write it back via `jsc-gitea:wiki`. The page content is Traditional Chinese, exactly as the template dictates. 7. If the plan page is new, add it to `PLAN_CONTENTS` using the entry format of `templates/plan-contents.md`, with status set to the literal 「未分析」. @@ -33,3 +35,4 @@ All wiki reads and writes go through `jsc-gitea:wiki`. - Never output a code snippet. - Never modify any file in the working directory. - Never skip the decision tree and assume requirements. +- Never stop questioning after one round; consensus is reached only under `references/consensus.md`, and the user says so. diff --git a/templates/analyze-page.md b/templates/analyze-page.md index 3ea0e87..8747598 100644 --- a/templates/analyze-page.md +++ b/templates/analyze-page.md @@ -14,28 +14,39 @@ - 複用來源：[[REPO_{HASH}]]（commit sha：`{sha}`） - 複用決策：{複用哪些方法/端點、為什麼；不複用的原因} +## 未決項 + + + +| 項目 | 影響 | 預設處理 | 待決定者 | +| --- | --- | --- | --- | +| {項目} | {不決定會怎樣} | {暫定做法} | {誰} | + ## 工作分解結構（WBS） -交接工作包（規格、介面、驗收條件）排在實作工作包之前；實作為候補。相依關係優先於交接排序。 +`WP-01` 固定是交付／交接工作包，獨立成一包，不與實作合併；用到它規格的實作工作包相依於它。 +交付型別於實作階段開工時確認（API 文件／由使用者輸入）。 資料來源欄記錄範例資料的出處：`真實：{來源}` 或 `推論：無來源`。 -| 編號 | 工作包名稱 | 交接 | 相依 | 工時(h) | 天數 | 資料來源 | 工作證 | 狀態 | -| --- | --- | --- | --- | --- | --- | --- | --- | --- | -| WP-01 | {規格類名稱} | 是 | - | {h} | {d} | 真實：{來源} | | 未完成 | -| WP-02 | {交接文件名稱} | 是 | WP-01 | {h} | {d} | 真實：{來源} | | 未完成 | -| WP-03 | {實作類名稱} | 否 | WP-01 | {h} | {d} | 推論：無來源 | | 未完成 | +| 編號 | 工作包名稱 | 交付 | 交付型別 | 相依 | 工時(h) | 天數 | 資料來源 | 工作證 | 狀態 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| WP-01 | {交付／交接：規格與介面定義} | 是 | API 文件 | - | {h} | {d} | 真實：{來源} | | 未完成 | +| WP-02 | {實作類名稱} | 否 | - | WP-01 | {h} | {d} | 真實：{來源} | | 未完成 | +| WP-03 | {實作類名稱} | 否 | - | WP-01 | {h} | {d} | 推論：無來源 | | 未完成 | -- 關鍵路徑：{WP-01 → WP-03 → ⋯⋯}，總天數 {d} -- 交接批次：{WP-01、WP-02}；實作候補：{WP-03、⋯⋯} +- 關鍵路徑：{WP-01 → WP-02 → ⋯⋯}，總天數 {d} +- 實作候補：{WP-02、WP-03、⋯⋯} ## 待辦事項（TDD） -### WP-01 {工作包名稱} +### WP-01 {交付／交接工作包名稱} + +- [ ] 盤點端點與參數：{對象} +- [ ] 產出規格與範例資料（標明真實／推論） +- [ ] 與使用者確認交付內容並產出交付文件 + +### WP-02 {工作包名稱} - [ ] 撰寫 {對象} 的測試：{預期行為} - [ ] 實作 {對象} 使測試通過 - [ ] 重構 {對象} 並保持測試綠燈 - -### WP-02 {工作包名稱} - -- [ ] ⋯⋯ diff --git a/templates/deliver-contents.md b/templates/deliver-contents.md new file mode 100644 index 0000000..18708d0 --- /dev/null +++ b/templates/deliver-contents.md @@ -0,0 +1,7 @@ +# 交付目錄 + + + +| 計畫名稱 | 工作包 | 交付 | 交付型別 | 交付頁 | HASH | 存取庫 | 交付時間 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| {計畫名稱} | WP-01 {工作包名稱} | 是 | API 文件 | [[DELIVER_{HASH}|{WP-01 工作包名稱}]] | {HASH} | {owner}/{repo} | {yyyy-MM-dd HH:mm:ss} | diff --git a/templates/deliver-page.md b/templates/deliver-page.md new file mode 100644 index 0000000..ed8e3b1 --- /dev/null +++ b/templates/deliver-page.md @@ -0,0 +1,81 @@ +# 交付：{計畫名稱} {WP-nn} {工作包名稱} + +- 頁名：`DELIVER_{HASH}` +- HASH：`{HASH}` +- 對應分析：[[ANALYZE_{HASH}]] +- 存取庫：`{owner}/{repo}` +- 目標分支：`{使用者確認的目標分支}` +- 工作證：`TICKET_{yyyyMMdd}_{HHmmss}_{HASH}` +- 交付工作包：是 +- 交付型別：API 文件 +- 交付時間：{yyyy-MM-dd HH:mm:ss} + +## 交付內容 + +| 項目 | 說明 | +| --- | --- | +| 這次交付什麼 | {一句話講清楚接手者拿到什麼} | +| 接手者需要做什麼 | {下一步動作；沒有就寫「無」} | +| 尚未交付的部分 | {留在候補的實作工作包，或寫「無」} | + +## API 文件 + + + +### {方法} {端點路徑} + +- 端點狀態：本次新增 +- 說明：{這個端點做什麼} + +標示規則：🆕 **新增**、⚠️ **變更**、❌ **移除**（含淘汰時程）、既有參數留空。 +資料來源：`真實：{來源}` 或 `推論：無來源`。範例只留格式，個資不留值。 + +#### 輸入參數（全部） + +| 參數 | 位置 | 型別 | 必填 | 範例 | 資料來源 | 狀態 | +| --- | --- | --- | --- | --- | --- | --- | +| {name} | path／query／header／body | {型別} | 是／否 | {值} | 真實：{來源} | 🆕 **新增** | + +#### 輸出參數（全部） + +| 參數 | 型別 | 說明 | 範例 | 資料來源 | 狀態 | +| --- | --- | --- | --- | --- | --- | +| {name} | {型別} | {說明} | {值} | 真實：{來源} | | + +#### 錯誤回應 + +| 狀態碼 | 條件 | 回應結構 | +| --- | --- | --- | +| {400} | {條件} | {結構} | + +#### 新舊差異 + + + +```diff + {方法} {端點路徑} + {既有參數} {型別} {必填} ++ {新增參數} {型別} {必填} {預設值}（本次新增） +- {移除參數} {型別} {必填} （本次移除，{日期} 前相容） +! {變更參數} {型別} {必填} （本次變更：{變更內容}） +``` + +### 驗收條件 + +- [ ] {可驗證的條件} + +## 變更檔案 + +| 檔案 | 變更 | +| --- | --- | +| `{path}` | {做了什麼} | + +## 驗證方式 + +| 項目 | 指令或步驟 | 結果 | +| --- | --- | --- | +| {測試} | `{指令}` | {通過／失敗} | + +## 已知限制 + +- {限制或風險；沒有就寫「無」}