design

/design — 開發設計

接收功能需求，自動盤點可用資源（agents/skills），透過 Plan agent 建立完整實作計畫並輸出至 plans/active/.md。不會自動執行實作，必須等使用者確認。

Step 0: 任務追蹤（預設文字清單，不打斷）

追蹤預設不依賴 Task 工具。 TaskCreate / TaskUpdate / TaskList 在 Opus 4.8、Sonnet 5、Fable 5、Mythos 5 及更新模型上預設不存在（Claude Code v2.1.233 起，見 rules/task-tracking-availability.md）。預設做法：在回覆內維護編號 Step 清單並逐項標記狀態——精度與工具相同，差別只在沒有 UI 面板。

規劃階段（Step 1–4）不為 task tracking 單獨發 AskUserQuestion。 且 session 沒有 Task 工具時，Step 6 批次詢問的「Task 追蹤」題直接剔除——不要問一個當下開不了的開關（env var 要重啟 session 才生效）。只有 session 確實有 Task 工具（使用者設了 CLAUDE_CODE_ENABLE_TODO_TOOLS=1 或 --allowedTools）時才併入該批次詢問。使用者已明示啟用 → 逕行以 TaskCreate 建子任務（含 activeForm、必要時 addBlockedBy），完成後 TaskUpdate 為 completed；呼叫失敗即 continue，不中止流程。

為什麼延後：HITL 等待是 /design→實作全程 wall-clock 的最大成本。2026-07-16 PDT-10398 session 實測：3.5h 全程中 ~85–100 min 在等使用者回覆，其中 ~40 min 來自 4 個「分散在流程各處、各自 block」的 AskUserQuestion（Task 追蹤、Worktree、推進方式、編隊授權）。這四題彼此獨立、答案都在「怎麼執行」這一類，合併成 plan 寫入後的一次詢問即可——分散問則每一題都可能撞上使用者離開的空窗。

Step 1: 盤點可用資源

追蹤： 於回覆的 Step 清單把「盤點可用資源」標為進行中，完成後標為完成。（session 有 Task 工具且已啟用時改用 TaskCreate(subject: "盤點可用資源", activeForm: "掃描 agent/skill 中...") → TaskUpdate(status: "completed")）

盤點 Claude Code 內建資源作為規劃參考：

1. Agent types：Plan（規劃，見 Step 3）、Explore（唯讀搜尋定位）、general-purpose（多步驟研究/審查，見 Step 4a）
2. 內建 skills：/code-review（品質審查）、/security-review（安全審查）、/simplify（reuse/簡化/效率清理）、/verify（端對端行為驗證）
3. 本 repo 自持 agents/ 定義（見 agents/README.md 索引）：complexity-triage（Step 2a 分診）、doc-reviewer（Step 4a 審查）、doc-updater（供 /update 使用）、tdd-guide（新功能/bug 修復缺測試覆蓋時，可引用其紅－綠－重構流程）
4. 根據使用者需求（$ARGUMENTS）篩選出相關的資源

輸出： 一份簡潔的資源清單，標記每個資源與當前需求的關聯程度（高/中/低）。

Step 2: 複雜度評估

Step 2a: 分診 subagent（先於一切重流程）

進入完整流程前，先派一個輕量分診 agent 判定複雜度——不讓主模型憑印象判斷，也不讓可走快速路徑的任務直接掉進完整儀式（2026-07-10 使用者指示）：

Agent(subagent_type="general-purpose", model="haiku")

haiku 即低成本層級。依 agents/complexity-triage.md 的定義執行（分診流程、判準表、紅旗皆以該檔為權威版本）；prompt 附上該檔內容或直接引用路徑。路徑解析與呼叫慣例見 agents/README.md。

• 輸入：$ARGUMENTS + 對話中的需求脈絡（/notion-plan 來源含整理後的 Markdown）+ 專案根目錄路徑
• 動作：只允許 Glob/Grep/Read 粗估影響面（找出可能要改的檔案、判斷有無方案取捨），不深讀、不設計方案；輸出契約見 agents/complexity-triage.md 的「輸出格式」章節（唯一權威，不在此重複 JSON schema）
• 主模型裁決：對照下表採納或否決——分診結果與主模型判斷衝突時，取較高複雜度（分診只准降級失敗、不准升級失敗）；ambiguous_requirements=true → 先 AskUserQuestion 補需求再重分診
• 分診 agent 約 5-15K tokens，換到的是：低複雜度任務跳過 Plan agent 全儀式 + 61K-token 審查 agent 的成本

