文件規範 on Tarragonhttps://tarrragon.github.io/blog/tags/%E6%96%87%E4%BB%B6%E8%A6%8F%E7%AF%84/Recent content in 文件規範 on TarragonHugo -- gohugo.iozh-TWTarragon (CC BY 4.0)Wed, 04 Mar 2026 00:00:00 +0000方法論文件撰寫方法論https://tarrragon.github.io/blog/record/%E6%96%B9%E6%B3%95%E8%AB%96%E6%96%87%E4%BB%B6%E6%92%B0%E5%AF%AB%E6%96%B9%E6%B3%95%E8%AB%96/Wed, 04 Mar 2026 00:00:00 +0000https://tarrragon.github.io/blog/record/%E6%96%B9%E6%B3%95%E8%AB%96%E6%96%87%E4%BB%B6%E6%92%B0%E5%AF%AB%E6%96%B9%E6%B3%95%E8%AB%96/<h2 id="一個根本性的誤解">一個根本性的誤解</h2> <p>我們花了很長時間，把方法論文件寫得越來越完整——完整的定義、詳細的範例、細緻的流程說明，直到有一天發現，這樣的文件根本沒有人在用。</p> <p>問題出在誤解了方法論的讀者是誰。</p>一個根本性的誤解

我們花了很長時間，把方法論文件寫得越來越完整——完整的定義、詳細的範例、細緻的流程說明，直到有一天發現，這樣的文件根本沒有人在用。

問題出在誤解了方法論的讀者是誰。

方法論的讀者是專家。他們已經知道這些內容，只是需要時忘記了細節。他們不需要被教導，只需要一個快速的提醒，幫他們找回記憶。

30 秒電梯理論

我們現在用一個簡單標準評估方法論：能在 30 秒內讀完嗎？如果不能，就太長了。

讀者打開方法論通常是在任務中途，需要確認某個原則或步驟。超出 30 秒的內容搬移到獨立的 SKILL 文件，由方法論引用。

方法論與 SKILL 的分工

方法論是複習清單：告訴你「有哪些原則」「判斷方向是什麼」，讓你快速確認沒有遺漏重要考量。

SKILL 是實作指南：包含範例、錯誤處理、邊界情況，回答「具體怎麼做」。

過去把兩者混在一起，結果兩頭不討好——方法論太長難以快速查閱，又因試圖簡潔而省略了真正需要的操作細節。

撰寫方法論的核查

每次撰寫或改寫方法論，問三個問題：

有完整的操作流程嗎？建立對應 SKILL，方法論只保留原則和引用。

有程式碼範例或錯誤處理細節嗎？屬於 SKILL，不屬於方法論。

精簡後會流失關鍵資訊嗎？如果是，那些資訊本來就不屬於方法論。

消除歧義仍然是核心要求

精簡不代表模糊。「應該」改為「必須」，「建議」改為「要求」，「適當時機」改為具體時間點。每個判斷只有兩種結果：接受或拒絕、必須或禁止。

簡短但模糊的方法論比詳細但模糊的更糟糕——它讓讀者覺得已經複習完了，卻什麼都沒想清楚。

]]>敏捷開發方法論https://tarrragon.github.io/blog/record/%E6%95%8F%E6%8D%B7%E9%96%8B%E7%99%BC%E6%96%B9%E6%B3%95%E8%AB%96/Wed, 08 Oct 2025 00:00:00 +0000https://tarrragon.github.io/blog/record/%E6%95%8F%E6%8D%B7%E9%96%8B%E7%99%BC%E6%96%B9%E6%B3%95%E8%AB%96/<h2 id="方法論概述">方法論概述</h2> <p>本方法論定義敏捷開發流程，採用主線程統籌分派、子代理人專責執行的協作模式，確保重構品質和進度控制。 但是在AI開發過程中，不會百分之百按照文件要求執行，所以需要配合hook機制在轉階段的時候檢查是否符合TDD流程，每一層的文件是否有確實填寫，指派任務給代理人之前，文件是否有提供完整的規格資料以及功能描述，不然執行上還是會有偏差，但是依照這套機制可以及早發現出錯的狀況及早糾正</p> <p>這篇方法論是延續之前敏捷重構方法論補充內容，但是因為內容更大更完整，所以獨立一篇文章而不是更新舊的敏捷重構方法論(實際專案中是取代舊的方法論)。</p> <h2 id="核心原則">核心原則</h2> <h3 id="1-主線程職責專一化">1. 主線程職責專一化</h3> <ul> <li><strong>只負責任務分派和統籌管理</strong>，絕不親自執行具體重構工作</li> <li>依照工作日誌規劃分派任務給相應的子代理人</li> <li>維持敏捷開發的節奏和品質標準</li> </ul> <h3 id="2-任務原子化拆分">2. 任務原子化拆分</h3> <ul> <li>每個小版本任務必須在 1-2 小時內完成</li> <li>任務影響檔案數量控制在 5 個以下</li> <li>每個任務都有明確的完成標準和驗收條件</li> </ul> <h3 id="3-品質門檻強制執行">3. 品質門檻強制執行</h3> <ul> <li>每個任務完成後必須通過測試檢查</li> <li>重構代理人強制驗證程式碼品質</li> <li>100% 測試通過率是最低要求</li> </ul> <h2 id="agent-角色定義">Agent 角色定義</h2> <h3 id="主線程-main-thread">主線程 (Main Thread)</h3> <p><strong>職責</strong>：</p> <ul> <li>依照主版本工作日誌分派任務</li> <li>維持敏捷開發節奏</li> <li>監控整體進度和品質</li> <li>處理升級請求和任務重新分派</li> </ul> <p><strong>禁止行為</strong>：</p> <ul> <li>親自閱讀或修改程式碼</li> <li>執行具體的重構工作</li> <li>繞過子代理人直接操作</li> </ul> <h3 id="子代理人-sub-agents">子代理人 (Sub-Agents)</h3> <p><strong>職責</strong>：</p> <ul> <li>執行指派的具體重構任務</li> <li>回報任務完成狀態和結果</li> <li>發現任務規模過大時向上回報</li> <li>確保任務符合完成標準</li> </ul> <p><strong>專業分工</strong>：</p> <ul> <li><strong>lavender-interface-designer</strong>: TDD Phase 1 功能設計</li> <li><strong>sage-test-architect</strong>: TDD Phase 2 測試設計</li> <li><strong>pepper-test-implementer</strong>: TDD Phase 3 實作規劃</li> <li><strong>cinnamon-refactor-owl</strong>: TDD Phase 4 重構執行</li> <li><strong>mint-format-specialist</strong>: 程式碼格式化和品質修正</li> </ul> <h3 id="重構代理人-refactor-validator">重構代理人 (Refactor Validator)</h3> <p><strong>職責</strong>：</p> <ul> <li>檢查子代理人完成的重構工作</li> <li>驗證程式碼品質和功能正確性</li> <li>確認測試通過率和效能標準</li> <li>批准任務完成或要求修正</li> </ul> <p><strong>代理人</strong>: <code>cinnamon-refactor-owl</code></p> <h3 id="pm-代理人-project-manager">PM 代理人 (Project Manager)</h3> <p><strong>職責</strong>：</p> <ul> <li>任務規模過大時進行二次拆分</li> <li>更新小版本工作日誌</li> <li>重新規劃任務執行順序</li> <li>管理任務依賴關係</li> </ul> <p><strong>代理人</strong>: <code>rosemary-project-manager</code></p> <h3 id="文件代理人-documentation-agent">文件代理人 (Documentation Agent)</h3> <p><strong>職責</strong>：</p> <ul> <li>更新小版本工作日誌</li> <li>標記小版本完成狀態</li> <li>記錄任務執行結果</li> <li>同步文件狀態</li> </ul> <p><strong>代理人</strong>: <code>memory-network-builder</code></p> <h2 id="任務分派前強制檢查清單">任務分派前強制檢查清單</h2> <p><strong>重要</strong>: 在分派任何重構任務前，主線程必須先通過以下檢查清單。如果無法回答這些問題，必須優先建立準備文件。</p> <h3 id="準備度檢查問題">準備度檢查問題</h3> <h4 id="1-明確的文件規劃">1. 明確的文件規劃</h4> <ul> <li><input disabled="" type="checkbox"> <strong>API 規格是否完整？</strong> 代理人知道要實作什麼樣的介面和行為嗎？</li> <li><input disabled="" type="checkbox"> <strong>設計文件是否具體？</strong> 有詳細的類別定義、方法簽名、使用範例嗎？</li> <li><input disabled="" type="checkbox"> <strong>架構圖是否清晰？</strong> 代理人知道新系統的整體架構和元件關係嗎？</li> </ul> <h4 id="2-測試先行策略">2. 測試先行策略</h4> <ul> <li><input disabled="" type="checkbox"> <strong>測試規格是否存在？</strong> 每個元件都有對應的測試規格和驗收標準嗎？</li> <li><input disabled="" type="checkbox"> <strong>TDD 流程是否明確？</strong> 代理人知道要先寫什麼測試再實作嗎？</li> <li><input disabled="" type="checkbox"> <strong>效能標準是否定義？</strong> 有明確的效能基準和測試方法嗎？</li> </ul> <h4 id="3-實作目標明確性">3. 實作目標明確性</h4> <ul> <li><input disabled="" type="checkbox"> <strong>完成標準是否可測量？</strong> 代理人知道什麼程度才算任務完成嗎？</li> <li><input disabled="" type="checkbox"> <strong>使用範例是否充足？</strong> 有具體的程式碼範例展示最終產品嗎？</li> <li><input disabled="" type="checkbox"> <strong>移轉策略是否清楚？</strong> 有舊系統到新系統的具體移轉指引嗎？</li> </ul> <h4 id="4-風險評估與應對">4. 風險評估與應對</h4> <ul> <li><input disabled="" type="checkbox"> <strong>潛在問題是否識別？</strong> 有預見可能的技術難點和解決方案嗎？</li> <li><input disabled="" type="checkbox"> <strong>回滾計畫是否準備？</strong> 出問題時有明確的回滾和修復策略嗎？</li> <li><input disabled="" type="checkbox"> <strong>依賴關係是否梳理？</strong> 知道任務間的依賴順序和影響範圍嗎？</li> </ul> <h4 id="5-參考文件和影響範圍完整性強制">5. 參考文件和影響範圍完整性（強制）</h4> <ul> <li><input disabled="" type="checkbox"> <strong>UseCase 參考是否明確？</strong> 工作日誌是否列出對應的 UseCase 和業務需求？</li> <li><input disabled="" type="checkbox"> <strong>流程圖 Event 是否具體？</strong> 是否指定要實作流程圖的哪些 Event 編號和對應類別/方法？</li> <li><input disabled="" type="checkbox"> <strong>架構規範是否引用？</strong> 是否明確列出適用的架構規範文件（Clean Architecture、DDD、錯誤處理等）？</li> <li><input disabled="" type="checkbox"> <strong>依賴類別是否列舉？</strong> 是否列出前置任務產出的依賴類別和版本號？</li> <li><input disabled="" type="checkbox"> <strong>測試設計是否參考？</strong> 是否明確測試檔案、測試數量和效能基準？</li> <li><input disabled="" type="checkbox"> <strong>影響檔案是否清單化？</strong> 是否完整列出需建立、修改、影響的檔案清單？</li> <li><input disabled="" type="checkbox"> <strong>影響範圍是否評估？</strong> 是否評估對上層模組和下層模組的影響？</li> </ul> <p><strong>違規處理</strong>: 缺少任何一項參考文件或影響範圍資訊，視為<strong>任務規劃不合格</strong>，必須立即補充後才能分派給代理人執行。</p> <h4 id="6-設計面效能考量前後端通用">6. 設計面效能考量（前後端通用）</h4> <ul> <li><input disabled="" type="checkbox"> <strong>效能瓶頸是否識別？</strong> 是否分析潛在的效能瓶頸（大量資料處理、複雜運算、API 等待、資料庫查詢）？</li> <li><input disabled="" type="checkbox"> <strong>優化策略是否規劃？</strong> 是否規劃對應的優化策略（異步處理、Isolate、快取機制、分頁載入、索引優化）？</li> <li><input disabled="" type="checkbox"> <strong>資源使用是否評估？</strong> 是否評估記憶體使用、網路請求數量、CPU 負載、儲存空間需求？</li> <li><input disabled="" type="checkbox"> <strong>UI 阻塞是否避免？</strong> (前端) 是否確保 UI 主執行緒不被阻塞（異步操作、Loading State、compute/Isolate）？</li> <li><input disabled="" type="checkbox"> <strong>回應時間是否設計？</strong> (後端) 是否設計 API 回應時間目標和逾時處理機制？</li> <li><input disabled="" type="checkbox"> <strong>效能基準是否設定？</strong> 是否定義具體的效能目標和測量方式（載入時間、渲染幀率、API 回應時間）？</li> </ul> <p><strong>適用範圍</strong>:</p>方法論概述

