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。

Phase 之間的資訊要雙向流動

測試設計階段（Phase 2）會發現實作階段才會踩到的問題——某個資料類別放在錯誤的架構層、某一層的服務根本還不存在。這類發現改變的不只是 Phase 3 的工作量，它同時說明 Phase 1 的設計文件寫錯了。

發現當下的選擇是兩個：維持原時程、降低測試覆蓋率，或是延長時程、把架構補正。判準取決於發現落在哪一層——Domain 層是其他層的依賴方向終點，它的錯誤會被上面每一層繼承，所以補正的優先序高於時程。

由此確立的原則是 Phase 間資訊雙向流動：Phase 2 發現的問題要回饋給 Phase 1 更新設計文件。「Phase 1 完成就凍結」在這個結構下是錯的——每個 Phase 的產出都是基礎版本，隨後續發現持續更新。

架構衝突當下就停

發現某個類別的架構層位置錯誤時，處理順序是主線程立即停止 Phase 3 啟動、指派遷移任務：移動檔案、更新所有 import 引用、執行測試確認無錯誤、提交變更。

停下來的理由是成本結構：這時要改的是一個檔案與它的引用；等 Phase 3 已經基於錯誤架構完成多個任務之後，要改的是那些任務的全部產出。

動態文件更新的觸發點

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

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

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

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

五重文件系統、Atomic Ticket、準備度檢查、強制驗證閘門，四者處理的是同一個問題：資訊要怎麼在上下文有限的多代理人協作中可靠流動。 每一項各自堵住一個流失點——找不到資訊、任務描述不足以執行、分派時規格未就緒、階段完成的判定標準浮動。

任務的原子性判準，走 Atomic Ticket 方法論；Ticket 設計決策該在哪個階段做，走 Ticket 設計決策集中在 Phase 3a。