Step 2b: 路徑判定

根據分診結果，選擇執行路徑：

複雜度	判斷標準	執行路徑
低（快速路徑）	單一 bug fix 或小型變更：≤3 檔、無架構決策、修法方向明確（例：顯示邏輯 bug、更新 README、改設定）	Step 3（精簡計畫，見下）→ Step 4a 改主模型 self-check（不派 subagent）→ Step 4b
中等以上	跨檔案且有架構影響、或修法方向需要取捨	Step 3（含架構決策）→ Step 4（含架構審查）
多 session	需跨 session 持續推進的大型計畫（遷移框架、多天重架構）	走標準流程產出 plan，跨 session 推進交給 /plan-run（state 持久化於 plans/active/.plan-state/）

快速路徑的存在理由（2026-07-10 PDT-10428 前例）：一個 P2 顯示 bug 走完整儀式，產出業界參照表、社群共識表、RTM、threat model 後，再被 61K-token 審查 agent 以「缺效能評估段落」「缺文件影響章節」等格式官僚項目打回重修——4 個 FAIL 沒有一個改變實作方向。儀式成本要與風險×不可逆性成比例，不與流程完整度成比例。檔案數不是唯一判準：bug fix 常跨 2-3 檔（util + 元件 + 測試）但仍是單一決策，屬快速路徑；反之單檔但涉及方案取捨（快取策略、狀態管理選型）走中等。

如果需求過於模糊無法判斷複雜度，使用 AskUserQuestion 請使用者補充具體資訊。

無論走哪條路徑，都會輸出 plans/active/.md。

Step 3: Plan agent — 建立實作計畫

追蹤： 於回覆的 Step 清單把「Plan agent 建立實作計畫」標為進行中，完成後標為完成。（session 有 Task 工具且已啟用時改用 TaskCreate(subject: "Plan agent 建立實作計畫", activeForm: "Plan agent 規劃中...") → TaskUpdate(status: "completed")）

使用內建 Plan agent 建立詳細的實作計畫。

Agent(subagent_type="Plan")

輸入 context：

• 使用者的需求描述（$ARGUMENTS + 對話脈絡）
• Step 1 盤點的可用資源清單
• 當前專案結構（透過 ls、git status 等了解）

計畫須包含：

計畫分兩組章節：核心章節（A 組，所有複雜度預設都要） 與 研究章節（B 組，僅風險觸發）。判準是「儀式成本與風險×不可逆性成比例」（見 Step 2b line 57 原則）——複雜度只決定「核心章節的深度」與「Step 4 審查是否派 subagent」，不決定研究章節是否出現。

A 組 — 核心章節（預設全複雜度必含）：

1. 需求拆解 — 將需求分解為可執行的子任務
2. 技術方案 — 每個子任務的實作方式
3. 架構決策（有架構取捨才填，可精簡形式）— 涉及架構的技術選擇須包含：選擇方案及理由、至少 1 個被排除的替代方案及原因、與現有程式碼的相容性、效能與安全性影響；無架構取捨的任務可省略此章節（例：純顯示 bug、文案、設定變更）
4. 可用資源整合 — 明確指出每個步驟應使用哪個 agent/skill（例：「Step 3: 使用 Plan agent」「Step 5: 使用 /code-review」）。資源分配須經 Step 1 盤點確認 — 不可假設資源可用
5. 依賴關係 — 哪些步驟必須按順序執行、哪些可以並行
6. 風險評估 — 潛在的技術風險和對策
7. Security / Threat Model（主動觸發，依 rules/security-guidance/skill-integration.md 的觸發閘）— 先判斷 plan 是否觸及安全敏感面（認證/輸入/endpoint/DB/反序列化/檔案/shell/SSRF/DOM/加密）：觸及 → 必含「Security / Threat Model」章節，逐條對照 ~/.claude/claude-security-guidance.md（與 plugin 同一份判準），且實作後步驟須納入 /security-review；未觸及 → 一句話「無安全敏感面，跳過」，不空列
8. 驗收標準 — 怎樣算完成
9. 測試覆蓋（新功能/修 bug 且缺測試覆蓋時）— 相關步驟可引用 agents/tdd-guide.md 的紅－綠－重構流程，先寫失敗測試再實作，對齊全域 80% 覆蓋率規則
10. Token 預算 — 中等以上逐 step 標【預期 agent 數 × 模型層級 × 預估 token】；低複雜度縮為一行總估算