本方法論定義敏捷開發流程，採用主線程統籌分派、子代理人專責執行的協作模式，確保重構品質和進度控制。 但是在AI開發過程中，不會百分之百按照文件要求執行，所以需要配合hook機制在轉階段的時候檢查是否符合TDD流程，每一層的文件是否有確實填寫，指派任務給代理人之前，文件是否有提供完整的規格資料以及功能描述，不然執行上還是會有偏差，但是依照這套機制可以及早發現出錯的狀況及早糾正

這篇方法論是延續之前敏捷重構方法論補充內容，但是因為內容更大更完整，所以獨立一篇文章而不是更新舊的敏捷重構方法論(實際專案中是取代舊的方法論)。

核心原則

1. 主線程職責專一化

  • 只負責任務分派和統籌管理，絕不親自執行具體重構工作
  • 依照工作日誌規劃分派任務給相應的子代理人
  • 維持敏捷開發的節奏和品質標準

2. 任務原子化拆分

  • 每個小版本任務必須在 1-2 小時內完成
  • 任務影響檔案數量控制在 5 個以下
  • 每個任務都有明確的完成標準和驗收條件

3. 品質門檻強制執行

  • 每個任務完成後必須通過測試檢查
  • 重構代理人強制驗證程式碼品質
  • 100% 測試通過率是最低要求

Agent 角色定義

主線程 (Main Thread)

職責：

  • 依照主版本工作日誌分派任務
  • 維持敏捷開發節奏
  • 監控整體進度和品質
  • 處理升級請求和任務重新分派

禁止行為：

  • 親自閱讀或修改程式碼
  • 執行具體的重構工作
  • 繞過子代理人直接操作

子代理人 (Sub-Agents)

職責：

  • 執行指派的具體重構任務
  • 回報任務完成狀態和結果
  • 發現任務規模過大時向上回報
  • 確保任務符合完成標準

專業分工：

  • lavender-interface-designer: TDD Phase 1 功能設計
  • sage-test-architect: TDD Phase 2 測試設計
  • pepper-test-implementer: TDD Phase 3 實作規劃
  • cinnamon-refactor-owl: TDD Phase 4 重構執行
  • mint-format-specialist: 程式碼格式化和品質修正

重構代理人 (Refactor Validator)

職責：

  • 檢查子代理人完成的重構工作
  • 驗證程式碼品質和功能正確性
  • 確認測試通過率和效能標準
  • 批准任務完成或要求修正

代理人: cinnamon-refactor-owl

PM 代理人 (Project Manager)

職責：

  • 任務規模過大時進行二次拆分
  • 更新小版本工作日誌
  • 重新規劃任務執行順序
  • 管理任務依賴關係

代理人: rosemary-project-manager

文件代理人 (Documentation Agent)

職責：

  • 更新小版本工作日誌
  • 標記小版本完成狀態
  • 記錄任務執行結果
  • 同步文件狀態

代理人: memory-network-builder

任務分派前強制檢查清單

重要: 在分派任何重構任務前，主線程必須先通過以下檢查清單。如果無法回答這些問題，必須優先建立準備文件。

準備度檢查問題

1. 明確的文件規劃

  • API 規格是否完整？ 代理人知道要實作什麼樣的介面和行為嗎？
  • 設計文件是否具體？ 有詳細的類別定義、方法簽名、使用範例嗎？
  • 架構圖是否清晰？ 代理人知道新系統的整體架構和元件關係嗎？

2. 測試先行策略

  • 測試規格是否存在？ 每個元件都有對應的測試規格和驗收標準嗎？
  • TDD 流程是否明確？ 代理人知道要先寫什麼測試再實作嗎？
  • 效能標準是否定義？ 有明確的效能基準和測試方法嗎？

3. 實作目標明確性

  • 完成標準是否可測量？ 代理人知道什麼程度才算任務完成嗎？
  • 使用範例是否充足？ 有具體的程式碼範例展示最終產品嗎？
  • 移轉策略是否清楚？ 有舊系統到新系統的具體移轉指引嗎？

4. 風險評估與應對

  • 潛在問題是否識別？ 有預見可能的技術難點和解決方案嗎？
  • 回滾計畫是否準備？ 出問題時有明確的回滾和修復策略嗎？
  • 依賴關係是否梳理？ 知道任務間的依賴順序和影響範圍嗎？

5. 參考文件和影響範圍完整性（強制）

  • UseCase 參考是否明確？ 工作日誌是否列出對應的 UseCase 和業務需求？
  • 流程圖 Event 是否具體？ 是否指定要實作流程圖的哪些 Event 編號和對應類別/方法？
  • 架構規範是否引用？ 是否明確列出適用的架構規範文件（Clean Architecture、DDD、錯誤處理等）？
  • 依賴類別是否列舉？ 是否列出前置任務產出的依賴類別和版本號？
  • 測試設計是否參考？ 是否明確測試檔案、測試數量和效能基準？
  • 影響檔案是否清單化？ 是否完整列出需建立、修改、影響的檔案清單？
  • 影響範圍是否評估？ 是否評估對上層模組和下層模組的影響？

違規處理: 缺少任何一項參考文件或影響範圍資訊，視為任務規劃不合格，必須立即補充後才能分派給代理人執行。

6. 設計面效能考量（前後端通用）

  • 效能瓶頸是否識別？ 是否分析潛在的效能瓶頸（大量資料處理、複雜運算、API 等待、資料庫查詢）？
  • 優化策略是否規劃？ 是否規劃對應的優化策略（異步處理、Isolate、快取機制、分頁載入、索引優化）？
  • 資源使用是否評估？ 是否評估記憶體使用、網路請求數量、CPU 負載、儲存空間需求？
  • UI 阻塞是否避免？ (前端) 是否確保 UI 主執行緒不被阻塞（異步操作、Loading State、compute/Isolate）？
  • 回應時間是否設計？ (後端) 是否設計 API 回應時間目標和逾時處理機制？
  • 效能基準是否設定？ 是否定義具體的效能目標和測量方式（載入時間、渲染幀率、API 回應時間）？

適用範圍:

  • 前端開發（UI 渲染、資料處理、狀態管理）
  • Backend API 開發（查詢優化、快取策略、並發處理）
  • 資料處理邏輯（JSON 解析、大量計算、批次處理）
  • 所有可能影響使用者體驗的功能

強制要求:

  • Phase 1 設計規格必須包含「效能考量」章節
  • 所有任務分派都需要評估效能影響
  • 無論前後端開發，都要從設計面預防效能問題
  • 效能問題在設計階段解決，而非依賴測試發現

參考文件:

  • TDD 協作流程 - Phase 4-1 UI 效能檢查
  • 測試金字塔設計 - 效能測試策略
  • Widget 測試指導原則 - 禁止效能測試

違規處理: 缺少效能考量分析，視為設計規劃不完整，必須補充效能分析後才能分派任務。

準備度檢查失敗處理

如果任何檢查項目回答為「否」，必須執行以下優先動作：

優先動作1: 建立 API 規格文件

1檔案: docs/[feature-name]-api-specification.md
2內容:
3- 完整的介面定義
4- 詳細的方法簽名
5- 具體的使用範例
6- 效能要求規格

優先動作2: 建立 TDD 測試規格

1檔案: docs/[feature-name]-test-specification.md
2內容:
3- 每個元件的測試案例
4- 驗收測試標準
5- 效能基準測試
6- 整合測試場景

優先動作3: 建立移轉指引

1檔案: docs/[feature-name]-migration-guide.md
2內容:
3- 舊系統→新系統對照表
4- 常見使用場景範例
5- 最佳實踐指引
6- 問題排除手冊

優先動作4: 建立實作範例

1檔案: docs/[feature-name]-implementation-examples.md
2內容:
3- 完整的程式碼範例
4- 使用情境示範
5- 常見模式展示
6- 最佳實踐指引

準備文件建立流程

文件建立責任分工

  • API 規格: lavender-interface-designer (功能設計專家)
  • 測試規格: sage-test-architect (測試設計專家)
  • 移轉指引: memory-network-builder (文件專家)
  • 實作範例: pepper-test-implementer (實作規劃專家)

文件品質標準

  • 完整性: 涵蓋所有必要資訊，無遺漏
  • 具體性: 提供可執行的詳細指引，非概念性描述
  • 一致性: 與整體架構和設計原則保持一致
  • 可測試性: 所有規格都可以通過測試驗證

三重文件原則 (Triple Document Principle)

本方法論採用三重文件機制確保不同層級的資訊流動和代理人協調。

文件層級定義

1. CHANGELOG.md - 版本功能變動記錄

職責：

  • 面向用戶的版本功能描述
  • 只記錄「做了什麼」，不記錄「怎麼做」
  • 版本發布時的正式變更說明
  • 符合 Keep a Changelog 規範

格式範例：

 1## v0.11.0 (2025-09-30)
 2
 3### 新增功能
 4- 統一書籍資訊查詢服務
 5- 支援 Google Books API 整合
 6
 7### 改善
 8- 優化錯誤處理機制
 9- 提升查詢效能
10
11### 修復
12- 修正 ISBN 驗證問題

更新時機：

  • 版本發布時由文件代理人更新
  • 從 work-log 提取用戶可感知的功能變動
  • 不記錄內部重構或技術細節

2. todolist.md - 開發任務全景圖

職責：

  • 記錄整個開發過程所有待處理任務
  • 任務狀態追蹤（待執行/進行中/已完成）
  • 優先級排序和依賴關係管理
  • 跨版本的任務規劃視圖

代理人使用場景：

  • PM 代理人：規劃任務優先序和依賴關係
  • 主線程：查看全局並分派下一個任務
  • 執行代理人：了解任務背景和依賴
  • 所有代理人：查看整體進度和下一步方向

內容結構：

 1# TodoList
 2
 3## v0.11.x 系列任務
 4- [x] v0.11.0 統一書籍資訊查詢服務
 5  - [x] Phase 1: 流程設計
 6  - [x] Phase 2: 測試設計
 7  - [ ] Phase 3: 實作執行
 8    - [x] v0.11.3 Domain 輸入驗證
 9    - [x] v0.11.4 核心查詢服務
10    - [ ] v0.11.5 資料處理和快取
11- [ ] v0.11.15 測試修復完成
12
13## v0.12.x 系列任務（規劃中）
14- [ ] v0.12.0 外部 API 整合

