Project 05. 讓 agent 自己檢查自己做的對不對

相關講義：L09. 為什麼 agent 會提前宣告完成 · L10. 為什麼端到端測試會改變結果 本篇範本檔案：templates/

你要做什麼

前四個項目裡，"檢查做得對不對"這件事要麼是你手動做的，要麼是靠檔案規則強制執行的。這個項目要讓 agent 自己來檢查。

方法是角色分離。以前是同一個 agent 既寫代碼又判斷質量。現在拆開：一個 agent 負責實現（生成者），另一個 agent 負責審查（評估者）。更進一步，還可以加一個負責規劃的角色（規劃者）。你要跑三次，看每加一層角色分離，結果好多少。

選一個實質性的功能升級（比如多輪對話歷史、引用面板重設計、文檔集合與篩選），三次都做同一個升級，唯一變量是 harness 的角色分工。

用什麼工具

• Claude Code 或 Codex（用於生成和規劃角色）
• 同一個或另一個 agent 實例（用於評估角色）
• 評估量表（參考 docs/zh-TW/resources/templates/evaluator-rubric.md）
• Sprint contract 範本（參考 docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md）

具體步驟

準備工作

1. 基於 P04 完成後的代碼，從同一個 commit 出發。
2. 創建三個分支：p05-single、p05-gen-eval、p05-plan-gen-eval。
3. 選定一個功能升級，寫清楚驗收標準。三次運行的功能範圍和驗收標準完全一致。
4. 寫好評估量表，打分維度至少包括：正確性、可靠性、可維護性、用戶體驗。

第一次運行（弱 harness — 單角色）

切到 p05-single 分支。

1. 一個 agent 包攬規劃、實現、自查。
2. 沒有外部評估量表，agent 自己判斷做得好不好。
3. 記錄最終產出和未解決的缺陷。

第二次運行（強 harness — 生成者 + 評估者）

切到 p05-gen-eval 分支。

1. 生成者和評估者先用 sprint contract 對齊：做什麼、怎麼驗證、什麼不算在範圍內。
2. 生成者實現功能。
3. 評估者用評估量表打分，反饋問題。
4. 生成者根據反饋修改。至少經過一輪修訂。
5. 記錄評估者抓住了多少缺陷、修訂了多少內容。

第三次運行（更強 harness — 規劃者 + 生成者 + 評估者）

切到 p05-plan-gen-eval 分支。

1. 規劃者先拆解任務、定義步驟和依賴關係。
2. 生成者按規劃實現。
3. 評估者用同一份評估量表打分。
4. 至少經過一輪修訂。
5. 記錄規劃是否減少了返工。

評估者調優

評估者不是一次就能用好的。初始版本的評估者往往會"發現問題然後自己說服自己通過"。你需要：

1. 讓評估者給一個已完成的 sprint 打分。
2. 和你自己的判斷對比。
3. 哪裡有分歧，就把量表寫得更具體。
4. 重新跑評估者，檢查對齊程度。
5. 重複 3-5 輪，直到評估者判斷和你的判斷基本一致。記錄每一輪調優的內容。

怎麼衡量結果

指標	說明
範圍定義質量	編碼前的任務拆解清晰度
缺陷檢出數	交付前被評估者抓到的缺陷數量和嚴重程度
量表評分	各維度的得分（正確性、可靠性、可維護性、UX）
返工量	評估反饋後需要重做的比例
最終健壯性	升級後功能在實際運行中的穩定程度
評估者調優輪數	評估者判斷與你對齊需要的迭代次數
Sprint contract 效果	合同是否減少了評估中的模糊地帶

要交什麼

• Sprint contract 文檔
• 評估者調優日誌（每輪改了什麼、為什麼改）
• 單角色運行記錄：提示詞、日誌、可運行證據
• 生成者+評估者運行記錄：含量表評分和修訂記錄
• 規劃者+生成者+評估者運行記錄：含規劃文檔、量表評分、修訂記錄
• 一份對比筆記：質量提升幅度和協調成本

對應講義

• Lecture 09 — 為什麼 agent 總是過早宣佈勝利
• Lecture 10 — 為什麼端到端測試能改變結果
• Lecture 11 — 為什麼可觀測性屬於 harness 的一部分