代理自我評估 是做什麼的？
在完成複雜任務後，代理會暫停下來，根據結構化的五軸評分表為自己的輸出進行評分。這不是通過/失敗的門檻，而是刻意的反思步驟，能在使用者介入之前，先行捕捉疏漏、標示過度自信，並找出可改進的領域。
何時啟動
- 在編寫橫跨 3 個以上檔案或超過 50 行程式碼之後
- 在完成一個多步驟工作流程（實作 → 測試 → 審查）之後
- 在經歷 3 次以上嘗試的除錯會話之後
- 在產出設計文件、架構決策或書面分析之後
- 當使用者問「那個有多好？」或「評分你自己」時
- 在任何會話的 Stop 鉤子結束時（如果已配置，請參閱
references/hook-integration.md）
核心概念
五大評估軸線
| 軸線 | 問題 | 它能捕捉到什麼 |
|---|---|---|
| 精確度 | 事實、聲明和輸出是否正確？ | 幻覺、錯誤的 API 名稱、不正確的語法、虛假陳述 |
| 完整性 | 是否涵蓋了使用者要求的所有事項？ | 遺漏的邊界情況、未處理的錯誤路徑、遺忘的需求、跳過的子任務 |
| 清晰度 | 解釋是否易於理解且結構良好？ | 令人困惑的解釋、未定義的術語、缺少上下文、冗長囉嗦 |
| 可操作性 | 使用者能否立即根據輸出採取行動？ | 模糊的建議、遺漏的步驟、「你應該做 X」但未說明如何做、無驗證路徑 |
| 簡潔度 | 是否使用了最少的詞語/代幣？ | 冗餘、過度解釋、逐字重複使用者的問題、填充內容 |
評分標準
5 — 傑出：沒有合理改進的空間
4 — 良好：僅有小問題，無實質性差距
3 — 及格：滿足要求，但至少有一個軸線存在明顯弱點
2 — 薄弱：存在明顯差距，影響可用性或正確性
1 — 差勁：基本上未滿足要求或包含重大錯誤
證據規則
所有低於 5 分的評分必須引用具體證據。 3 分的評分不能只說「可以更好」——必須確切說出缺少或錯誤的內容。口訣：「展示差距，而不只是命名它。」
工作流程
步驟 1：收集原始材料
收集你需要評估的項目：
- 原始使用者請求（從對話中回讀）
- 你的最終回應/輸出（交付物）
- 任何驗證正確性的工具輸出（測試結果、退出碼、lint 輸出）
- 在任務期間收到的任何使用者反饋（修正、「再試一次」、「這不對」）
步驟 2：獨立評分每個軸線
逐一處理 5 個軸線。對每個軸線：
- 閱讀軸線問題
- 在輸出中尋找證據（或證據不足）
- 分配 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 — 使用了 urllib3，與我們基於 httpx 的
程式碼庫不符。使用了錯誤的函式庫。
完整性： 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 傳輸層重新執行」勝過「修正函式庫問題」。
- 使用工具輸出作為證據。 如果測試通過了，就引用它們。如果 lint 乾淨，就引用它。不要猜測——用 grep 尋找證明。
- 如果你找不到任何差距，請再努力一點。 在所有 5 個軸線上都獲得完美分數是罕見的。捫心自問：「如果我是使用者，這個輸出中什麼會讓我惱火？」
相關技能
agent-eval— 不同編碼代理在基準任務上的正面對決比較verification-loop— 針對預期結果進行輸出的系統性驗證security-review— 以安全為重點的程式碼審查核對清單