更新責任：

  • 所有代理人在任務狀態變更時即時更新
  • PM 代理人負責新增和重組任務
  • 主線程負責維護任務優先序

3. work-log/ - 詳細實作記錄

職責：

  • 完整的技術實作細節和決策過程
  • TDD 四階段進度追蹤
  • 代理人交接的完整上下文
  • 問題發現和解決方案記錄

文件結構：

  • 主版本日誌 (vX.Y.0-main.md)：中版本總覽、任務分派清單
  • 小版本日誌 (vX.Y.Z-task.md)：具體任務的詳細執行記錄

內容標準：

 1# vX.Y.Z 任務名稱
 2
 3## 任務資訊
 4- 版本號、負責代理人、執行日期
 5- 前置任務、後續任務
 6
 7## 任務目標
 8- 明確的技術目標
 9
10## 參考文件
11- UseCase、流程圖、架構規範
12- 依賴類別、測試設計
13
14## 執行過程
15- Phase 1: 設計
16- Phase 2: 測試
17- Phase 3: 實作
18- Phase 4: 重構
19
20## 完成標準
21- 測試通過率 100%
22- 程式碼品質符合標準

更新責任：

  • 執行代理人負責記錄詳細過程
  • 文件代理人負責標記完成狀態
  • PM 代理人負責維護主版本日誌

三重文件協調機制

資訊流動方向

graph TD
    A[work-log<br/>實作細節] -->|提取功能變動| B[CHANGELOG<br/>版本說明]
    A -->|完成任務| C[todolist<br/>狀態更新]
    C -->|規劃下一步| D[主線程分派]
    D -->|查看詳細| A
    B -->|版本發布| E[用戶和團隊]

    style A fill:#e1f5ff
    style B fill:#fff4e1
    style C fill:#e8f5e9

流程說明：

  1. 代理人在 work-log 記錄詳細實作過程
  2. 任務完成時更新 todolist 狀態
  3. 版本發布時從 work-log 提取變動到 CHANGELOG
  4. 主線程基於 todolist 和 work-log 規劃下一步

代理人交接層級

主線程 ↔ PM 代理人

主要參考：

  • todolist.md - 任務全局和優先序
  • vX.Y.0-main.md - 版本進度和任務拆分

交接場景：

  • 任務規模過大需要拆分
  • 規劃下一個版本系列
  • 任務依賴關係調整
主線程 ↔ 執行代理人

主要參考：

  • vX.Y.Z-task.md - 具體任務詳細說明
  • todolist.md - 任務依賴和背景

交接場景：

  • 分派新任務
  • 接收完成回報
  • 處理問題升級
執行代理人 ↔ 執行代理人

主要參考：

  • vX.Y.Z-task.md - 前置任務的產出和發現
  • vX.Y.0-main.md - 重要決策和架構調整

交接場景：

  • Phase 1 → Phase 2：設計交接測試
  • Phase 2 → Phase 3：測試交接實作
  • Phase 3 → Phase 4：實作交接重構
  • 依賴任務間的產出交接
版本發布時

主要參考：

  • work-log/ - 提取所有功能變動
  • todolist.md - 確認完成項目

執行流程：

  1. 文件代理人檢視所有已完成的 work-log
  2. 提取用戶可感知的功能變動
  3. 更新 CHANGELOG.md
  4. 確認 todolist.md 狀態一致

三重文件更新責任

文件 更新時機 責任代理人 更新內容 更新頻率
work-log 任務執行中/完成 執行代理人 詳細實作過程、決策記錄 即時
todolist 任務狀態變更 所有代理人 任務狀態、優先序 即時
CHANGELOG 版本發布 文件代理人 功能變動摘要 版本發布時

三重文件一致性檢查

強制檢查項目

版本號一致性：

  • CHANGELOG 版本號 = work-log 主版本號
  • todolist 版本系列 = work-log 版本系列

任務狀態一致性：

  • todolist 標記完成 ⇒ work-log 必須有對應完成記錄
  • work-log 標記完成 ⇒ todolist 必須同步更新

功能描述一致性：

  • CHANGELOG 功能描述 ⇒ 必須對應 work-log 實作內容
  • 不可在 CHANGELOG 記錄未實作的功能

Hook 系統整合

Version Check Hook：

  • 檢查三重文件版本號一致性
  • 建議版本推進策略

Document Sync Hook：

  • 提醒 work-log 完成時更新 todolist
  • 提醒版本發布時更新 CHANGELOG

Work Log Check Hook：

  • 識別工作狀態（更新/新建/完成）
  • 確保 work-log 記錄完整性

強制要求

文件完整性要求

  1. work-log 必須完整：

    • 所有技術細節必須記錄
    • 所有決策必須說明理由
    • 所有問題發現必須記錄

  2. todolist 必須即時：

    • 任務狀態即時更新，不得延遲
    • 新任務必須立即加入
    • 完成任務必須立即標記

  3. CHANGELOG 必須準確：

    • 只記錄用戶可感知的變動
    • 不記錄內部重構或技術債務
    • 必須基於實際完成的 work-log

代理人責任要求

  1. 執行代理人：

    • 任務執行過程必須記錄到 work-log
    • 任務完成時必須更新 todolist 狀態
    • 發現問題必須記錄到 work-log

  2. 文件代理人：

    • 版本發布時必須更新 CHANGELOG
    • 確保三重文件一致性
    • 標記 work-log 完成狀態

  3. PM 代理人：

    • 維護 todolist 任務結構
    • 維護 vX.Y.0-main.md 任務分派
    • 確保任務依賴關係正確

  4. 主線程：

    • 不得親自修改程式碼
    • 基於 todolist 和 work-log 分派任務
    • 監控三重文件一致性

v0.11.0 實戰範例

三重文件協調實例

work-log 記錄（v0.11.3-domain-input-validation.md）：

1## Phase 3 實作完成
2- BookQueryInput Value Object 實作
3- InputValidator 驗證邏輯
4- 71 個測試 100% 通過

todolist 更新：

1- [x] v0.11.3 Domain 輸入驗證

CHANGELOG 提取（版本發布時）：

1## v0.11.0 (2025-09-30)
2### 新增功能
3- 統一書籍資訊查詢服務（支援 ISBN、標題、作者查詢）

協調流程：

  1. pepper-test-implementer 完成 v0.11.3 實作
  2. 記錄詳細過程到 work-log
  3. 更新 todolist 標記完成
  4. 主線程分派下一個任務 v0.11.4
  5. 版本發布時，文件代理人從所有 v0.11.x work-log 提取功能到 CHANGELOG

代理人交接實例

Phase 2 → Phase 3 交接：

sage-test-architect 完成測試設計後：

 1# v0.11.2-tdd-phase2-test-design.md
 2
 3## Phase 2 產出
 4- 335 個測試用例設計
 5- 33 個測試檔案規劃
 6- 架構修正決策：BookEnrichmentData 遷移到 Domain 層
 7
 8## 傳遞給 Phase 3
 9- 依賴類別：BookEnrichmentData (已遷移)
10- 測試優先序：v0.11.3 → v0.11.4 → v0.11.5
11- 重要發現：Domain 服務層需從零建立

pepper-test-implementer 接收後：

1# v0.11.3-domain-input-validation.md
2
3## 參考文件
4- 測試設計：v0.11.2-tdd-phase2-test-design.md#task-20
5- 前置任務產出：無（首個任務）
6- 架構調整：BookEnrichmentData 已遷移到 Domain 層
7
8## Phase 3 執行
9基於 Phase 2 測試設計，實作 BookQueryInput...

交接重點：

  • Phase 2 的架構發現立即傳遞
  • Phase 3 明確參考 Phase 2 測試設計
  • work-log 完整記錄交接脈絡

敏捷重構流程

增強版執行循環

graph TD
    A[主線程開始任務分派] --> B[執行準備度檢查清單]
    B --> C{檢查是否全部通過?}
    C -->|否| D[呼叫相應代理人建立準備文件]
    D --> E[文件建立完成]
    E --> B
    C -->|是| F[檢查主版本工作日誌]
    F --> G[分派下一個任務]
    G --> H[子代理人執行任務]
    H --> I{任務規模是否適當?}
    I -->|過大| J[向上回報主線程]
    J --> K[PM代理人拆分任務]
    K --> L[建立小版本工作日誌]
    L --> M[依小版本日誌分派]
    M --> H
    I -->|適當| N[完成任務回報]
    N --> O[重構代理人檢查]
    O --> P{品質是否通過?}
    P -->|不通過| Q[要求修正]
    Q --> H
    P -->|通過| R[文件代理人更新日誌]
    R --> S{小版本是否完成?}
    S -->|是| T[回到主版本檢查下一任務]
    S -->|否| U[檢查小版本下一任務]
    U --> M
    T --> F

標準執行循環

graph TD
    A[主線程檢查主版本工作日誌] --> B[分派下一個任務]
    B --> C[子代理人執行任務]
    C --> D{任務規模是否適當?}
    D -->|過大| E[向上回報主線程]
    E --> F[PM代理人拆分任務]
    F --> G[建立小版本工作日誌]
    G --> H[依小版本日誌分派]
    H --> C
    D -->|適當| I[完成任務回報]
    I --> J[重構代理人檢查]
    J --> K{品質是否通過?}
    K -->|不通過| L[要求修正]
    L --> C
    K -->|通過| M[文件代理人更新日誌]
    M --> N{小版本是否完成?}
    N -->|是| O[回到主版本檢查下一任務]
    N -->|否| P[檢查小版本下一任務]
    P --> H
    O --> A

任務拆分實戰範例

v0.11.5 任務拆分情境

原始任務：v0.11.5 - 批次 1.3 資料處理和快取

任務描述（來自 v0.11.0-main.md）：

1#### v0.11.5 - 批次 1.3 資料處理和快取
2**狀態**: 待執行
3**負責**: pepper-test-implementer
4**實作內容**:
5- BookEnrichmentProcessor
6- BookMetadata 實體
7- ApiCacheManager
8
9**驗收**: 資料處理鏈測試通過

代理人回報（情境假設）

 1## 代理人回報 - v0.11.5
 2
 3**回報代理人**: pepper-test-implementer
 4**任務**: v0.11.5 - 批次 1.3 資料處理和快取
 5
 6### 問題描述
 7經過 Phase 2 測試設計分析，發現此任務包含三個獨立且複雜的元件：
 81. BookEnrichmentProcessor - 資料處理邏輯（20+ 個測試用例）
 92. BookMetadata 實體 - Domain 層核心實體（15+ 個測試用例）
103. ApiCacheManager - 快取管理機制（18+ 個測試用例）
11
12預估總工作量：4-5 小時，超過單一任務標準（1-2 小時）
13
14### 建議拆分方案
15**方案 A**：依元件職責拆分為三個子任務
16- v0.11.5-a: BookEnrichmentProcessor（資料處理核心）
17- v0.11.5-b: BookMetadata（Domain 實體）
18- v0.11.5-c: ApiCacheManager（快取機制）
19
20**方案 B**：依依賴關係拆分
21- v0.11.5-a: BookMetadata + BookEnrichmentProcessor
22- v0.11.5-b: ApiCacheManager
23
24### 推薦方案
25推薦方案 A，原因：
26- 每個元件職責單一，測試獨立
27- 符合 Clean Architecture 分層（Domain / Application）
28- 可並行開發（如有多代理人）
29- 風險隔離，單一元件問題不影響其他
30
31### 等待主線程決策
32請確認拆分方案，並指示是否需要 PM 代理人建立子版本工作日誌。

主線程決策處理

