代理自我評估
在完成一個複雜任務後，代理會暫停並根據結構化的五軸評分標準來評估自己的輸出。這不是一個通過/不通過的關卡——這是一個深思熟慮的反思步驟，能夠在使用者提出疑問之前，就捕捉到遺漏、標記過度自信，並找出需要改進的地方。
何時啟用
- 在編寫跨越 3 個以上檔案或 50 行以上的程式碼之後
- 在完成一個多步驟工作流程之後（實作 → 測試 → 審查）
- 在一個涉及 3 次以上嘗試的除錯過程之後
- 在產出設計文件、架構決策或書面分析之後
- 當使用者問「那個做得怎麼樣？」或「給自己打分」時
- 在任何會話的停止鉤子（Stop hook）結尾處（如果已配置——請參閱
references/hook-integration.md）
核心概念
五個評估軸向
| 軸向 | 問題 | 它捕捉什麼 |
|---|---|---|
| 準確性 | 事實、陳述和輸出是否正確？ | 幻覺、錯誤的 API 名稱、不正確的語法、虛假陳述 |
| 完整性 | 是否涵蓋了使用者要求的所有內容？ | 遺漏的邊緣案例、未處理的錯誤路徑、被遺忘的需求、跳過的子任務 |
| 清晰度 | 解釋是否易於理解且結構良好？ | 令人困惑的解釋、未定義的術語、遺漏的上下文、冗長的贅述 |
| 可操作性 | 使用者是否能立即根據輸出採取行動？ | 模糊的建議、遺漏的步驟、「你應該做 X」但未說明如何做、沒有驗證路徑 |
| 簡潔性 | 是否使用了最少的單詞/代幣？ | 冗餘、過度解釋、逐字重複使用者的問題、填充內容 |
評分標準
5 — 卓越：沒有任何合理的改進空間
4 — 良好：只有一些小瑕疵，沒有實質性的差距
3 — 合格：滿足了要求，但在至少一個軸向上有明顯的弱點
2 — 薄弱：存在明顯的差距，影響了可用性或正確性
1 — 差勁：從根本上錯失了要求或包含重大錯誤
證據規則
任何低於 5 分的評分必須引用具體的證據。3 分不能只說「可以更好」——必須確切說明遺漏了什麼或錯在哪裡。核心準則：「展示差距，而不只是命名它。」
工作流程
步驟 1：收集原始材料
收集你將要評估的內容：
- 原始使用者請求（從對話中回讀）
- 你的最終回應/輸出（交付物）
- 任何用於驗證正確性的工具輸出（測試結果、退出代碼、lint 輸出）
- 在任務期間收到的任何使用者反饋（更正、「再試一次」、「那個不對」）
步驟 2：獨立評分每個軸向
逐一處理五個軸向。針對每個軸向：
- 閱讀該軸向的問題
- 在輸出中找到證據（或缺乏證據）
- 分配 1-5 分
- 如果分數 < 5，撰寫一句改進備註，引用差距所在
不要先在腦中計算平均分數然後反向推導。每個軸向都應從頭評分。
步驟 3：產出評估報告
使用 templates/evaluation-report.md 中的範本。報告必須包含：
- 一句話摘要
- 五軸評分卡（每個軸向的分數 + 證據）
- 總體分數（簡單平均值，四捨五入到小數點後一位）
- 1-3 個按影響力排序的具體改進建議
- 自我檢查：「使用者是否會同意這個評估？」
步驟 4：應用改進
如果有任何軸向得分為 3 或更低：
- 說明你會採取什麼不同的做法
- 如果差距可在 30 秒內修正（遺漏的連結、不清楚的措辭），立即修正它
- 如果差距需要重做，明確標記它：「此軸向得分為 [原因]，因為 [證據]。使用 [具體修正] 重新執行可能會將其提升至 [分數]。」
程式碼範例
範例：良好的評估（分數 4+）
任務：為 HTTP 客戶端添加重試邏輯
評分卡：
準確性： 5 — 所有 API 呼叫皆正確。已驗證：重試使用指數退避。
無幻覺的方法。
完整性： 4 — 涵蓋快樂路徑 + 3 個錯誤案例。遺漏：
處理掛起連線的超時處理。
清晰度： 5 — 程式碼註解說明退避公式。
PR 描述連結到促使此變更的事件。
可操作性： 5 — 只需一次合併。無後續任務。測試通過。
簡潔性： 4 — 總共 47 行。重試迴圈可以提取到一個
輔助函數中，以減少約 8 行。
總體：4.6 — 一個差距（超時處理）。在合併前修正。
範例：薄弱的評估（分數 2-3）
任務：為 HTTP 客戶端添加重試邏輯
評分卡：
準確性： 2 — 使用了不符合我們基於 httpx 的
程式碼庫的 urllib3。使用了錯誤的函式庫。
完整性： 3 — 對 GET 有效。POST/PUT 未處理（使用者
說的是「所有 HTTP 請求」）。
清晰度： 4 — 程式碼可讀性高。良好的變數命名。
可操作性： 2 — 提及了「添加測試」，但未建立測試檔案。
使用者在合併前必須自己編寫測試。
簡潔性： 3 — 120 行。重試配置在 3 個地方重複，
而不是使用一個共享的 RetryConfig 物件。
總體：2.8 — 使用了錯誤的函式庫。需要用 httpx 重寫。
先修正準確性（切換到 httpx），然後擴展到所有 HTTP
方法，最後整合配置。
反模式
「全部都是 5 分」
失敗：準確性： 5 — 全部很好。
完整性： 5 — 全部涵蓋。
清晰度： 5 — 清晰。
沒有引用證據。這是自我恭維，不是評估。真正的 5 分需要證明沒有什麼可以改進。
因範圍蔓延而過度扣分
失敗：完整性： 2 — 未處理 WebSocket 連線或
gRPC 串流（使用者沒有要求這些）
只根據使用者實際要求的內容進行評估，而不是根據你本可以額外構建的內容。
利用評估重新爭論
失敗：「正如我之前所說，這種方法不對。分數：1」
評估是關於交付的輸出，而不是關於重新爭論已經做出的設計決策。如果方法有誤，應該在交付前就被發現。
將個人偏好與客觀差距混為一談
失敗：「分數：3。我不喜歡 Python 裝飾器。」
「不喜歡」不是證據。請引用具體的可讀性、可測試性或正確性問題，否則請將分數保持在 4+。
最佳實踐
- 評估輸出，而非過程。 使用者關心的是你交付了什麼，而不是你迭代了多少次。
- 每個薄弱軸向只提一個改進點。 不要為一個軸向列出 5 件事——選擇影響最大的差距。
- 將改進與使用者影響聯繫起來。「缺少錯誤處理意味著使用者的 API 呼叫會無聲崩潰」勝過「添加錯誤處理」。
- 具體說明「修正完成」的樣子。「使用配置了重試機制的 httpx transport 重新執行」勝過「修正函式庫問題」。
- 使用工具輸出作為證據。 如果測試通過，引用它們。如果 lint 乾淨，引用它。不要猜測——用 grep 找證據。
- 如果你找不到任何差距，再努力找找。 在所有五個軸向上都獲得完美分數是很罕見的。捫心自問：「如果我是使用者，這個輸出有什麼地方會讓我惱火？」
相關技能
agent-eval— 不同程式碼代理在基準任務上的正面對比verification-loop— 針對預期結果的系統性輸出驗證security-review— 安全導向的程式碼審查清單