B 組 — 研究章節（僅在風險觸發時加入；預設整段省略）：

3. 業界實踐與標準化方案參照 — 業界標準/慣例（RFC、W3C、OWASP、12-Factor 等）、學術研究或成熟標準化方案、社群共識與反面意見/已知陷阱的引述
4. 需求追蹤矩陣（RTM） — 每個需求（REQ-1、REQ-2...）映射到實作步驟與驗收標準，供 Step 4a 需求覆蓋率 set-difference 比對

B 組觸發條件（滿足任一才加入，否則省略）：①高風險或不可逆（生產資料遷移、破壞性 schema 變更、金流、認證/授權面）；②引入團隊尚未採用的新架構/新框架/新模式（選型本身要說服他人）；③使用者明確要求嚴謹論證或引用依據。不觸發的預設情境（含多數實作任務，即使跨 multi-session）：功能開發、既有 pattern 的重構、自包含元件/POC、bug 修復——這些只需 A 組核心章節。

B 組未觸發時 Step 4a 審查對應放寬：agents/doc-reviewer.md 的「業界/學術支撐」「社群共識與反面意見」兩維度僅在 B 組觸發時檢查；未觸發時標 N/A，不因缺研究章節判 FAIL。需求覆蓋率在無 RTM 時改用需求清單直接 set-difference。

低複雜度（快速路徑）額外精簡：A 組再砍到 1、2、7、8、10 + Implementation Steps（S-code 格式不變，維持 /plan-run 相容）；4 僅在有架構取捨時填；9 縮為一句話判定。診斷類 step（live 驗證、payload 擷取）不屬儀式、不可裁剪——票面假設與程式碼矛盾時，診斷 gate 是快速路徑中最有價值的部分。

Step 4: 品質檢查與 Plan Mode 呈現

追蹤： 於回覆的 Step 清單把「品質檢查與 Plan Mode 呈現」標為進行中（前置 = Step 3），完成後標為完成。（session 有 Task 工具且已啟用時改用 TaskCreate(subject: "品質檢查與 Plan Mode 呈現", activeForm: "品質檢查與輸出中...", addBlockedBy: [Step 3 TaskCreate 回傳的 task ID]) → TaskUpdate(status: "completed")）

Step 4a: 品質審查（subagent 隔離）

快速路徑（低複雜度）不派 subagent：主模型以 7 項精簡清單 self-check——可執行性（每步有檔案路徑+動作）、依賴正確性、驗收可測、實作後品保步驟存在、診斷 gate 存在（票面假設未經 live 驗證時）、安全敏感面判定、測試覆蓋（新增/修改邏輯有對應測試，或明示不需要的理由，可引用 agents/tdd-guide.md）。任一不過直接改 plan，不進 FAIL 迴圈。以下 subagent 審查僅適用中等以上複雜度。

啟動 general-purpose subagent 在隔離 context 中審查 Step 3 的計畫。不使用已禁用的 architect agent（ECC 版與無前綴版皆禁，消融實驗 delta=-0.50，見 rules/refactor/remove-architect-pipeline.md），改用通用 agent 依 agents/doc-reviewer.md 的定義與檢查清單執行審查。路徑解析與呼叫慣例見 agents/README.md。

Agent(subagent_type="general-purpose", model="sonnet")

prompt：「依 agents/doc-reviewer.md 的定義與檢查清單執行審查」+ 下方 context。

傳入 subagent 的 context：

• Step 3 產出的完整計畫內容
• Step 1 的資源盤點結果
• Step 2 判定的複雜度等級