決策過程：

  1. 檢視相關文件：

    • Phase 2 測試設計：確認測試用例數量和複雜度
    • 流程圖 Event 6-7：確認元件間依賴關係
    • 架構規範：確認分層正確性

  2. 評估拆分方案：

    • 方案 A 職責更清晰，符合單一職責原則
    • 每個子任務 1.5-2 小時，符合標準
    • BookMetadata 是 Domain 層核心，應獨立處理

  3. 做出決策：

     1## 決策記錄 - v0.11.5 拆分
 2
 3**決策**: 採用方案 A，拆分為三個子任務
 4**理由**:
 5- 符合單一職責原則
 6- BookMetadata 是 Domain 層核心實體，重要性高
 7- 測試覆蓋率可逐步建立
 8- 風險管理更精確
 9
10**執行**:
111. 呼叫 rosemary-project-manager 建立子版本工作日誌
122. 更新 v0.11.0-main.md 任務清單
133. 依序分派 v0.11.5-a → v0.11.5-b → v0.11.5-c

PM 代理人建立子版本日誌

rosemary-project-manager 執行：

1. 建立 v0.11.5-a 工作日誌

 1# v0.11.5-a 資料處理核心 - BookEnrichmentProcessor
 2
 3## 任務資訊
 4- **版本號**: v0.11.5-a
 5- **父任務**: v0.11.5 批次 1.3 資料處理和快取
 6- **負責代理人**: pepper-test-implementer
 7- **執行日期**: 2025-09-30
 8- **前置任務**: v0.11.4 (核心查詢服務)
 9- **後續任務**: v0.11.5-b (BookMetadata)
