tdd

name	tdd
description	TDD 紅綠重構開發循環
disable-model-invocation	true

Test-Driven Development

GATE：強制對焦

收到任務後：

1. 複述「我理解你要用 TDD 實作 ___」
2. 確認要測試的行為清單（不是實作步驟）
3. 問「方向對嗎？」

等用戶確認後才開始寫任何程式碼

核心原則

測試驗證行為，不驗證實作。 好測試讀起來像規格書，壞測試跟 diff 一樣。 詳細原則、範例、mocking 指引：Read tests.md、Read mocking.md

禁止反模式：橫向切片

不可以「先寫全部 test，再寫全部 code」。必須垂直切片：

正確：test1→impl1 → test2→impl2 → test3→impl3
錯誤：test1,test2,test3 → impl1,impl2,impl3

工作流程

---

步驟 1：規劃

由主對話（Opus）執行——需要跟用戶對焦方向。

• 設計 public interface（Read interface-design.md）
• 列出要測試的行為（不是實作步驟）
• 識別 deep module 機會（Read deep-modules.md）

模型路由

• 確認要測試的行為清單：主對話（Opus）——需要跟用戶對焦
• 偵察現有測試和程式碼結構：直接 Bash 呼叫

  cursor-agent -f --print "列出 [路徑] 的測試檔案和主要類別"
  

  （零 Anthropic token）

熵減審核

• 熵減：每個要測試的行為，是否對應真實的業務需求？沒有用的行為不測試
• 三問：行為清單讓工程師清楚知道「要建什麼」嗎？
• 量化：行為數量是否合理（5～15 個）？超過 15 個考慮拆分模組
• 有主見：直接指出不必要的行為，不全部接受

---

步驟 2：Tracer Bullet

寫 1 個 test → 紅燈 → 寫最少代碼通過 → 綠燈。確認路徑可通。

模型路由

• 寫第一個紅燈測試：Agent model="sonnet"
• 跑測試確認紅燈：直接 Bash（零 token）

  composer test -- --filter <TestName>
  

• 寫最小實作讓綠燈：Agent model="sonnet"
• 跑測試確認綠燈：直接 Bash（零 token）
• Tracer Bullet 完成確認：主對話（Opus） 展示給用戶

熵減審核

• 熵減：第一個測試是否切到最核心的行為（不是最簡單的行為）？
• 三問：測試名稱用英文描述 WHAT 不 HOW 嗎？
• 量化：實作行數 ≤ 測試驗證的最小需求
• 有主見：不加不必要的 mock、不過度設計測試 fixture

強制停止點：Tracer Bullet 完成後（第一個 test 紅→綠），停止並確認「路徑可通了，要繼續增量循環嗎？」等用戶確認才繼續。

---

步驟 3：增量循環

每次一個 test，只寫讓當前 test 過的最少代碼，不預期未來的 test。

模型路由

• 每個 test→impl 循環：Agent model="sonnet"
• 跑測試：直接 Bash（零 token）

  composer test -- --filter <TestName>
  

• 循環結束後的進度回報：主對話（Opus） 簡要告知用戶

熵減審核（每個循環後執行）

• 熵減：每個 test→impl 循環後，代碼有沒有變得更簡單？
• 三問：測試讓工程師更容易理解行為嗎？
• 量化：
  • 每個測試只測一個行為
  • 測試名稱用英文描述 WHAT 不 HOW
  • 實作行數 ≤ 測試驗證的最小需求
• 有主見：不加不必要的 mock、不過度設計測試 fixture

任何熵減審核項目為 ❌，停止循環，先修正再繼續。

---

步驟 4：重構

所有 test 通過後才重構。紅燈時禁止重構。

模型路由

• 識別重構候選項：直接 Bash 呼叫 Kimi（免費）

  kimi --yolo --print "分析以下代碼的重構機會：[檔案路徑]"
  

  也可 Read refactoring.md 查候選項
• 執行重構：Agent model="sonnet"
• 跑測試確認全綠：直接 Bash（零 token）

  composer test
  

• 重構結果回報：主對話（Opus） 告知用戶

熵減審核

• 熵減：重構後行數是否比重構前少？抽象是否更清晰？
• 三問：重構後的代碼讓下一個工程師更容易讀懂嗎？
• 量化：重構後所有 test 仍通過（無退化）
• 有主見：不做「讓我感覺良好但不改善可讀性」的重構

---

品質檢查（每個循環完成後執行）

驗證軌道	標準	狀態
行為導向測試	每個 test 的名稱描述可觀察行為（如「當 X 時，應回傳 Y」），非描述實作（如「呼叫了 methodZ」）	✅/❌
公開介面約束	所有 test 只透過 public interface 操作，無直接存取私有屬性	✅/❌
紅燈先確認	每個 test 在寫實作前確實執行過紅燈（有失敗記錄）	✅/❌
最小實作	寫了讓 test 過的最少代碼，無超前預期未來需求的實作	✅/❌
重構後綠燈	重構後執行全部 test 仍通過，無退化	✅/❌

完成條件

• 每個 test 描述行為，不描述實作
• 所有 test 只用 public interface
• 重構後所有 test 仍通過
• 無推測性功能（只寫讓 test 過的代碼）
• 品質檢查五項全部通過
• 四步驟的熵減審核全部通過