檢查清單權威版本在 agents/doc-reviewer.md（基礎品質維度 + 架構審查維度 + 研究支撐維度），本段僅保留執行契約摘要：subagent 須逐項檢查並回報結果（PASS/FAIL + 說明）。「業界支撐」「社群共識」兩維度僅在 B 組研究章節觸發時主動驗證（缺引述/引述有誤/未揭露反面意見 → FAIL）；B 組未觸發的精簡計畫這兩維度標 N/A，不判 FAIL。若 agents/ 目錄不存在（安裝不完整），從 https://github.com/ashe-li/agent-skills 的 agents/doc-reviewer.md 取得，或請使用者重跑 npx skills update。

subagent 回報後的處理：

• 全部 PASS： 進入 Step 4b
• 有 FAIL 項目： 回饋至 Step 3 重新規劃（將 FAIL 項目和修正方向作為額外 context 傳給 Plan agent），修正後重新啟動 Step 4a subagent 檢查。初次檢查 + 最多 2 次重試（共最多 3 輪）
• 經 3 輪仍有 FAIL： 在 plan 的 Review Notes 中標記待確認項目，交由使用者決定

Step 4b: EnterPlanMode 呈現計畫

品質檢查通過後，使用 EnterPlanMode 將完整計畫內容呈現給使用者。

為什麼用 Plan Mode： Claude Code 2.1.77+ 在使用者接受 plan 時會自動命名 session。透過 Plan Mode 呈現計畫，使用者 accept 後觸發 session auto-naming，同時作為正式的計畫確認流程。

呈現內容： 將完整 plan（依照下方格式）作為 Plan Mode 的輸出。Plan Mode 中不可使用 Write/Edit，所以只呈現，不寫檔。

使用者 accept 後： ExitPlanMode 觸發 session auto-naming，接著進入 Step 5 寫檔。

長等待可通知：plan 呈現後的 approval 是全流程最長的 HITL 空窗（2026-07-16 實測 43 min——使用者不知道 plan 已就緒就離開了）。呈現 plan 前，若 harness 有 PushNotification 工具，發一則「plan 已就緒待審」通知；Step 6 批次詢問前同理。

Step 5: 生成 Slug 並寫入 plan 檔案

使用者在 Plan Mode 中 accept 後（ExitPlanMode），將計畫寫入檔案。

Slug 生成規則： 從 plan 的 H1 標題（# Implementation Plan: <名稱>）取 : 後的部分轉為 kebab-case（僅保留英數字與 -，中文與特殊字元轉 -、去重複、截斷至 60 字元、全小寫）；純中文標題等無法轉換時用 plan-YYYYMMDD。例：Stripe Subscription Billing → stripe-subscription-billing。

輸出路徑： plans/active/<slug>.md（相對於專案根目錄）

• 若目錄不存在，自動 mkdir -p plans/active/
• 若同名檔案已存在，使用 AskUserQuestion 詢問：覆蓋 / 加日期後綴 / 取消

plan 格式：

# Implementation Plan: [功能名稱]

> Generated by /design on [日期]
> Plan file: plans/active/<slug>.md
> Status: PENDING APPROVAL

## Overview
<!-- 1-3 句話描述目標 -->

## Resources
<!-- 本次計畫使用的 agents/skills -->

| Resource | Type | Usage |
|----------|------|-------|
| Plan | agent | Step 3: 建立實作計畫 |
| /code-review | skill | Step 5: 品質審查 |
| /simplify | skill | Phase 2: dead code、命名、nesting、重複程式碼合併 |
| ... | ... | ... |

<!-- 以下兩張研究表為 B 組，僅在 Step 3 B 組觸發條件成立時填入；否則整段省略 -->
## Industry & Standards Reference（B 組，風險觸發才填）
| 技術決策 | 參照依據 | 類型 | 來源 |
|----------|---------|------|------|
| ... | ... | 業界標準/學術研究/標準化方案/最佳實踐 | ... |

## Community Consensus & Dissenting Views（B 組，風險觸發才填）
| 技術決策 | 社群共識 | 反面意見/已知陷阱 | 來源 |
|----------|---------|------------------|------|
| ... | ... | ... | GitHub/SO/Reddit/... |