10
11## 任務目標
12實作 BookEnrichmentProcessor 資料處理核心邏輯。
13
14## 參考文件（強制完整）
15
16### UseCase 參考
17- [UC-01 ISBN 精確查詢](/app-use-cases.md#uc-01)
18
19### 流程圖參考（具體到 Event）
20- [主流程 Event 6](/use-cases/unified-api/book-info-query-flow.md)
21  - Event 6: BookEnrichmentProcessor.process(rawData)
22  - 輸入: GoogleBooksDto
23  - 輸出: BookEnrichmentData
24
25### 架構規範
26- [Application 層設計](/app-requirements-spec.md#application-layer)
27- [資料轉換規範](/domain-transformation-layer-design.md)
28
29### 依賴類別（前置任務產出）
30- `BookQueryInput` (v0.11.3)
31- `QueryType` (v0.11.4)
32- `GoogleBooksDto` (Infrastructure 既有)
33
34### 測試設計參考
35- [主流程測試設計](/record/agile-programing-methodology/v0.11.2-tdd-phase2-test-design.md#task-22)
36- 測試檔案: `book_enrichment_processor_test.dart`
37- 測試用例: 20 個
38
39## 影響範圍
40- 新建: `lib/application/book_info/processors/book_enrichment_processor.dart`
41- 新建: `test/unit/application/book_info/processors/book_enrichment_processor_test.dart`
42
43## 完成標準
44- [ ] BookEnrichmentProcessor 實作完成
45- [ ] 20 個測試用例 100% 通過
46- [ ] 符合 Application 層職責
47- [ ] 錯誤處理遵循規範
48
49## 回到父任務
50完成後更新 v0.11.0-main.md 標記 v0.11.5-a 完成。

2. 建立 v0.11.5-b、v0.11.5-c 工作日誌

（類似格式，省略詳細內容）

更新主版本工作日誌

更新 v0.11.0-main.md：

 1#### v0.11.5 - 批次 1.3 資料處理和快取（待執行）
 2**狀態**: 執行中（已拆分為子任務）
 3**負責**: pepper-test-implementer
 4
 5**子任務**:
 6- [ ] v0.11.5-a: BookEnrichmentProcessor ([工作日誌](/record/agile-programing-methodology/v0.11.5-a-enrichment-processor.md))
 7- [ ] v0.11.5-b: BookMetadata ([工作日誌](/record/agile-programing-methodology/v0.11.5-b-book-metadata.md))
 8- [ ] v0.11.5-c: ApiCacheManager ([工作日誌](/record/agile-programing-methodology/v0.11.5-c-cache-manager.md))
 9
10**驗收**: 三個子任務全部完成，資料處理鏈測試通過
11
12**拆分原因**: 任務複雜度超出標準，依元件職責拆分為三個獨立任務
13**拆分決策**: [決策記錄連結]

任務拆分關鍵原則

何時拆分

  • 預估工作時間 > 3 小時
  • 影響檔案數量 > 5 個
  • 測試用例數量 > 30 個
  • 包含多個獨立職責的元件
  • 依賴關係複雜需要分階段驗證

拆分命名規則

  • 單層拆分: vX.Y.Z-a, vX.Y.Z-b, vX.Y.Z-c
  • 多層拆分: vX.Y.Z-a1, vX.Y.Z-a2（極少使用）
  • 命名語意: 清楚表達子任務核心職責

拆分後的依賴管理

  • 串行依賴: 明確標註前置任務和後續任務
  • 並行任務: 標註可同時進行的子任務
  • 共享依賴: 在父任務層級說明共同依賴

動態文件更新機制

核心原則

敏捷開發的資訊流動本質：前置階段的發現必須立即傳遞並更新後續任務描述，確保所有代理人基於最新、最完整的資訊執行任務。

Phase 發現傳遞流程

Phase 1 → Phase 2 → Phase 3 資訊流

graph LR
    A[Phase 1 設計] -->|架構決策| B[Phase 2 測試設計]
    B -->|實作指引| C[Phase 3 實作]
    B -->|問題識別| D[架構調整]
    D -->|更新設計| A
    D -->|更新任務| C

v0.11 實際案例：Phase 2 發現如何更新 Phase 3 任務

Phase 2 發現（v0.11.2）：

  1. 架構問題：BookEnrichmentData 位於 Infrastructure 層（應在 Domain 層）
  2. 命名不一致：4 個流程圖元件命名與程式碼不符
  3. 缺失元件：Domain 服務層完全缺失，需要 20 個新類別
  4. 時程調整：從 4-6 天調整為 6-7 天

立即執行的更新動作：

1. 架構修正（阻塞性問題）

決策：立即停止 Phase 3 任務，優先修正架構問題

執行：

 1## 緊急任務插入 - v0.11.2-fix
 2
 3**任務**: 遷移 BookEnrichmentData 到 Domain 層
 4**優先級**: 最高（阻塞後續開發）
 5**執行**: 主線程直接處理或指派給 mint-format-specialist
 6
 7**完成後動作**:
 8- 更新所有相關任務的依賴類別參考
 9- 更新流程圖中的層級標註
10- 通知所有相關代理人架構變更
2. 更新待執行任務的參考文件

原始 v0.11.5 任務描述（Phase 2 前）：

1#### v0.11.5 - 批次 1.3 資料處理和快取
2**實作內容**:
3- BookEnrichmentProcessor
4- BookMetadata 實體
5- ApiCacheManager
6
7**參考文件**: （缺失）

更新後 v0.11.5 任務描述（Phase 2 後）：

 1#### v0.11.5 - 批次 1.3 資料處理和快取
 2**實作內容**:
 3- BookEnrichmentProcessor
 4- BookMetadata 實體
 5- ApiCacheManager
 6
 7**參考文件**（Phase 2 補充）:
 8- [主流程 Event 6-7](/record/use-cases/unified-api/book-info-query-flow.md)
 9- [測試設計](/record/agile-programing-methodology/v0.11.2-tdd-phase2-test-design.md#task-22)
10- 依賴類別: `BookEnrichmentData` (**已遷移到 Domain 層**)
11- 依賴類別: `BookQueryInput` (v0.11.3)
12- 依賴類別: `QueryType` (v0.11.4)
13- [錯誤處理規範](/record/app-error-handling-design.md)
14
15**Phase 2 發現**:
16- BookEnrichmentData 已從 Infrastructure 遷移到 Domain
17- 需要處理資料轉換和驗證邏輯
18- 快取策略需要配合速率控制（批次 2）
19
20**驗收**: 資料處理鏈測試通過，符合 Domain 層職責
3. 更新主版本工作日誌（持續性文件）

v0.11.0-main.md 動態更新區域：

 1## Phase 2 重要發現（持續更新）
 2
 3### 架構調整
 4- **BookEnrichmentData 層級修正**（2025-09-30）
 5  - 原位置: `lib/infrastructure/`
 6  - 新位置: `lib/domains/book_info/entities/`
 7  - 影響任務: v0.11.5, v0.11.6
 8  - Git commit: 58b1603
 9
10### 命名統一
11- **流程圖命名修正**（2025-09-30）
12  - 修正 4 個元件命名不一致
13  - 所有後續任務參考已更新
14
15### 實作發現
16- **Domain 服務層新建**：v0.11.3-4 建立 BookQueryInput, QueryTypeResolver
17  - 影響: 所有後續任務依賴這些基礎類別
18  - 參考: 所有任務需 import package:book_overview_app/domains/book_info/
19
20### 時程調整
21- **原估時程**: 4-6 天
22- **調整時程**: 6-7 天（+1-2 天）
23- **原因**: 28 個 TDD 新建測試，Domain 層從零建立

動態更新觸發時機

1. 架構變更時

觸發條件：

  • 類別位置調整（跨層級遷移）
  • 介面簽名變更
  • 依賴關係變化

更新範圍：

  • 所有引用該類別的任務
  • 相關的流程圖和設計文件
  • 測試設計中的 Mock 設定

2. 測試設計發現時

觸發條件：

  • 識別出新的測試用例
  • 發現缺失的邊界條件
  • 複雜度評估變化

更新範圍：

  • 對應實作任務的驗收標準
  • 相關任務的前置條件
  • 時程估算調整

3. 實作階段發現時

觸發條件：

  • 技術方案調整
  • 新增輔助類別
  • 效能優化需求

更新範圍：

  • 後續相關任務的參考實作
  • 測試設計補充
  • 文件範例更新

動態更新執行標準

主線程職責

1## 主線程動態更新檢查清單
2
3每次任務完成後：
4- [ ] 檢查是否有架構變更
5- [ ] 檢查是否有新的依賴類別
6- [ ] 檢查是否影響後續任務
7- [ ] 更新主版本工作日誌「重要發現」區域
8- [ ] 更新所有受影響任務的參考文件
9- [ ] 通知相關代理人（如已分派）

代理人回報職責

 1## 代理人發現回報格式
 2
 3### 發現類型
 4- [ ] 架構問題
 5- [ ] 依賴變更
 6- [ ] 新增元件
 7- [ ] 技術債務
 8
 9### 影響評估
10- 影響範圍: [列出受影響的任務版本號]
11- 嚴重程度: 阻塞 / 重要 / 資訊性
12- 建議動作: [具體建議]
13
14### 需要更新的文件
15- [ ] 主版本工作日誌
16- [ ] 相關任務參考文件
17- [ ] 流程圖或設計文件

代理人回報與討論流程

回報時機與類型

1. 架構衝突檢測

觸發情境：

  • 流程圖定義與實作需求衝突
  • 類別職責與層級定位不符
  • 依賴方向違反 Clean Architecture

v0.11 實際案例：

 1## 架構衝突回報 - v0.11.2
 2
 3**回報代理人**: sage-test-architect
 4**檢測階段**: Phase 2 測試設計
 5
 6### 衝突描述
 7發現 `BookEnrichmentData` 位於 `lib/infrastructure/` 目錄，
 8但其職責為 Domain 層實體（純資料結構，無外部依賴）。
 9
10### 架構分析
11- **當前位置**: `lib/infrastructure/api/google_books/book_enrichment_data.dart`
12- **應該位置**: `lib/domains/book_info/entities/book_enrichment_data.dart`
13- **衝突原因**: 違反 Clean Architecture 分層原則
14- **影響範圍**:
15  - v0.11.5 (資料處理) 需要引用此類別
16  - v0.11.6 (API 客戶端) 需要轉換到此類別
17  - 所有測試需要更新 import 路徑
18
19### 建議方案
20**推薦**: 立即遷移到 Domain 層
21**理由**:
221. Domain 層應該定義核心資料模型
232. Infrastructure 層應該依賴 Domain，而非反向
243. 後續所有 Domain 服務都需要使用此類別
25
26### 需要決策
27- [ ] 是否同意遷移到 Domain 層
28- [ ] 是否需要重新命名（EnrichmentData → BookEnrichmentData）
29- [ ] 是否需要更新所有流程圖標註
30
31#### 等待主線程確認後執行

主線程處理流程：

  1. 檢視相關規範：

    • 閱讀 Clean Architecture 設計文件
    • 確認 Domain 層職責定義
    • 檢查是否有其他類似問題

  2. 做出決策：

     1## 決策 - BookEnrichmentData 遷移
 2
 3**決定**: 同意遷移到 Domain 層
 4**執行**:
 51. 立即處理（阻塞後續任務）
 62. 遷移到 `lib/domains/book_info/entities/`
 73. 更新所有 import 引用
 84. 更新流程圖層級標註
 9
10**指派**: mint-format-specialist 執行檔案遷移和路徑更新
11**時程**: 0.5 小時，完成後繼續 v0.11.3

  3. 更新受影響任務：

    • 更新 v0.11.5, v0.11.6 參考文件
    • 標註 BookEnrichmentData 新位置
    • 更新所有測試的 import 路徑範例

2. 任務複雜度超標

觸發情境：

  • 預估工作時間 > 3 小時
  • 測試用例數量 > 30 個
  • 影響檔案數量 > 5 個

（參考「任務拆分實戰範例」章節）

3. 流程圖與需求不一致

觸發情境：

  • Event 描述過於抽象
  • 方法簽名未定義清楚
  • 錯誤處理策略模糊

回報格式：

 1## 流程圖釐清需求 - vX.Y.Z
 2
 3**回報代理人**: [agent-name]
 4**流程圖**: [flow-diagram-name.md]
 5**Event**: Event X
 6
 7### 需要釐清的問題
 81. **Event X 描述**: [原始描述]
 9   - 疑問: [具體不清楚的地方]
10   - 需要確認: [需要確認的技術細節]
11
122. **方法簽名缺失**:
13   - 當前: Event X 只說「處理資料」
14   - 需要: 輸入參數類型、輸出返回類型、異常處理
15
16### 建議補充
17```dart
18// 建議的方法簽名
19Future<BookEnrichmentData> processRawData(
20  GoogleBooksDto rawData,
21  QueryType queryType,
22) async {
23  // 實作邏輯
24}

需要主線程確認

  • 方法簽名是否正確
  • 是否需要更新流程圖
  • 錯誤處理策略（拋出異常 vs OperationResult）
 1
 2**主線程處理**：
 31. 檢視 UseCase 定義
 42. 確認技術方案
 53. 更新流程圖或任務描述
 64. 回覆代理人並記錄決策
 7
 8#### 4. 技術方案需要確認
 9**觸發情境**：
10- 多種實作方案可行
11- 效能與可讀性取捨
12- 第三方套件選擇
13
14**回報格式**：
15```markdown
16## 技術方案確認 - vX.Y.Z
17
18**方案 A**: [描述]
19- 優點: [列舉]
20- 缺點: [列舉]
21- 適用場景: [說明]
22
23**方案 B**: [描述]
24- 優點: [列舉]
25- 缺點: [列舉]
26- 適用場景: [說明]
27
28### 推薦方案及理由
29[代理人的推薦與分析]
30
31### 等待主線程決策
32[需要確認的具體問題]

回報標準格式

完整回報模板

 1## 代理人回報 - vX.Y.Z
 2
 3**回報代理人**: [agent-name]
 4**任務**: [task-name]
 5**回報類型**: 架構衝突 / 複雜度 / 流程圖釐清 / 技術方案
 6**嚴重程度**: 阻塞 / 重要 / 資訊性
 7
 8---
 9
10### 問題描述
11[清楚描述發現的問題或疑問]
12
13### 背景資訊
14- **相關文件**: [列出相關的 UseCase、流程圖、架構文件]
15- **當前狀態**: [任務執行到什麼階段]
16- **發現時機**: [什麼時候發現這個問題]
17
18### 影響評估
19- **影響任務**: [列出受影響的任務版本號]
20- **影響範圍**: [程式碼、測試、文件]
21- **風險等級**: [高/中/低]
22
23### 分析與建議
24#### 原因分析
25[為什麼會發生這個問題]
26
27#### 建議方案
28**方案 A**: [描述]
29**方案 B**: [描述]
30**推薦**: [哪個方案及理由]
31
32### 等待主線程決策
33- [ ] [具體需要決策的問題 1]
34- [ ] [具體需要決策的問題 2]
35- [ ] [需要更新的文件清單]
36
37---
38
39**暫停執行**: 是 / 可繼續其他任務 / 不影響當前工作

主線程討論與決策流程

決策流程圖

graph TD
    A[代理人回報] --> B[主線程接收]
    B --> C{嚴重程度?}
    C -->|阻塞| D[立即處理]
    C -->|當日| E[當日處理]
    C -->|資訊性| F[記錄並規劃]

    D --> G[檢視相關文件]
    E --> G
    F --> G

    G --> H[分析影響範圍]
    H --> I{需要專家?}
    I -->|是| J[呼叫 PM 或相關代理人]
    I -->|否| K[主線程決策]

    J --> K
    K --> L[記錄決策理由]
    L --> M[更新受影響任務]
    M --> N[通知相關代理人]
    N --> O[繼續執行]

決策記錄格式

 1## 決策記錄 - [問題簡述]
 2
 3**決策日期**: YYYY-MM-DD
 4**相關回報**: [代理人回報連結]
 5**決策者**: 主線程 / PM代理人
 6
 7---
 8
 9### 問題摘要
10[簡要描述問題]
11
12### 決策內容
13**決定**: [具體決策]
14**理由**:
151. [理由 1]
162. [理由 2]
173. [理由 3]
18
19### 執行計畫
20- [ ] [動作 1]
21- [ ] [動作 2]
22- [ ] [動作 3]
23
24### 影響範圍
25- **更新任務**: [列出需要更新的任務]
26- **更新文件**: [列出需要更新的文件]
27- **通知對象**: [列出需要通知的代理人]
28
29### 追蹤記錄
30- YYYY-MM-DD: [執行狀態更新]
31- YYYY-MM-DD: [完成確認]

決策傳遞機制

1. 更新主版本工作日誌

在 vX.Y.0-main.md 新增「決策記錄」區域：

1## 重要決策記錄
2
3### [決策 1 標題]
4- **日期**: YYYY-MM-DD
5- **問題**: [簡述]
6- **決策**: [簡述]
7- **影響**: [列出受影響任務]
8- **詳細**: [連結到完整決策記錄]

2. 更新受影響任務描述

所有受影響的任務都需要補充「決策影響」區域。

3. 通知相關代理人

如果任務已分派，需要明確通知代理人決策內容。

溝通協作原則

代理人責任

  • 主動回報：發現問題立即回報，不自行假設
  • 完整資訊：提供足夠的背景資訊供決策
  • 建議方案：分析並提供具體建議
  • 等待確認：阻塞性問題必須等待主線程決策

主線程責任

  • 快速響應：阻塞問題當日處理完畢
  • 充分調研：檢視相關文件和規範
  • 清楚決策：明確說明決策理由
  • 完整傳遞：確保所有受影響方收到資訊

協作品質標準

  • 響應時間: 阻塞問題 < 2 小時，重要問題 < 1 天
  • 決策品質: 必須基於專案規範和架構原則
  • 資訊完整: 所有決策必須文件化並傳遞
  • 追蹤閉環: 決策執行完成必須確認和記錄

任務分派規則

1. 任務優先序

  1. 架構核心任務 - 影響多個模組的基礎架構變更
  2. 高風險任務 - 影響關鍵業務邏輯的重構
  3. 中風險任務 - 次要功能模組的重構
  4. 低風險任務 - 測試檔案和工具檔案的更新

2. 任務大小控制

理想任務大小：

  • 執行時間：1-2 小時
  • 影響檔案：1-5 個檔案
  • 測試影響：單一測試套件
  • 複雜度：單一職責變更

任務過大指標：

  • 影響檔案 > 5 個
  • 預估時間 > 3 小時
  • 涉及多個模組
  • 需要連環修改

3. 升級處理機制

何時觸發升級：

  • 子代理人回報任務規模過大
  • 發現任務間複雜依賴關係
  • 需要重新評估技術方案
  • 遇到無法解決的技術問題

升級處理流程：

  1. 子代理人向主線程回報問題
  2. 主線程呼叫 PM 代理人進行分析
  3. PM 代理人拆分任務並建立小版本日誌
  4. 依新的小版本日誌重新分派任務

任務執行標準

任務分派標準格式

每個任務分派必須包含：

 1## 任務 vX.Y.Z - [任務名稱]
 2
 3### 任務目標
 4- 明確的完成目標描述
 5- 具體的技術實現要求
 6
 7### 參考文件（強制完整填寫）
 8
 9#### UseCase 參考（必須）
10- [UC-XX](/record/app-use-cases.md#uc-xx) - [Use Case 名稱]
11- [UC-YY](/record/app-use-cases.md#uc-yy) - [相關 Use Case]
12
13**說明**: 明確指出此任務對應哪些 Use Case，確保實作符合業務需求。
14
15#### 流程圖參考（必須，具體到 Event）
16- [流程圖名稱 Event X-Y](/record/use-cases/[feature]/[flow-name].md)
17  - Event X: [Event 描述] - [對應的類別/方法]
18  - Event Y: [Event 描述] - [對應的類別/方法]
19
20**範例**（來自 v0.11.5）:
21- [主流程 Event 6-7](/record/use-cases/unified-api/book-info-query-flow.md)
22  - Event 6: BookEnrichmentProcessor.process(rawData) - 處理原始資料
23  - Event 7: BookMetadata.create() - 建立 Domain 實體
24
25**說明**: 具體到 Event 編號，讓代理人知道要實作流程圖的哪個部分。
26
27#### 架構規範（必須）
28- [Domain 層設計](/record/app-requirements-spec.md#domain-layer) - 層級職責定義
29- [錯誤處理規範](/record/app-error-handling-design.md) - 異常處理標準
30- [資料轉換規範](/record/domain-transformation-layer-design.md) - DTO 轉換規則
31
32**說明**: 確保實作符合專案架構原則。
33
34#### 依賴類別（前置任務產出）
35- `ClassName1` (vX.Y.Z) - [簡短說明]
36- `ClassName2` (vX.Y.Z) - [簡短說明]
37
38**範例**（來自 v0.11.5）:
39- `BookQueryInput` (v0.11.3) - 查詢輸入參數 Value Object
40- `QueryType` (v0.11.4) - 查詢類型枚舉
41- `BookEnrichmentData` (Domain 層) - **已從 Infrastructure 遷移**
42
43**說明**: 列出此任務依賴的前置任務產出，包含版本號方便追溯。
44
45#### 測試設計參考（TDD 必須）
46- [測試設計文件](/record/agile-programing-methodology/vX.Y.Z-test-design.md#section)
47- 測試檔案: `test_file_name_test.dart`
48- 測試用例數: N 個
49- 效能基準: [如有特殊要求]
50
51**說明**: TDD 開發必須先參考測試設計，瞭解驗收標準。
52
53#### 實作範例（如有）
54- [類似實作參考](/record/agile-programing-methodology/vX.Y.Z-work-log.md#implementation)
55- [程式碼範例](/record/docs/implementation-examples.md)
56
57**說明**: 提供參考範例幫助代理人理解預期實作方式。
58
59### 影響範圍
60- 需要修改的檔案清單
61- 預估影響的測試檔案
62- 影響的依賴關係
63
64### 依賴關係
65- 前置任務：[必須完成的前置任務清單]
66- 後續任務：[依賴此任務的後續任務]
67- 並行任務：[可同時進行的相關任務]
68
69### 完成標準
70- [ ] 功能實現完成
71- [ ] 測試通過率 100%
72- [ ] 程式碼品質檢查通過
73- [ ] 無新增警告或錯誤
74- [ ] 參考文件更新 (如有需要)
75
76### 風險評估
77- 技術風險等級：高/中/低
78- 潛在影響評估
79- 回滾策略
80
81### 指派代理人
82- 主要執行代理人：[Agent Name]
83- 檢查代理人：cinnamon-refactor-owl
84
85### 後續更新責任 (準備階段特有)
86- [ ] 更新相關任務的參考文件欄位
87- [ ] 補充依賴任務的詳細資訊
88- [ ] 建立文件間的關聯性

任務完成回報格式

 1## 任務完成回報 - vX.Y.Z
 2
 3### 完成項目
 4- [x] 目標1 完成
 5- [x] 目標2 完成
 6- [x] 測試驗證通過
 7
 8### 品質指標
 9- 測試通過率：100%
10- 程式碼覆蓋率：維持或提升
11- 效能影響：無負面影響
12
13### 技術變更摘要
14- 修改檔案數量：N 個
15- 新增程式碼行數：+N 行
16- 移除程式碼行數：-N 行
17
18### 發現問題
19- 無問題 / 發現問題清單
20
21### 後續建議
22- 下一個任務的建議
23- 潛在改善機會

品質控制機制

強制檢查點

任務執行前檢查

  • 任務目標明確定義
  • 完成標準可測量
  • 指派代理人明確
  • 風險評估完成
  • 參考文件完整性（強制） - UseCase、流程圖 Event、架構規範、依賴類別、測試設計全部填寫
  • 影響範圍明確性（強制） - 需建立/修改/影響的檔案清單完整列出

任務執行中檢查

  • 定期進度回報
  • 問題及時升級
  • 品質標準持續監控
  • 測試覆蓋率維持

任務完成後檢查

  • 重構代理人驗證通過
  • 測試通過率 100%
  • 程式碼品質符合標準
  • 文件同步更新

階段完成驗證機制

重要: 基於實戰經驗學習，每個開發階段必須通過完整驗證才能標記為完成。

階段完成檢查清單 (Stage Completion Checklist)

1. 編譯完整性檢查 (Compilation Integrity)
1# 強制執行的編譯檢查指令
2flutter analyze lib/ --no-fatal-warnings
3dart analyze lib/ --no-fatal-warnings
4
5# 檢查是否有 error 級別問題
6flutter analyze lib/ 2>&1 | grep -E "error" || echo "編譯檢查通過"

通過標準:

  • 0 個 error 級別問題
  • warning 和 info 級別問題可接受
  • 所有 import 語句正確解析
2. 依賴路徑一致性檢查 (Dependency Path Consistency)
1# 檢查是否有引用不存在檔案的問題
2flutter analyze lib/ 2>&1 | grep "Target of URI doesn't exist" || echo "路徑檢查通過"
3
4# 檢查是否符合 package 導入規範
5grep -r "import '\.\." lib/ || echo "無相對路徑導入"
6
7# 檢查是否有重複或錯誤的路徑引用
8find lib/ -name "*.dart" -exec grep -l "package:book_overview_app" {} \; | sort

通過標準:

  • 無「Target of URI doesn’t exist」錯誤
  • 100% 使用 package 導入格式，0% 相對路徑
  • 所有路徑指向正確的檔案位置
3. 測試通過率檢查 (Test Pass Rate)
1# 100% 測試通過率要求
2dart test --coverage
3flutter test --coverage
4
5# 確保所有測試套件都能執行
6dart test test/unit/ --reporter=expanded
7flutter test test/widget/ --reporter=expanded
8flutter test test/integration/ --reporter=expanded

通過標準:

  • 100% 測試通過率，無例外
  • 所有測試套件正常執行
  • 無測試環境錯誤
  • 測試覆蓋率不下降
4. 重複實作檢查 (Duplicate Implementation Check)
 1# 檢查是否有重複的服務實作
 2find lib/ -name "*service*.dart" | sort
 3find lib/ -name "*provider*.dart" | sort
 4
 5# 檢查類似命名的類別
 6grep -r "class.*Service" lib/ --include="*.dart" | sort
 7grep -r "class.*Provider" lib/ --include="*.dart" | sort
 8
 9# 檢查是否有功能重疊的實作
10echo "手動檢查是否有功能重複的實作"

通過標準:

  • 無功能重複的服務實作
  • 類別命名符合單一職責原則
  • 無廢棄或未使用的實作
  • 依賴關係清晰無衝突
5. 架構一致性檢查 (Architecture Consistency)
 1# 檢查檔案是否在正確的架構層級
 2ls -la lib/core/services/
 3ls -la lib/domains/*/services/
 4ls -la lib/presentation/*/services/
 5
 6# 驗證 Clean Architecture 分層
 7echo "確認檔案位置符合 Clean Architecture 原則"
 8
 9# 檢查導入路徑是否符合架構設計
10grep -r "import.*lib/core" lib/presentation/ || echo "無違反架構的導入"
11grep -r "import.*lib/presentation" lib/core/ || echo "無反向依賴"

通過標準:

  • 檔案位置符合 Clean Architecture 分層
  • 無跨層直接依賴違規
  • 依賴方向正確 (外層依賴內層)
  • 服務檔案位於正確的目錄結構

階段完成強制流程

每個開發階段必須按以下順序執行：

  1. 完成階段開發工作
  2. 執行編譯檢查 - 必須 0 error
  3. 執行測試檢查 - 必須 100% 通過
  4. 檢查路徑一致性 - 修正所有 import 問題
  5. 檢查重複實作 - 確保無功能重複
  6. 驗證架構一致性 - 檔案位置符合設計
  7. 更新工作日誌 - 記錄檢查結果
  8. 標記階段完成 - 更新 todolist 狀態

階段失敗處理原則

  • 任何檢查項目失敗 = 階段未完成
  • 必須修正所有問題後重新檢查
  • 不允許「暫時跳過」或「之後處理」
  • 問題修正優先於新功能開發
  • 重複檢查直到所有項目通過

檢查清單整合到工作日誌

每個開發階段的工作日誌必須包含
 1## 階段完成檢查
 2
 3### 編譯檢查
 4- [ ] flutter analyze 無 error
 5- [ ] dart analyze 無 error
 6- [ ] 無「Target of URI doesn't exist」錯誤
 7
 8### 測試檢查
 9- [ ] dart test 100% 通過
10- [ ] flutter test 100% 通過
11- [ ] 測試覆蓋率檢查完成
12
13### 一致性檢查
14- [ ] 無相對路徑 import
15- [ ] 無重複服務實作
16- [ ] 檔案位置符合架構設計
17
18### 最終確認
19- [ ] 所有檢查項目通過
20- [ ] 工作日誌更新完成
21- [ ] 準備進入下一階段

Hook 系統整合

此階段完成驗證機制與現有 Hook 系統整合：

  • PostEdit Hook - 檔案修改後自動檢查編譯狀態
  • Version Check Hook - 階段推進前強制執行完整檢查
  • Code Smell Detection Hook - 即時偵測重複實作問題
  • PM Trigger Hook - 檢查失敗時觸發專案管理介入

失敗處理機制

任務失敗類型

  1. 技術失敗 - 無法達成技術目標
  2. 品質失敗 - 無法通過品質檢查
  3. 時程失敗 - 超出預估完成時間
  4. 範圍失敗 - 任務範圍超出預期

失敗處理策略

  1. 技術失敗 → PM 代理人重新設計技術方案
  2. 品質失敗 → 重構代理人指導修正
  3. 時程失敗 → PM 代理人拆分任務
  4. 範圍失敗 → 主線程重新分派任務

進度追蹤機制

三重文件原則整合

本方法論的進度追蹤完全基於「三重文件原則」（詳見前述章節）：

  1. CHANGELOG.md - 版本功能變動（面向用戶）
  2. todolist.md - 任務全景圖（面向開發）
  3. work-log/ - 實作細節（面向交接）

三層進度管理（對應 work-log）

重要說明：三層進度管理主要對應到 work-log 文件系統，與 CHANGELOG 和 todolist 協同運作。

1. 大版本層級 (vX.Y.x) - 對應主版本工作日誌

  • 追蹤文件: docs/work-logs/vX.Y.0-main.md (主版本總覽)
  • 對應三重文件:
    • work-log: 詳細任務分派和執行記錄
    • todolist: vX.Y.x 系列所有任務清單
    • CHANGELOG: 版本發布時提取功能變動
  • 更新頻率: 任務分派時、階段完成時
  • 責任代理: 主線程、PM 代理人

2. 小版本層級 (vX.Y.1, vX.Y.2, …) - 對應小版本工作日誌

  • 追蹤文件: docs/work-logs/vX.Y.Z-[specific-task].md (具體任務)
  • 對應三重文件:
    • work-log: 完整的實作細節和 TDD 階段記錄
    • todolist: 單一任務狀態更新
    • CHANGELOG: 任務完成後潛在的功能變動點
  • 更新頻率: 任務執行中、任務完成時
  • 責任代理: 執行代理人、文件代理人

3. 任務層級 (TodoList) - 對應 todolist.md

  • 追蹤工具: TodoWrite 工具 + docs/todolist.md
  • 對應三重文件:
    • todolist: 任務狀態即時追蹤
    • work-log: 任務詳細資訊來源
    • CHANGELOG: 完成任務累積的功能變動
  • 更新頻率: 即時更新
  • 責任代理: 所有代理人

三重文件同步機制

任務執行流程中的文件更新

sequenceDiagram
    participant 主線程
    participant 執行代理人
    participant todolist
    participant work-log
    participant CHANGELOG

    主線程->>todolist: 檢視下一個待執行任務
    主線程->>work-log: 查看 vX.Y.0-main.md 分派清單
    主線程->>執行代理人: 分派任務 vX.Y.Z

    執行代理人->>work-log: 記錄執行過程到 vX.Y.Z.md
    執行代理人->>todolist: 更新任務狀態為「進行中」

    執行代理人->>work-log: 標記任務完成
    執行代理人->>todolist: 更新任務狀態為「完成」

    Note over 主線程,CHANGELOG: 版本發布時
    主線程->>work-log: 檢視所有已完成任務
    主線程->>CHANGELOG: 提取功能變動
    主線程->>todolist: 確認版本完成

版本發布時的三重文件協調

  1. 文件代理人檢查 work-log：

    • 讀取 vX.Y.0-main.md 所有已完成任務
    • 讀取每個 vX.Y.Z-task.md 實作細節

  2. 提取功能變動到 CHANGELOG：

    • 只記錄用戶可感知的功能變動
    • 忽略內部重構和技術細節
    • 依照 Keep a Changelog 格式撰寫

  3. 驗證 todolist 一致性：

    • 確認 todolist 標記的完成任務與 work-log 一致
    • 確認版本號對應正確

關鍵指標監控

效率指標

  • 任務完成速度 (任務數/天)
  • 平均任務執行時間
  • 升級請求頻率
  • 重做次數

品質指標

  • 測試通過率趨勢
  • 程式碼覆蓋率變化
  • 新增錯誤/警告數量
  • 效能回歸情況

協作指標

  • 代理人回應時間
  • 任務交接效率
  • 溝通品質評分
  • 問題解決時間

成功標準

方法論成功指標

效率成功標準

  • 30-40 個小版本任務如期完成
  • 每個任務平均完成時間 < 2 小時
  • 升級請求 < 10% 總任務數
  • 重做次數 < 5% 總任務數

品質成功標準

  • 100% 測試通過率維持
  • 程式碼覆蓋率不下降
  • 0 個新增的錯誤或警告
  • 效能目標全部達成

協作成功標準

  • 代理人角色職責清晰
  • 任務交接無遺漏
  • 問題升級機制有效
  • 文件同步及時準確

階段驗證成功標準

  • 每個階段 100% 通過編譯檢查
  • 每個階段 100% 通過測試檢查
  • 每個階段 100% 通過路徑一致性檢查
  • 每個階段 100% 通過重複實作檢查
  • 每個階段 100% 通過架構一致性檢查
  • 階段失敗率 < 5%
  • 平均階段驗證時間 < 30 分鐘

重構成功標準

架構成功標準

  • 完全符合設計文件 v2.0 規範
  • 原生 Exception 系統實作完成
  • 舊錯誤處理系統完全移除
  • 統一錯誤處理入口建立

效能成功標準

  • 錯誤建立時間 < 0.1ms
  • 記憶體占用 < 200 bytes
  • 程式碼量減少 ~80%
  • 編譯時間改善

敏捷開發本質

核心理念

敏捷開發是持續發現、快速調整、資訊流動的動態過程

資訊流動機制

Phase 間的資訊傳遞

graph TD
    A[Phase 1 設計] -->|架構決策| B[Phase 2 測試設計]
    B -->|實作指引| C[Phase 3 實作]
    C -->|重構發現| D[Phase 4 重構]

    B -->|問題識別| E[架構調整]
    E -->|更新設計| A
    E -->|更新測試| B
    E -->|更新實作| C

    C -->|技術債務| F[文件補充]
    F -->|參考資料| C
    F -->|設計優化| A

v0.11 實際資訊流範例

Phase 1 → Phase 2 傳遞：

 1Phase 1 (v0.11.1) 產出:
 2- 44 個 Event 流程設計
 3- 3 個核心流程圖
 4- 架構層級劃分
 5
 6Phase 2 (v0.11.2) 接收並發現:
 7- 流程圖定義清楚
 8- 注意：BookEnrichmentData 位置錯誤
 9- 4 個命名不一致
10- Domain 服務層缺失
11
12Phase 2 回饋 Phase 1:
13- 修正架構問題 → 立即執行
14- 更新流程圖命名 → 完成修正

Phase 2 → Phase 3 傳遞：

 1Phase 2 (v0.11.2) 產出:
 2- 335 個測試用例設計
 3- 33 個測試檔案規劃
 4- 架構修正決策
 5- 時程調整 (Plan B)
 6
 7Phase 3 (v0.11.3-14) 接收並執行:
 8- 測試先行 TDD 開發
 9- 依賴 Phase 2 架構修正
10- 參考測試設計驗收標準
11- 遵循調整後時程
12
13Phase 3 動態更新 Phase 2 發現:
14- 補充任務參考文件
15- 更新依賴類別資訊
16- 調整實作優先序

靈活任務交接

交接不是單向傳遞

傳統錯誤模式：

1Phase 1 完成 → 凍結
2Phase 2 開始 → 發現問題但不敢改 Phase 1
3Phase 3 繼續 → 基於錯誤的設計實作

敏捷正確模式：

1Phase 1 完成 → 基礎版本
2Phase 2 發現 → 立即回報並調整 Phase 1
3Phase 1 更新 → 同步更新 Phase 2 和 Phase 3 參考
4Phase 3 執行 → 基於最新、最正確的設計

任務交接檢查清單

前置任務完成時：

 1## 任務交接檢查 - vX.Y.Z 完成
 2
 3### 產出清單
 4- [ ] 程式碼檔案: [列出新建/修改檔案]
 5- [ ] 測試檔案: [列出測試覆蓋]
 6- [ ] 文件更新: [列出相關文件]
 7
 8### 後續任務更新
 9- [ ] 檢查哪些任務依賴此產出
10- [ ] 更新後續任務的「依賴類別」參考
11- [ ] 補充實作範例連結
12- [ ] 通知相關代理人（如已分派）
13
14### 發現問題記錄
15- [ ] 是否有架構問題影響後續任務
16- [ ] 是否有命名需要統一
17- [ ] 是否有技術債務需要標註
18- [ ] 是否需要調整後續任務範圍
19
20### 主版本日誌更新
21- [ ] 標記任務完成
22- [ ] 補充「重要發現」區域
23- [ ] 更新進度統計

持續文件精煉

文件不是一次性產物

文件生命週期：

graph LR
    A[初始版本] --> B[Phase 1 補充]
    B --> C[Phase 2 修正]
    C --> D[Phase 3 完善]
    D --> E[Phase 4 定版]

    C -->|發現問題| F[緊急更新]
    F --> C

    D -->|實作發現| G[補充範例]
    G --> D

文件更新觸發點

1. 強制更新時機
  • 架構變更 → 立即更新所有相關文件
  • 介面簽名變更 → 更新流程圖和參考
  • 依賴關係變化 → 更新任務依賴清單
  • 命名修正 → 全專案統一更新
2. 建議更新時機
  • 發現更好的實作方式 → 補充範例
  • 常見問題解決 → 補充 FAQ
  • 效能優化技巧 → 補充最佳實踐
  • 測試技巧發現 → 補充測試指引
3. v0.11 實際更新案例
案例 1：架構修正觸發連鎖更新
 1觸發: BookEnrichmentData 遷移到 Domain 層
 2
 3更新文件清單:
 41. 流程圖 book-info-query-flow.md
 5   - Event 6-7 層級標註
 6
 72. 主版本日誌 v0.11.0-main.md
 8   - 架構調整記錄
 9   - v0.11.5, v0.11.6 依賴類別更新
10
113. 測試設計 v0.11.2-tdd-phase2-test-design.md
12   - Mock 設定路徑更新
13
144. 所有後續任務描述
15   - 參考文件補充
16   - import 路徑範例
案例 2：Phase 2 發現補充任務參考
 1觸發: Phase 2 完成測試設計
 2
 3補充內容:
 41. v0.11.5-14 所有任務
 5   - 新增「測試設計參考」欄位
 6   - 具體到測試檔案名稱和用例數
 7
 82. v0.11.0-main.md
 9   - 補充「Phase 2 重要發現」區域
10   - 記錄時程調整和原因
11
123. 依賴類別參考
13   - v0.11.3, v0.11.4 產出類別
14   - 列入所有相關任務參考

響應式規劃

規劃不是固定藍圖

初始規劃基於：

  • 現有知識和經驗
  • 需求分析結果
  • 架構設計假設
  • 風險初步評估

執行中調整基於：

  • 實際發現的問題
  • 技術方案驗證結果
  • 測試設計識別的複雜度
  • 代理人的回報和建議

調整決策標準

何時調整規劃？

立即調整（阻塞性）：

  • 架構設計根本性錯誤
  • 依賴關係衝突無法解決
  • 技術方案不可行
  • 測試通過率無法達成

範例：BookEnrichmentData 位置錯誤 → 立即停止並修正

計畫調整（重要性）：

  • 任務複雜度超出預期
  • 需要額外的前置任務
  • 測試用例數量大幅增加
  • 發現缺失的功能模組

範例：Domain 服務層缺失 → 調整時程從 4-6 天到 6-7 天

優化調整（改善性）：

  • 發現更好的實作方式
  • 可以提前完成的任務
  • 可以合併的重複工作
  • 效能優化機會
調整必須文件化

調整決策記錄格式：

 1## 規劃調整決策 - [調整標題]
 2
 3**調整日期**: YYYY-MM-DD
 4**觸發原因**: [為什麼需要調整]
 5**影響範圍**: [哪些任務受影響]
 6
 7### 原始規劃
 8- 任務數量: N 個
 9- 預估時程: X 天
10- 假設條件: [列出]
11
12### 調整後規劃
13- 任務數量: M 個
14- 預估時程: Y 天
15- 調整原因: [詳細說明]
16
17### 具體變更
181. [變更 1]
192. [變更 2]
203. [變更 3]
21
22### 風險評估
23- 新風險: [識別出的新風險]
24- 緩解措施: [對應的處理方式]
25
26### 溝通記錄
27- YYYY-MM-DD: [通知相關代理人]
28- YYYY-MM-DD: [更新主版本日誌]

v0.11 規劃調整實例

Plan B 決策：

 1## 規劃調整決策 - v0.11.0 採用 Plan B
 2
 3**調整日期**: 2025-09-30
 4**觸發原因**: Phase 2 識別出 28 個 TDD 新建測試和 Domain 層缺失
 5
 6### 原始規劃
 7- 任務數量: 10-12 個小版本
 8- 預估時程: 4-6 天
 9- 假設: 60% 實作已完成，40% 補充測試
10
11### 調整後規劃
12- 任務數量: 14 個小版本
13- 預估時程: 6-7 天 (+1-2 天)
14- 原因: Domain 層需從零建立，測試覆蓋率需 100%
15
16### 具體變更
171. 新增 v0.11.3-4：Domain 輸入驗證和查詢服務
182. 延後外部 API 整合到 v0.12.0
193. 簡化速率控制，移除批次處理和斷路器
204. 專注核心功能，確保品質優先
21
22### 風險評估
23- 新風險: 時程延長 1-2 天
24- 緩解: 簡化外部 API 整合，移到下個版本
25- 好處: Domain 層基礎扎實，後續開發更順暢

敏捷成功關鍵

1. 資訊透明化

  • 所有發現立即記錄
  • 所有決策公開透明
  • 所有變更同步通知

2. 快速響應能力

  • 問題當日解決
  • 調整迅速執行
  • 文件即時更新

3. 持續改進循環

  • 每個 Phase 總結學習
  • 問題根因分析
  • 流程持續優化

4. 團隊協作文化

  • 鼓勵主動回報
  • 容許計畫調整
  • 品質高於速度

使用指引

主線程使用方式

  1. 檢查主版本工作日誌，找到下一個待執行任務
  2. 分派任務給適當的子代理人，使用標準任務格式
  3. 等待回報，不親自執行任何程式碼修改
  4. 處理升級，必要時呼叫 PM 代理人
  5. 確認完成，由重構代理人和文件代理人完成驗證

子代理人使用方式

  1. 接收任務，確認任務目標和完成標準
  2. 評估規模，如發現過大立即向上回報
  3. 執行任務，專注於指派的具體工作
  4. 回報結果，使用標準回報格式
  5. 配合檢查，與重構代理人協作完成驗證

緊急情況處理

代理人無法執行任務

  1. 立即向主線程回報
  2. 主線程評估替代方案
  3. 必要時調整任務或更換代理人

技術方案遇到阻礙

  1. 子代理人立即停止執行
  2. 向主線程詳細回報問題
  3. 主線程呼叫 PM 代理人重新設計

品質標準無法達成

  1. 重構代理人拒絕通過
  2. 明確指出品質問題
  3. 要求修正或重新設計

v0.11.0 實戰案例集

案例總覽

v0.11.0 統一書籍資訊查詢服務開發過程，完整展現了敏捷重構方法論的實際應用，包含任務拆分、動態調整、代理人協作等核心流程。

案例 1：Phase 2 發現觸發 Plan B 調整

背景

初始規劃：

  • 預估時程：4-6 天
  • 假設：60% 程式碼已完成，補充測試即可
  • 任務數：10-12 個小版本

觸發事件

sage-test-architect 完成 Phase 2 測試設計後回報：

 1## 重大發現 - Phase 2 測試設計
 2
 3### 實作狀態檢查結果
 4- 已完成：GoogleBooksApiImplementation 已完整實作
 5- 已完成：GoogleBooksDto 和轉換已實作
 6- 缺失：Domain 服務層完全缺失（0% 完成度）
 7- 待辦：需要 28 個 TDD 新建測試
 8- 注意：BookEnrichmentData 位置錯誤
 9
10### 影響評估
11- 預估工作量：原估 2-3 天 → 實際需 4-5 天
12- 複雜度：低 → 高（需從零建立 Domain 層）
13- 風險：中 → 高（架構債務累積風險）

主線程決策過程

  1. 檢視相關文件：

    • 閱讀 Clean Architecture 規範
    • 確認 Domain 層職責定義
    • 評估架構債務風險

  2. 召開決策會議（主線程 + PM代理人）：

    • 分析時程影響
    • 評估功能範圍調整可能性
    • 制定 Plan A、Plan B 方案

  3. 決策記錄：

 1## 決策 - v0.11.0 採用 Plan B
 2
 3**決策日期**: 2025-09-30
 4**決策者**: 主線程
 5
 6### 方案比較
 7**Plan A**: 維持原時程，降低測試覆蓋率
 8- 優點：時程不變 (4-6 天)
 9- 缺點：測試覆蓋率 < 80%
10- 缺點：架構債務累積
11- 缺點：違反品質標準
12
13**Plan B**: 延長時程，確保品質（採用）
14- 優點：測試覆蓋率 100%
15- 優點：Domain 層基礎扎實
16- 優點：架構符合規範
17- 注意：時程延長 +1-2 天 (→ 6-7 天)
18
19### 決定
20採用 Plan B，理由：
211. 品質優於速度（專案鐵律）
222. Domain 層是核心基礎，不能妥協
233. 延長 1-2 天可接受
244. 簡化外部 API 整合補償時程
25
26### 執行計畫
271. 新增 v0.11.3-4：Domain 輸入驗證和查詢服務
282. 延後外部 API 整合（Amazon、台灣出版品）到 v0.12.0
293. 簡化速率控制，移除批次處理和斷路器
304. 更新所有後續任務參考文件

執行結果

  • v0.11.3-4 成功完成（71 個測試 100% 通過）
  • 優點：Domain 層基礎扎實
  • 時程控制良好（實際 +1 天）
  • 品質標準維持 100%

學習要點

  1. 測試設計階段至關重要：能提前識別實作狀態問題
  2. 品質不妥協：短期時程延長換長期穩定發展
  3. 靈活調整功能範圍：延後次要功能，專注核心價值
  4. 決策必須文件化：清楚記錄原因和權衡

案例 2：架構衝突檢測與立即修正

背景

Phase 2 測試設計過程中，sage-test-architect 發現 BookEnrichmentData 位於錯誤層級。

問題描述

 1## 架構衝突 - BookEnrichmentData 位置錯誤
 2
 3### 當前狀態
 4- 位置: `lib/infrastructure/api/google_books/book_enrichment_data.dart`
 5- 職責: 純資料結構，封裝書籍豐富化資料
 6
 7### 問題分析
 8- BookEnrichmentData 無外部依賴，應屬於 Domain 層
 9- Infrastructure 層不應定義 Domain 實體
10- 違反 Clean Architecture 依賴方向
11
12### 影響範圍
13- v0.11.5 (資料處理) 需要引用
14- v0.11.6 (API 客戶端) 需要轉換
15- 所有測試需要更新 import 路徑
16
17### 建議
18立即遷移到 Domain 層，阻塞性問題。

主線程處理

  1. 確認問題嚴重性：阻塞（影響後續所有任務）
  2. 立即停止 Phase 3 啟動：等待架構修正完成
  3. 指派緊急任務：
 1## 緊急任務 - v0.11.2-fix BookEnrichmentData 遷移
 2
 3**優先級**: 最高
 4**執行人**: mint-format-specialist
 5**預估時間**: 0.5 小時
 6
 7### 執行步驟
 81. 遷移檔案到 `lib/domains/book_info/entities/`
 92. 更新所有 import 引用
103. 執行測試確認無錯誤
114. 提交變更
12
13### 完成後動作
141. 更新流程圖層級標註
152. 更新 v0.11.5-6 任務參考
163. 通知所有相關代理人
174. 繼續 v0.11.3 執行
  1. 執行和追蹤：
    • 0.4 小時完成遷移
    • Git commit: 58b1603
    • 更新相關文件
    • 解除 Phase 3 阻塞

執行結果

  • 架構問題立即解決
  • 延遲影響最小化（< 1 小時）
  • 後續任務基於正確架構
  • 無技術債務累積

學習要點

  1. 架構問題零容忍：立即停止並修正
  2. 緊急任務機制：快速插入高優先級任務
  3. 影響範圍評估：精確識別受影響任務並更新
  4. 追蹤閉環：確認完成並解除阻塞

案例 3：命名不一致的系統化修正

背景

Phase 2 測試設計發現 4 個流程圖元件命名與程式碼不符。

問題清單

 1## 命名不一致清單
 2
 31. 流程圖: QueryValidator
 4   程式碼: BookInputValidator
 5   影響: Event 1-2
 6
 72. 流程圖: BookInfoService
 8   程式碼: UnifiedBookInfoService
 9   影響: Event 3-5
10
113. 流程圖: DataProcessor
12   程式碼: BookEnrichmentProcessor
13   影響: Event 6-7
14
154. 流程圖: CacheService
16   程式碼: ApiCacheManager
17   影響: Event 8-9

決策過程

選項 A：更新流程圖命名

  • 流程圖是設計文件，應該貼近業務語意
  • 程式碼已實作，更新成本高
  • 捨棄：流程圖命名過於簡化

選項 B：更新程式碼命名

  • 程式碼命名更具體清楚
  • 符合 Domain 層命名原則
  • 採用：流程圖更新成本低

執行計畫

 1## 命名統一任務
 2
 3**執行**: memory-network-builder
 4**時程**: 0.5 小時
 5
 6### 更新範圍
 71. 更新 3 個流程圖文件
 82. 更新主版本工作日誌
 93. 更新所有任務參考
104. Git commit 記錄變更

執行結果

  • 流程圖命名統一
  • Git commit: 79992cb
  • 所有任務參考同步更新
  • 代理人無歧義參考

學習要點

  1. 命名一致性至關重要：避免代理人困惑
  2. 及早發現及早處理：Phase 2 發現是最佳時機
  3. 全專案同步更新：確保所有引用一致
  4. 決策權衡明確：記錄為什麼選擇特定方案

案例 4：工作日誌架構重組

背景

v0.11.0 初始建立了 6 個工作日誌文件，違反「一個主版本一個日誌」原則。

問題描述

1初始狀態:
2- v0.11.0-unified-api-implementation.md (主日誌)
3- v0.11.0-unified-api-flow-design.md (Phase 1)
4- v0.11.0-implementation-status-report.md (Phase 2.1)
5- v0.11.0-test-design-main-flow.md (Phase 2.2)
6- v0.11.0-test-design-api-fallback.md (Phase 2.3)
7- v0.11.0-test-design-rate-limiting.md (Phase 2.4)
8
9問題: 6 個檔案都以 v0.11.0 開頭，不符合方法論規範

重組策略

參考 v0.9.0 成功模式，制定重組計畫：

 1## 重組計畫
 2
 3### 新架構
 4- v0.11.0-main.md (主版本總覽)
 5- v0.11.1-tdd-phase1-design.md (Phase 1)
 6- v0.11.2-tdd-phase2-test-design.md (Phase 2 合併)
 7- v0.11.3-domain-input-validation.md (批次 1.1)
 8- v0.11.4-core-query-service.md (批次 1.2)
 9
10### 執行步驟
111. 重命名主日誌
122. Phase 1 重命名為 v0.11.1
133. Phase 2 四個文件合併為 v0.11.2
144. 批次實作提取為 v0.11.3-4
155. 清理舊檔案
166. Git 提交重組結果

執行結果

  • 10 個檔案變更（929 行新增，5910 行刪除）
  • Git commit: d86940a
  • 符合方法論規範
  • 清晰的版本架構

學習要點

  1. 方法論合規性檢查：定期審查是否符合標準
  2. 參考成功案例：v0.9.0 模式可複用
  3. 大膽重組：發現問題立即修正，不將就
  4. 文件瘦身：主版本日誌簡潔，詳細內容在子版本

方法論改進建議（基於實戰）

1. 強化 Phase 2 重要性

發現：Phase 2 測試設計階段能提前識別 80% 的實作問題 建議：增加 Phase 2 的檢查清單和回報機制

2. 任務參考文件標準化（已強制執行）

發現：初始任務描述參考文件不足，導致代理人需要詢問 原建議：強制要求 UseCase、流程圖 Event、依賴類別完整填寫 已實施：

  • 更新「準備度檢查問題」加入第 5 項強制檢查
  • 更新「任務執行前檢查」加入參考文件和影響範圍強制項目
  • 違規處理機制：缺少任何一項視為任務規劃不合格
  • 實戰驗證：v0.12.1 已補充完整參考文件和影響範圍章節

3. 動態更新機制制度化

發現：Phase 發現需要立即傳遞給後續任務 建議：建立「重要發現」區域，強制每個 Phase 完成後更新

4. 緊急任務插入流程

發現：架構問題需要立即處理 建議：定義緊急任務命名規則（vX.Y.Z-fix）和執行流程

5. 工作日誌結構模板

發現：初期結構混亂，後期重組成本高 建議：提供標準模板，從一開始就符合規範

方法論版本歷史

v1.3 (2025-10-07)

  • 新增: 三重文件協調原則

v1.2 (2025-09-30)

  • 新增: 任務拆分實戰範例（基於 v0.11.5 情境）
  • 新增: 動態文件更新機制（Phase 發現傳遞流程）
  • 新增: 代理人回報與討論流程（4 種回報類型）
  • 新增: 敏捷開發本質說明（資訊流動、靈活交接、響應式規劃）
  • 新增: v0.11.0 實戰案例集（4 個完整案例）
  • 更新: 任務參考文件格式（強制完整填寫要求）
  • 更新: 基於 v0.11 實戰經驗完善所有流程

v1.1 (2025-09-29)

  • 新增: 階段完成驗證機制 (基於實戰經驗學習)
  • 新增: 5 項強制檢查項目 (編譯、測試、路徑、重複、架構)
  • 新增: 階段失敗處理原則
  • 新增: Hook 系統整合指引
  • 更新: 成功標準，加入階段驗證指標
  • 修正: 移除版本特定內容，改為通用流程

v1.0 (2025-09-27)

  • 建立: 基礎敏捷重構方法論
  • 定義: Agent 分工協作模式
  • 建立: 任務分派和品質控制機制

當前版本: v1.2 適用範圍: 通用敏捷重構開發流程 最後更新: 2025-09-30 責任人: Claude Code AI Assistant 重大更新: 基於 v0.11.0 實戰經驗，新增任務拆分範例、動態更新機制、代理人回報流程、敏捷開發本質說明

]]>