開發 Book Overview App 時遇到一個核心問題：AI 的上下文有限，讓代理人自行決定工作流程的話，主線程 compact 後就會失憶，任務交接也無法保證正確。

需要一套方法讓主線程始終掌握全局，同時讓各代理人在清楚的規格下專注執行。這就是這套方法論的起點。

三大核心原則

主線程只分派、不寫程式碼。 主線程的價值在於全局視野和決策，一旦它開始親自動手，統籌能力就消失了。

任務符合 Atomic Ticket 原則：一個 Action 加一個 Target。「實作 BookEnrichmentProcessor」是好的任務；「實作資料處理」太模糊。任務夠原子，才能精確評估、精確驗收。

100% 測試通過率，沒有例外。 我們試過接受「暫時跳過」，結果累積的債務比預期高出很多倍。現在的規則是：任何檢查失敗就等於階段未完成。

Agent 角色定義

主線程（rosemary-project-manager）負責分派任務、監控進度，處理代理人回報的升級請求。禁止親自閱讀或修改程式碼，不繞過子代理人直接操作。

TDD 四個階段各有專責代理人：Phase 1 由 lavender-interface-designer 做功能設計，Phase 2 由 sage-test-architect 做測試設計，Phase 3a 由 pepper-test-implementer 制定語言無關的實作策略，Phase 3b 由 parsley-flutter-developer 執行 Flutter 程式碼，Phase 4 由 cinnamon-refactor-owl 做重構評估。

五重文件系統

文件混亂是任務失敗的隱性原因之一。代理人不知道去哪找資訊，或者基於過時文件做了錯誤假設。

每份文件只回答一個問題：CHANGELOG 回答「這個版本做了什麼？」、todolist.yaml 回答「還有哪些問題要處理？」、worklog 回答「這個版本要達成什麼目標？」、ticket 回答「這個任務怎麼執行的？」、error-patterns 回答「之前遇過類似問題嗎？」

細節下沉原則確保 worklog 只記錄大方向，具體細節都沉到 ticket 層級。

任務分派前的準備度檢查

這是從失敗中學到的最重要教訓：分派任務前，先確認代理人有足夠資訊執行。

四個面向：API 規格和設計文件是否具體到類別定義？測試規格是否存在？完成標準是否可測量？潛在風險和依賴關係是否梳理清楚？

任何一個回答為否，就先建立對應文件再分派。我們早期跳過這步驟，代理人執行到一半才發現關鍵資訊缺失，修復成本遠高於事前準備。

階段完成的強制驗證

每個開發階段完成後，必須通過五項強制檢查：

  • flutter analyze 零 error
  • 無「Target of URI doesn’t exist」，100% package 格式導入
  • 測試 100% 通過，覆蓋率不得下降
  • 無功能重複的服務實作
  • 檔案位置符合 Clean Architecture，依賴方向正確

任何一項失敗就等於階段未完成。不允許「暫時跳過」。

技術債務的責任分工

Phase 4 的 cinnamon-refactor-owl 必須在重構評估中識別所有技術債務，用標準格式記錄到工作日誌，執行 /tech-debt-capture 建立 Ticket，確認 Ticket 成功建立後才能完成 Phase 4。

這個設計解決一個常見問題：技術債務往往被口頭記錄，然後就消失了。現在強制要求轉化為可追蹤的 Ticket。

資訊流動，不是固定計畫

v0.11.0 實戰中最深刻的學習：敏捷開發是持續發現、快速調整的動態過程。

Phase 2 測試設計讓我們提前識別了 80% 的實作問題。sage-test-architect 在設計測試時發現 BookEnrichmentData 放在錯誤的架構層，同時發現 Domain 服務層完全缺失，需要 28 個 TDD 新建測試。

這個發現改變了整個計畫，原估 4-6 天調整為 6-7 天。我們面對兩個選擇：維持原時程但降低測試覆蓋率，或延長時程確保品質。

選了後者，理由是 Domain 層是核心基礎不能妥協。最終結果：71 個測試 100% 通過，時程只多了 1 天。

這個案例確立了一個原則：Phase 間的資訊必須雙向流動。Phase 2 發現的問題不只影響 Phase 3，也必須回饋給 Phase 1 更新設計文件。「Phase 1 完成就凍結」是錯誤模式，每個 Phase 的產出都是基礎版本，隨著後續發現持續更新。

架構衝突的零容忍

發現 BookEnrichmentData 位置錯誤後，主線程立即停止 Phase 3 啟動，指派緊急遷移任務：移動檔案、更新所有 import 引用、執行測試確認無錯誤、提交變更。實際花了 0.4 小時完成。

如果在 Phase 3 已基於錯誤架構實作多個任務後才修正，修復成本至少高出十倍。

動態文件更新的觸發點

三種情況必須立即觸發文件更新：

架構變更時——類別位置調整、介面簽名變更，必須同步更新所有引用該類別的任務和設計文件。

測試設計發現時——識別新測試用例、發現缺失的邊界條件，更新對應實作任務的驗收標準。

實作階段發現時——技術方案調整、新增輔助類別，更新後續相關任務的參考實作。

核心洞察

AI 協作開發的核心挑戰是：如何讓多個 AI 代理人在有限的上下文中，基於共享的知識庫，做出一致且高品質的決策。

五重文件系統、Atomic Ticket、準備度檢查、強制驗證閘門——這些都是為了解決「資訊在 AI 協作中如何可靠流動」這個根本問題。

這套方法論仍在持續演進。每個版本都帶來新的學習，新的 error-pattern，新的流程調整。