## Implementation Steps

<!--
格式約束（/plan-run state machine 需要）：
- Step 標頭：`- [ ] **S<phase>.<num>** — <title>`（S-code 必填，例 S1.1、S1.2、S2.1）
- 欄位：兩個空格縮排 + ASCII 冒號（`  - Files: ...`，不要 bold、不要全形冒號）
- Dependencies 值：純 step ID list（`S1.1, S1.2`），支援 range（`S1.1 ~ S2.3`），禁止自由文字
-->

### Phase 1: [實作階段]
- [ ] **S1.1** — [Step title]
  - Files: src/foo.ts, src/bar.ts
  - Agent: `planner`
  - Action: ...
  - Dependencies: []
  - Why: ...

> **Dependencies canonical form**: 無 deps 時用 `Dependencies: []`（不要省略整個欄位、不要寫 `None` 或留空白），plan_runner.py parser 對 `[]` 一致處理。有 deps 時用 step ID list：`Dependencies: S1.1, S1.2` 或 range `Dependencies: S1.1 ~ S2.3`。

### Phase 2: [品質保障]
- [ ] 執行 /code-review 審查程式碼品質
- [ ] 執行 /simplify 自動修正（dead code、命名、nesting、重複程式碼合併）
- [ ] 執行 /security-review 檢查安全性
- [ ] 執行 /verify 進行全面驗證

### Phase 3: [文件同步]
- [ ] 執行 /update 更新知識庫（文件更新 + 審查 + inline 5 維知識沉澱）
- [ ] 或手動同步相關文件（README、docs/）

## Architecture Notes
<!-- 中等以上複雜度必填 -->
<!-- 每個架構決策：選擇方案、排除的替代方案、相容性分析、效能/安全影響 -->
<!-- 文件影響評估：實作後需新增或更新哪些文件 -->

## Risks & Mitigations
<!-- 風險評估 -->

## Acceptance Criteria
- [ ] ...
- [ ] ...

## Review Notes
<!-- 計畫品質自審的結果 -->

寫入後提示使用者：

plans/active/<slug>.md 已寫入。 可以開始實作；實作完成後執行 /plan-archive 歸檔。

Step 6: 執行模式批次確認（單次 AskUserQuestion，唯一的執行前 HITL 合併點）

plan 寫入後，把所有「怎麼執行」的決策合併成一次 AskUserQuestion（工具單次支援最多 4 題），不分散在流程各處逐一問。批次組成：

題目	選項（第一選項 = Recommended）	何時從批次剔除（答案已知就不問）
Task 追蹤（僅當 session 有 Task 工具）	啟用 (Recommended)（附 token 預估）/ 不啟用	session 沒有 Task 工具即剔除（預設模型即如此，見 rules/task-tracking-availability.md，改用文字清單）；使用者已明示偏好；低複雜度單一 fix 逕行不問
Worktree	是，建 sibling worktree (Recommended) / 否，當前目錄	rules/worktree-prompt.md 跳過條件：已表態、已在 worktree、小型任務
推進方式	依複雜度推薦（下表）	使用者已在 $ARGUMENTS 或對話中明示偏好
編隊授權	啟用並行 (Recommended)（附 token 預估）/ 單路序列	plan 的 Dependencies DAG 無可並行分支；或使用者已表態

• 全部題目都被剔除 → 整個批次跳過，逕行開工。
• 批次後不再為這四類決策發第二次 AskUserQuestion。實作中新發現的裁決（如 code review 挖出的 scope 問題）仍即時問，但發問前先把不依賴該答案的工作派出去（agent 跑著等答案，而不是所有人停著等）。

批次答案的執行細節：

• Worktree = 是：依 rules/worktree-prompt.md 路徑慣例建 sibling worktree（git worktree add ~/Documents/<project>-<slug> -b <branch>），並提示開發完成後執行 /pr。
• 編隊 = 啟用：依 plan 的 Dependencies DAG 並行派工；未啟用則序列推進。
• 推進方式：見下。

推進方式選項

依 Step 2 判定的複雜度給推薦：

