| name | dev-workflow-v2 |
| description | 通用軟體開發工作流程，適用於新增功能、修正功能、重構等程式開發需求。 以棕地專案為預設情境（保護既有行為、最小擾動），同時支援綠地專案豁免。 涵蓋五個階段：需求分析、程式碼探索、設計（計畫）、開發（棕地 TDD 任務清單）、驗證。 每個階段會產生對應的 Markdown 文件（analysis.md、plan.md、task.md、followups.md）供下一階段參考。 當使用者提出功能開發、Bug 修復、重構等需求時，主動使用此 Skill 引導整個開發流程。 觸發情境：「新增功能」、「修正功能」、「開發需求」、「implement」、「fix」、「refactor」、「建立需求」、「開發流程」。
|
Dev Workflow
通用軟體開發工作流程，適用於前端與後端開發。預設為棕地專案優先，綠地專案可豁免特定步驟。
流程總覽
flowchart LR
P1["Phase 1<br/>需求分析"] --> P2["Phase 2<br/>程式碼探索"]
P2 -->|產出 analysis.md| P3["Phase 3<br/>設計／計畫"]
P3 -->|產出 plan.md| P4["Phase 4<br/>開發／TDD"]
P4 -->|產出 task.md| P5["Phase 5<br/>驗證"]
subgraph P4_Loop ["Phase 4 — 棕地 TDD 循環"]
C["⚪ Characterize<br/>釘住既有行為"] --> R["🔴 Red<br/>寫新行為失敗測試"]
R --> G["🟢 Green<br/>最少程式碼通過"]
G --> RF["🔵 Refactor<br/>優化但限縮範圍"]
RF -.->|下一個任務| C
end
綠地專案可省略 Characterize 步驟，直接從 Red 開始。
每個階段必須滿足退出條件才能進入下一階段。任何階段發現問題可回退到前一階段修正。
核心紀律（棕地優先）
本流程預設專案為棕地（已有既有程式碼、使用者、測試）。在所有階段中，三條紀律凌駕於其他考量：
- 先理解再修改（Understand-First）：任何修改前，必須先掌握被修改程式碼的呼叫方、行為契約、測試覆蓋狀況。沒有這些資訊就規劃方案，視為流程違規。
- 保護既有行為（Behavior Preservation）：除非需求明確要求改變舊行為，否則所有舊行為必須保持不變。任何修改都應有測試保護「舊行為仍正常」。
- 最小擾動（Minimal Diff）：只修改完成需求所必要的程式碼。不順手重構不相關區域、不順手改格式、不順手「優化」。每一行 diff 都應能回答「這行為什麼必要？」。
綠地專案豁免：若使用者明確聲明這是綠地專案（無既有使用者、無既有測試需保護），可豁免紀律 2 的 characterization 要求。紀律 1 與 3 仍適用。
不該動什麼（硬規則）
LLM 在 Refactor 階段最常見的失誤是「順手改」。以下情境必須停手：
- 與當前任務無直接關聯的檔案 → 不動
- 與當前任務無直接關聯的函式（即便就在同一檔案中）→ 不動
- 程式碼風格、格式、import 順序的「美化」→ 不動（除非任務本身就是 lint/format）
- 看起來「應該重構」但沒有測試保護的舊程式碼 → 不動，只在 followups.md 中記錄
- 第三方套件版本升級 → 不動，需獨立任務處理
若在執行中發現「真的很想改但不在範圍內」的程式碼，記錄到 .tmp/followups.md，由使用者決定是否另開任務。
Self-Check 執行原則
每個 Phase 結束時須執行對應的 self-check checklist。執行 self-check 時：
- 逐項實際驗證，不可橡皮圖章：每一項都必須對照剛產出的文件或程式碼實際確認，不可憑印象勾選
- 未通過項目必須具體說明：若某項打
[ ]，必須在下方寫出「未通過原因」與「補救方式」
- 任一項未通過則退回該階段補完：不可帶著未通過項進入下一階段
- Self-check 結果寫入對應文件末尾：保留檢查痕跡，方便後續追溯
- 使用者可隨時要求重跑 self-check：若使用者對某階段品質有疑慮，重跑該階段 self-check 並回報結果
Self-check 的目的不是形式化驗收，而是強迫 Claude 在切換階段前停下來檢視自己的產出。若發現自己想跳過某項或敷衍勾選，這就是該項真正需要被檢查的訊號。
文件管理規範
所有階段產出的文件統一存放於專案根目錄的 .tmp/ 資料夾下。
文件清單：
.tmp/analysis.md — Phase 1+2 的需求分析與程式碼探索結果.tmp/plan.md — Phase 3 的設計計畫與技術決策.tmp/task.md — Phase 4 的開發任務 Checklist.tmp/followups.md — 流程中發現但不在當前範圍內的改進建議
備份規則：
- 產生新文件前，檢查是否已存在同名文件
- 若存在，將舊文件重新命名為
{原檔名}.{YYYYMMDD-HHmmss}.md（例如 analysis.20250611-143022.md）
- 再建立新文件
目錄初始化：
- 每次流程開始前，確認
.tmp/ 目錄存在，若不存在則建立
- 建議將
.tmp/ 加入 .gitignore
followups.md 範本
# 後續建議事項
> 產生時間：{YYYY-MM-DD HH:mm}
> 來源需求：{需求摘要}
本流程中發現但**不在當前範圍**的改進機會。請評估是否另開任務處理。
## 建議項目
### 1. {標題}
- **發現於**：Phase {N}, {context}
- **位置**：`{file:line}`
- **現況**：{描述}
- **建議**：{描述}
- **優先級**：高/中/低
- **預估規模**：小型/中型/大型
Phase 1: 需求分析
目的：釐清「做什麼」和「為什麼」。
執行步驟：
- 確認需求的具體內容和範圍
- 使用 AskUserQuestion tool 與使用者互動，釐清模糊點和不確定的部分。主動提問而非假設，典型問題包含：
- 功能的邊界在哪裡？（做到什麼程度、不做什麼）
- 是否有相關的 UI/UX 設計稿或 wireframe？
- 是否有既有的類似功能可參考？
- 對效能、相容性是否有特殊要求？
- 這是棕地或綠地專案？是否有既有使用者/行為需要保護？
- 定義驗收標準，必須分為兩類：
- Positive Criteria（新行為）：本次需求要達成的新功能、新能力
- Regression Criteria（舊行為保護）：哪些既有行為在本次修改後必須保持不變
- 若無法列出 Regression Criteria（例如不知道目前有哪些行為），這就是 Phase 2 探索的明確目標之一
- 識別可能的風險和限制
退出條件：
- 需求範圍明確，無模糊地帶
- 雙欄驗收標準已列出並獲使用者確認
- 已識別已知風險和限制
Phase 1 Self-Check
在進入 Phase 2 前，逐項確認：
未通過項目處理：
{若有 [ ] 項，於此說明原因與補救方式}
產出：向使用者輸出需求摘要，包含範圍、雙欄驗收標準、風險。等待使用者確認後進入 Phase 2。
注意：Phase 1 的結果暫存於記憶中，待 Phase 2 完成後一併寫入 analysis.md。
Phase 2: 程式碼探索
目的：了解現有架構、行為契約、風險訊號，為設計提供依據。
執行方式：使用 Agent tool（subagent_type: Explore）派出子代理進行三軸探索：靜態軸、動態軸、歷史軸。每軸可獨立派一個 sub-agent 並行執行，避免大量搜尋結果佔用主要 context window。
靜態軸：程式碼結構
根據以下需求，探索程式碼庫的靜態結構並回報：
1. 與需求相關的檔案清單（路徑、用途、是否需修改）
2. 現有架構模式與設計慣例（命名、結構、風格）
3. 相關模組的相依關係（depends on / depended by）
需求描述：{從 Phase 1 得到的需求摘要}
動態軸：行為契約與影響範圍
針對以下需修改的目標檔案/函式，回報：
1. 反向依賴：誰呼叫了這些函式？列出所有呼叫點（檔案 + 行號）
2. 行為契約：呼叫方對這些函式有哪些隱含假設？
- 輸入格式假設
- 回傳值/副作用假設
- 錯誤處理假設（會不會 throw？回 null？）
- 執行順序假設（同步/非同步、前置條件）
3. 測試覆蓋現況：
- 哪些行為已有測試保護？（列出測試檔案 + 測試名稱）
- 哪些行為「沒有」測試保護？（這是 Phase 4 需要補 characterization tests 的區域）
4. 資料流：相關資料從哪裡來、到哪裡去？是否跨越 API/DB/外部服務邊界？
目標檔案/函式：{從靜態軸結果得到的修改目標}
歷史軸：風險訊號
針對以下檔案，從 git history 蒐集風險訊號：
1. 過去 6 個月的修改頻率（高頻修改 = 不穩定區域 = 高風險）
2. 是否有 revert commit？revert 的原因？
3. 最近一次重大變更的 commit message 與相關 PR 描述
4. 是否有 TODO / FIXME / HACK 註解？內容為何？
目標檔案：{從靜態軸結果得到的修改目標}
執行順序：靜態軸通常先做，動態軸與歷史軸可並行。若任一軸的回報不夠完整，可追加探索或在主 context 中補充閱讀關鍵檔案。
退出條件：
- 已掌握相關程式碼的結構和模式（靜態軸完成）
- 已識別所有反向依賴與行為契約（動態軸完成）
- 已掌握風險訊號（歷史軸完成）
- 已識別需要補 characterization tests 的區域
Phase 2 Self-Check
在進入 Phase 3 前，逐項確認 .tmp/analysis.md：
結構完整性：
內容深度（這幾項最容易敷衍，要特別檢查）：
棕地專案額外檢查（綠地可略）：
未通過項目處理：
{若有 [ ] 項，於此說明原因與補救方式}
產出：
- 向使用者報告探索結果，列出影響範圍、風險評級、關鍵發現
- 產生
.tmp/analysis.md，內容結構如下：
# 需求分析與程式碼探索報告
> 產生時間：{YYYY-MM-DD HH:mm}
> 需求摘要：{一句話描述}
> 專案類型：棕地 / 綠地
## 1. 需求分析
### 1.1 需求描述
{需求的具體內容}
### 1.2 需求範圍
{功能範圍與邊界}
### 1.3 驗收標準
#### 1.3.1 Positive Criteria（新行為）
- [ ] {新功能應達成的標準 1}
- [ ] {新功能應達成的標準 2}
#### 1.3.2 Regression Criteria（舊行為保護）
- [ ] {既有功能 X 在修改後仍正常運作}
- [ ] {既有 API contract 不變}
- [ ] {既有資料格式仍能處理}
### 1.4 風險與限制
- {風險 1}
- {風險 2}
## 2. 程式碼探索
### 2.1 相關檔案清單（靜態軸）
| 檔案路徑 | 用途 | 需修改 | 修改類型 |
|---------|------|--------|---------|
| {path} | {description} | ✅ / ❌ | 新增/修改/刪除 |
### 2.2 現有架構與慣例
- 架構描述：{description}
- 命名規則：{description}
- 設計模式：{description}
### 2.3 反向依賴與行為契約（動態軸）
針對每個需修改的目標：
#### {目標函式/模組 1}
- **呼叫方**（共 N 處）：
- `{file}:{line}` — {使用情境}
- **行為契約**：
- 輸入：{假設}
- 輸出：{假設}
- 錯誤：{假設}
- 順序：{假設}
- **測試覆蓋**：
- 已覆蓋：{test file/name}
- **未覆蓋**（Phase 4 須補 characterization）：{behavior description}
### 2.4 風險訊號（歷史軸）
| 檔案 | 修改頻率 | revert 紀錄 | TODO/FIXME | 風險評級 |
|------|---------|------------|-----------|---------|
| {path} | {N times / 6mo} | {yes/no} | {內容} | 高/中/低 |
### 2.5 影響範圍總評
{綜合三軸資訊，評估本次修改的影響範圍與風險等級}
Phase 3: 設計（計畫）
目的：決定「怎麼做」，制定具體的實現方案，並選定修改策略以控制風險。
輸入：讀取 .tmp/analysis.md 作為設計依據。
重要：此階段不使用 EnterPlanMode。由 skill 自行管理計畫流程，確保後續階段不被中斷。
執行步驟：
-
讀取 .tmp/analysis.md，掌握需求、行為契約、測試空白區、風險訊號
-
選擇修改策略（棕地必做）：
根據 analysis.md 的反向依賴數量、風險評級、是否影響 public API，從以下策略中選擇一種或組合：
| 策略 | 適用情境 | 代價 |
|---|
| 直接修改 | 反向依賴 ≤ 3、無 public API、低風險區 | 最簡單，但測試保護要求高 |
| Adapter / Wrapper 隔離 | 需改變內部實作但要保留外部介面 | 多一層間接，但隔離風險 |
| 平行新舊並存（Strangler Fig） | 大型重構或邏輯顛覆，無法一次切換 | 短期程式碼膨脹，長期可控 |
| Feature Flag | 需要漸進釋出或快速回滾能力 | 增加分支，但提供安全網 |
| 新建+棄用（不刪） | 既有 API 不能立即移除（外部使用者） | 留下 dead code，需後續清理計畫 |
策略選擇必須寫入 plan.md 並說明理由。
-
確認與本次需求直接相關的技術決策：
- 確認涉及的框架、套件版本，僅記錄影響設計方案的項目
- 確認測試框架與相關工具
-
查閱最新技術文件（必要時）：
- 套件相關：使用 MCP tool
mcp__context7__resolve-library-id 解析相關套件的 library ID，再使用 mcp__context7__query-docs 查詢最新的 API 用法、最佳實踐、breaking changes
- 專案內部歷史決策：用 git log / grep 查相關 commit、CHANGELOG、註解
- 適用情境：引入新依賴、不確定既有寫法是否仍是最佳實踐、看到不熟悉的內部慣例
-
設計解決方案，包含：
- 修改清單（新增/修改/移除）
- Rollback 策略：萬一修改後發現問題，如何快速回退？
- 資料相容性：是否涉及資料格式變更？舊資料如何處理？
- 邊界情況與錯誤處理
-
向使用者呈現完整設計方案，使用 AskUserQuestion 確認或調整
-
確認後產生 .tmp/plan.md
退出條件：
- 修改策略已選定且有明確理由
- 實現方案具體且可執行
- Rollback 策略明確
- 方案已獲使用者明確確認
.tmp/plan.md 已產生
Phase 3 Self-Check
在進入 Phase 4 前，逐項確認 .tmp/plan.md：
結構完整性：
修改策略品質（最容易敷衍的環節）：
Rollback 品質：
對齊使用者：
未通過項目處理：
{若有 [ ] 項，於此說明原因與補救方式}
產出：
產生 .tmp/plan.md，內容結構如下：
# 設計計畫
> 產生時間：{YYYY-MM-DD HH:mm}
> 需求摘要：{一句話描述}
> 參考文件：.tmp/analysis.md
## 1. 技術決策
與本次需求相關的技術選型與版本確認：
| 項目 | 版本 | 決策理由 |
|------|------|---------|
| {item} | {version} | {reason} |
### Context7 / 內部歷史查閱結果（如有）
| 來源 | 查閱重點 | 關鍵發現 |
|------|---------|---------|
| {package / commit / PR} | {query topic} | {findings} |
## 2. 修改策略
**選定策略**：{直接修改 / Adapter 隔離 / Strangler Fig / Feature Flag / 新建+棄用}
**選擇理由**：
- 反向依賴數：{N}
- 風險評級：{高/中/低}
- 是否影響 public API：{是/否}
- 其他考量：{description}
**策略落地方式**：
{具體說明這個策略在本次需求中如何實現，例如「在 X 模組新增 Adapter，舊呼叫方繼續走原 API，內部委派到新實作」}
## 3. Rollback 策略
**回退觸發條件**：{什麼情況下需要 rollback}
**回退方式**：
- [ ] {步驟 1，例如「revert commit X」}
- [ ] {步驟 2，例如「關閉 feature flag Y」}
## 4. 資料相容性
- 是否涉及資料格式變更：{是/否}
- 舊資料處理：{description}
- 遷移計畫（如有）：{description}
## 5. 規劃方向
### 5.1 新增項目
| 項目 | 說明 | 理由 |
|------|------|------|
| {item} | {description} | {reason} |
### 5.2 修改項目
| 項目 | 現狀 | 調整方向 | 理由 |
|------|------|---------|------|
| {item} | {current} | {planned} | {reason} |
### 5.3 移除項目（如有）
| 項目 | 理由 |
|------|------|
| {item} | {reason} |
## 6. 實現方案
### 6.1 架構設計
{整體設計思路與架構圖（如有）}
### 6.2 修改檔案清單
| 檔案路徑 | 操作 | 說明 |
|---------|------|------|
| {path} | 新增/修改/刪除 | {description} |
### 6.3 邊界情況與錯誤處理
- {case 1}
- {case 2}
## 7. 風險評估
- {risk 1}
- {risk 2}
Phase 4: 開發（棕地 TDD 任務清單）
目的：以棕地 TDD 循環（Characterize → Red → Green → Refactor）逐步實現設計方案，以 .tmp/task.md 的 Checklist 追蹤進度。
輸入：讀取 .tmp/plan.md 作為開發依據。
執行步驟：
- 讀取
.tmp/plan.md，掌握修改策略與規劃方向
- 將設計方案拆分為可獨立執行的小任務
- 產生
.tmp/task.md，以 Checklist 格式列出所有任務
- 依序執行每個任務，每個任務遵循棕地 TDD 循環：
單一任務的棕地 TDD 循環
Step 0: Characterize（特徵測試）— 釘住既有行為
綠地專案可跳過此步驟，直接從 Step A 開始。
- 檢查 analysis.md 的「測試覆蓋現況」，確認本任務涉及的程式碼有哪些「未覆蓋」的既有行為
- 為這些未覆蓋的既有行為撰寫 characterization tests：
- 不是測試「應該做什麼」，而是測試「目前實際做什麼」
- 包含正常路徑、邊界值、錯誤情境
- 測試名稱以
characterize_ 或 legacy_behavior_ 為前綴，方便識別
- 執行測試，確認全部通過（這證明你正確理解了既有行為）
- 若測試失敗，代表你對既有行為的理解有誤 → 修正測試直到反映真實行為，不修改實作
- 更新
.tmp/task.md 中對應任務的 Characterize 步驟為 [x]
為什麼需要這步：接下來 Green 步驟會修改實作。如果沒有 characterization tests，你無法分辨「測試通過」是因為新行為正確，還是因為新行為意外覆蓋了你不知道的舊行為。
Step A: Red（紅燈）— 寫新行為失敗測試
- 根據任務需求與
.tmp/analysis.md 中的 Positive Criteria，撰寫對應的測試案例
- 測試應描述「期望的行為」，而非「實作細節」
- 執行測試，確認測試失敗（紅燈）
- 若測試直接通過，需判斷原因：
- (a) 功能已存在 → 確認確實符合需求後，可跳過此任務
- (b) 測試不夠精確 → 加強斷言條件，使其能區分正確與錯誤行為
- 更新
.tmp/task.md 中對應任務的 Red 步驟為 [x]
Step B: Green（綠燈）— 寫最少程式碼讓新測試通過
- 撰寫最少量的程式碼讓 Red 測試轉為綠燈
- 目標是「讓測試通過」，暫不考慮程式碼美觀或最佳化
- 同時執行 Characterization tests，確認既有行為仍然通過
- 若 Characterization 測試紅燈，代表你的修改打破了舊行為 → 必須調整實作或修改策略，不可移除/降級 characterization 測試
- 全部綠燈後，更新
.tmp/task.md 中對應任務的 Green 步驟為 [x]
Step C: Refactor（重構）— 嚴格限縮範圍
- 在所有測試（new + characterization）通過的前提下，審視程式碼品質
- 重構範圍硬性限制：
- 只能重構「本任務新增或修改的程式碼」
- 不可重構未在本任務範圍內的程式碼，即便就在隔壁
- 若發現範圍外的重構機會，記錄到
.tmp/followups.md
- 優化方向（僅在有明確需要時進行）：
- 消除重複程式碼
- 改善命名與可讀性
- 簡化過於複雜的邏輯
- 遵循專案的 coding style 和慣例
- 每次重構後重跑全部測試（new + characterization + 既有測試套件）
- 重構不應改變外部行為，只改善內部品質
- 更新
.tmp/task.md 中對應任務的 Refactor 步驟為 [x]
完成一個任務的 Characterize → Red → Green → Refactor 後，再進入下一個任務。
任務粒度原則
- 每個任務應對應一個可獨立 revert 的 commit
- 一個任務不應同時跨越多個 layer（例如不要同時改 API + UI + DB schema）
- 一個任務不應同時修改超過 3 個檔案（不含測試檔案）
- 若任務過大，進一步拆分
退出條件：
.tmp/task.md 中所有項目皆為 [x]- 每個任務的 Characterize → Red → Green → Refactor 皆已走完（綠地可省略 Characterize）
- 程式碼符合專案慣例
Phase 4 Self-Check
Phase 4 的 self-check 分兩層：單任務完成時檢查 TDD 循環、全部任務完成時檢查任務集合品質。
單任務完成 Self-Check（每完成一個 Task 都要跑）
未通過項目處理：
{若有 [ ] 項，於此說明原因與補救方式，必要時回退到對應 TDD 步驟}
全部任務完成 Self-Check（進入 Phase 5 前跑）
未通過項目處理：
{若有 [ ] 項，於此說明原因與補救方式}
產出：
產生並持續更新 .tmp/task.md，內容結構如下：
# 開發任務清單
> 產生時間：{YYYY-MM-DD HH:mm}
> 需求摘要：{一句話描述}
> 參考文件：.tmp/plan.md
> 專案類型：棕地 / 綠地
## 任務列表
### Task 1: {任務標題}
- **涉及檔案**：`{file1}`, `{file2}`
- **測試檔案**：`{test_file}`
- **說明**：{具體要做什麼}
- **對應驗收標準**：Positive {1.3.1.x}, Regression {1.3.2.x}
**棕地 TDD 循環**：
- [ ] Characterize：補 characterization test `{描述}`，確認既有行為通過
- [ ] Red：撰寫新行為測試 `{描述}`，確認紅燈
- [ ] Green：實作程式碼，確認新測試綠燈、characterization 仍綠燈
- [ ] Refactor：審視並優化（限縮在本任務範圍內），確認所有測試仍綠燈
### Task 2: {任務標題}
...（依此類推）
Phase 5: 驗證
目的：確認整體功能正確性、未破壞既有功能、並確保程式碼品質與 diff 紀律。
Phase 4 已確保每個任務各自的單元測試通過。Phase 5 關注「全局」：整合驗證、主動驗證、雙欄驗收標準確認、diff 紀律檢查。
執行步驟：
5.1 自動化驗證（綠燈基線）
- 執行完整測試套件（unit + integration + E2E + characterization），確認既有測試與新增測試皆未被破壞
- 執行型別檢查（如
pnpm type-check）
- 執行建置（如
pnpm build）
- 執行 lint 檢查（如
pnpm lint）
5.2 主動驗證（棕地必做）
- 呼叫方 trace：對照 analysis.md 的反向依賴清單，逐一確認每個呼叫方的使用情境是否仍正常（可透過搜尋 + 人工檢視 + 必要時跑 E2E 涵蓋該路徑）
- Silent failure 檢查：搜尋本次修改範圍內的
try/catch、.catch()、onError，確認沒有把錯誤吞掉
- 資料相容性檢查（若 plan.md 標記涉及資料格式）：
- 用舊格式資料跑一次，確認可處理
- 用新格式資料跑一次，確認可處理
- 效能比對（若涉及熱路徑或大量資料處理）：
- 修改前後跑相同 benchmark，確認無顯著退化
5.3 驗收標準逐項確認
- 對照
.tmp/analysis.md 的雙欄驗收標準：
- 對照
.tmp/plan.md 的修改清單，確認沒有意外的 diff（執行 git diff --stat 檢視）
5.4 Diff 紀律檢查
- 檢視最終 diff，每個 hunk 都應能回答：「這個變更是哪個任務、哪條驗收標準必要的？」
- 若有「順手改」的變更，回退或拆分到獨立 commit
- 確認 followups.md 已記錄所有「想改但沒改」的項目
若任一檢查失敗，回到 Phase 4 以 TDD 循環修正。
退出條件：
- 5.1 全綠
- 5.2 全部主動驗證項目通過（綠地可省略 5.5）
- 5.3 驗收標準（雙欄）逐項滿足
- 5.4 diff 沒有範圍外變更
Phase 5 Self-Check
向使用者宣告「需求完成」前，逐項確認：
自動化驗證實際執行紀錄（不可只說「跑過了」，要附結果）：
主動驗證實際執行紀錄（棕地必填）：
驗收標準逐項對照：
Diff 紀律：
最終產出物：
未通過項目處理：
{若有 [ ] 項，於此說明原因與補救方式，必要時回退到 Phase 4}
產出：向使用者報告最終結果，包含：
- 變更摘要（檔案 + 行數）
- 雙欄驗收標準達成情況
- 主動驗證結果
- followups.md 內容（建議使用者後續處理的事項）
回饋迴圈
任何階段發現需要回退時：
- Characterization 失敗 → 對既有行為的理解有誤，修正測試或回到 Phase 2 重新探索行為契約
- TDD 紅燈無法綠燈 → Red 無法表達需求：回顧
analysis.md；Green 無法通過：回到 Phase 3 調整 plan.md；Refactor 破壞測試：立即還原
- 新行為打破 Characterization → 回到 Phase 3，可能需改用更隔離的修改策略（Adapter / Strangler Fig）
- 設計問題 → 暫停開發，回到 Phase 3 調整
plan.md，告知使用者
- 驗證失敗（測試、type-check、build、呼叫方 trace） → 回到 Phase 4 以 TDD 循環修正
- 需求變更 → 回到 Phase 1 重新分析，重新產生
analysis.md
回退時向使用者說明原因和調整方向。涉及文件更新時，同步更新對應的 .tmp/ 文件。
流程規模判斷
用以下「訊號清單」客觀判斷需求規模。任一高風險訊號出現即升級為大型流程。
訊號評估
| 訊號 | 小型 | 中型 | 大型 |
|---|
| 修改檔案數 | 1 | 2-5 | 6+ |
| 反向依賴數（最大） | ≤ 1 | 2-5 | 6+ |
| 影響 public API | 否 | 否 | 是 |
| 跨 layer 修改 | 否 | 否 | 是 |
| 涉及資料格式變更 | 否 | 否 | 是 |
| 測試覆蓋現況 | 完整 | 部分 | 缺乏 |
| 風險評級（歷史軸） | 低 | 中 | 高 |
| 引入新依賴 | 否 | 否 | 是 |
流程對應
小型流程（所有訊號皆為「小型」欄）：
- Phase 1-2 在主對話中思考即可，可省略 analysis.md
- Phase 3 簡化為一句話設計（修改策略仍須明示）
- Phase 4 仍須走 Characterize → Red → Green → Refactor（綠地可省略 Characterize）
- Phase 5 跑自動化驗證 + 呼叫方 trace 即可
中型流程（訊號落在「中型」欄）：
- 完整產出 analysis.md 和 task.md
- plan.md 可簡化（修改策略與 Rollback 仍須明示）
- 完整走五階段
- Phase 5 須跑 5.1 + 5.2 + 5.3
大型流程（任一訊號落在「大型」欄）：
- 完整走五階段，每階段都與使用者對齊
- 所有 .tmp/ 文件完整產出
- Phase 3 必須使用 Context7 + git history 查閱
- Phase 5 必須跑全部主動驗證項目（5.1 ~ 5.4 全部）