複雜度（Step 2 判定）	推薦選項
低（1-3 步、無依賴）	LLM 自主推進
中等（4-10 步、有依賴）	/plan-run（推薦）
高（10+ 步、複雜 DAG、多並行）	/plan-run（強烈推薦；會跨 session 的話再掛 Stop hook）

選項文案（放進批次詢問的「推進方式」題）：

1. /plan-run — 推進順序由狀態機決定、不會跳步；不需要每個 step 手動催，也會定期停下來讓你確認。預設用內建 /goal 提供續推力道（零安裝），跨 session 的長 plan 可改掛 Stop hook。失敗時仍以 AskUserQuestion 交還給人決定
2. LLM 自主推進 — 直接在當前 session 開始實作；簡單線性 plan 適用，無狀態機 overhead
3. 暫不開始 — 結束 /design，由使用者另行決定時機

選項 1 的前置與例外：預設模式零安裝（init --no-attach + 一道 /goal）。只有需要跨 session 續推時才要裝 Stop hook（見 docs/hooks-setup.md），而那條路徑只認 $HOME 底下的 plan——落在 $HOME 之外時掛不上 pointer，用預設模式即可。對 plan 不確定或有高風險不可逆 step 時，可暫停自動推進逐步確認——這些操作都在 /plan-run 文件裡。

若選 1（/plan-run）：

1. normalize 兜底（canonical 格式跑下去是 no-op）：python3 "${AGENT_SKILLS_HOME:-$HOME/Documents/agent-skills}/scripts/plan_runner.py" normalize plans/active/<slug>.md --write。stderr 顯示 Wrote normalized plan → 已 normalize（.bak 備份同目錄）；顯示 WARN: Dependencies prose did not yield step IDs → 該行需手動補 step ID
2. 初始化 state（預設模式 A，零安裝）：python3 "${AGENT_SKILLS_HOME:-$HOME/Documents/agent-skills}/scripts/plan_runner.py" init plans/active/<slug>.md --no-attach。若回 No steps found in plan，依回傳 payload 的 hint 欄位處理；warnings 欄位若僅為 range syntax 已自動展開可忽略
3. 提示使用者（模式 A）。/goal 文字逐字取自 plan-run/SKILL.md Step 1.5，那三處措辭是刻意的，不要改寫：

   State 已初始化於 <state_path>。 下一道指令就會自己跑下去：

   /goal plans/active/<slug>.md 的所有 step 都已 completed 或 skipped——判準是 plan_runner.py 的
   輸出出現 Progress: N/N；或同一個 step 連續 2 輪沒有前進。尚未達成時，下一輪第一個
   動作必須是跑 python3 ~/Documents/agent-skills/scripts/plan_runner.py next plans/active/<slug>.md，
   照它印出的三行做完並回報 complete，不要問使用者是否繼續。
   
   現在開始推進，每輪盡量多推幾步。
   

   隨時可跑 python3 "${AGENT_SKILLS_HOME:-$HOME/Documents/agent-skills}/scripts/plan_runner.py" status plans/active/<slug>.md 查看進度。/clear、compaction、開新 session 會讓 /goal 消失，state file 還在，重下同一道 /goal 就接上。

4. 只有使用者明確要跨 session 續推、且 python3 "${AGENT_SKILLS_HOME:-$HOME/Documents/agent-skills}/scripts/plan_runner.py" doctor 的「Stop hook 已註冊」「wrapper 存在且可執行」兩項都 PASS 時，改走模式 B：把第 2 步的 --no-attach 拿掉重跑一次 init（冪等，會把 cwd 的 pointer 掛上），提示文改為「hook 從下一輪起接手，不要再下 /goal」。plan 在 $HOME 之外時 pointer 掛不上，維持模式 A。兩種驅動器不可同時開——續推輪數上限由所有 blocker 共用，疊加換不到更多步，只換到互相稀釋的指令。

若選 2（LLM 自主推進）： 直接進入標準 implementation flow（plan 仍可隨時切換 /plan-run，state machine init 是冪等的，未來呼叫不影響）。

若選 3（暫不開始）： 結束 /design，告知：Plan 已存於 plans/active/<slug>.md，隨時可執行 /plan-run plans/active/<slug>.md 開始推進，或直接在 session 中開始實作。