agent-self-evaluation

Agent Self-Evaluation

完成复杂任务后，智能体暂停并按结构化 5 轴 rubric 评估自己的输出。这不是 pass/fail gate，而是刻意反思步骤，用于在用户发现前捕捉遗漏、标记过度自信和暴露可改进区域。

何时激活

• 写了跨 3+ 文件或 50+ 行的代码后
• 完成多步 workflow 后（implement → test → review）
• 经历 3+ 次尝试的调试会话后
• 产出设计文档、架构决策或书面分析后
• 用户问 “how good was that?” 或 “rate yourself”
• 任何 session Stop hook 结束时（如果已配置——见 references/hook-integration.md）

核心概念

5 个评估维度

维度	问题	捕捉什么
Accuracy	事实、声明和输出是否正确？	幻觉、错误 API 名、错误语法、虚假陈述
Completeness	是否覆盖用户要求的所有内容？	漏掉边缘情况、未处理错误路径、忘记需求、跳过子任务
Clarity	解释是否易懂且结构良好？	混乱解释、未定义术语、缺少上下文、啰嗦
Actionability	用户能否立即基于输出行动？	模糊建议、缺少步骤、只说“you should X”但不展示怎么做、没有验证路径
Conciseness	是否用了完成任务所需的最少文字/tokens？	冗余、过度解释、逐字重复用户问题、填充内容

评分尺度

5 — Exceptional: 没有合理改进空间
4 — Good: 只有小问题，没有实质缺口
3 — Adequate: 满足请求，但至少一个维度有明显弱点
2 — Weak: 存在影响可用性或正确性的清晰缺口
1 — Poor: 根本错过请求或包含重大错误

证据规则

每个低于 5 的分数都必须引用具体证据。3 分不能只说 “could be better”——必须说明到底缺什么或错什么。口诀：“展示缺口，不只是命名缺口。”

工作流

Step 1：收集原材料

收集要评估的内容：

- 原始用户请求（从对话中回读）
- 你的最终响应/输出（交付物）
- 任何验证正确性的工具输出（测试结果、exit codes、lint output）
- 任务期间收到的用户反馈（corrections、“try again”、“that's not right”）

Step 2：独立评分每个维度

逐个处理 5 个维度。每个维度：

1. 阅读维度问题
2. 在输出中寻找证据（或缺失证据）
3. 给出 1-5 分
4. 如果分数 < 5，写一句引用缺口的改进说明

不要先在脑中平均总分再倒推各项。每个维度重新独立评分。

Step 3：生成评估报告

使用 templates/evaluation-report.md 中的模板。报告必须包含：

- 一行 summary
- 5-axis scorecard（每轴分数 + 证据）
- Overall score（简单平均，保留 1 位小数）
- 按影响排序的 1-3 条具体改进
- Self-check: "Would the user agree with this assessment?"

Step 4：应用改进

如果任何维度 ≤ 3：

1. 说明你会如何不同地做
2. 如果缺口能在 < 30 秒内修复（缺链接、措辞不清），现在修
3. 如果缺口需要返工，明确标记：“This axis scored [reason] because [evidence]. Re-running with [specific fix] would likely raise it to [score].”

代码示例

示例：良好评估（4+ 分）

Task: Add retry logic to HTTP client

Scorecard:
  Accuracy:    5 — All API calls correct. Verified: retries use
                  exponential backoff. No hallucinated methods.
  Completeness: 4 — Covered happy path + 3 error cases. Missing:
                  timeout handling for hung connections.
  Clarity:      5 — Code comments explain backoff formula.
                  PR description links to incident that motivated this.
  Actionability:5 — Single merge. No follow-up tasks. Tests pass.
  Conciseness:  4 — 47 lines total. The retry loop could be extracted
                  into a helper to drop ~8 lines.

Overall: 4.6 — One gap (timeout handling). Fix before merging.

示例：弱评估（2-3 分）

Task: Add retry logic to HTTP client

Scorecard:
  Accuracy:    2 — Used urllib3 which doesn't match our
                  httpx-based codebase. Wrong library.
  Completeness: 3 — Works for GET. POST/PUT not handled (user
                  said "all HTTP requests").
  Clarity:      4 — Code is readable. Good variable names.
  Actionability:2 — "Add tests" mentioned but no test file created.
                  User has to write tests before merging.
  Conciseness:  3 — 120 lines. The retry config is duplicated in
                  3 places instead of one shared RetryConfig object.

Overall: 2.8 — Wrong library used. Needs httpx rewrite.
  Fix accuracy first (switch to httpx), then extend to all
  HTTP methods, then consolidate config.

反模式

“Everything is a 5”

FAIL: Accuracy:    5 — All good.
   Completeness: 5 — Everything covered.
   Clarity:      5 — Clear.

没有引用证据。这是自我表扬，不是评估。真正的 5 需要证明没有可改进之处。

因 scope creep 过度扣分

FAIL: Completeness: 2 — Didn't handle WebSocket connections or
   gRPC streaming (user didn't ask for these)

只按用户实际要求评估，不按你可以额外构建什么评估。

用评估重新争论

FAIL: "As I said earlier, this approach is wrong. Score: 1"

评估对象是交付输出，不是重新争论已经做出的设计决策。如果方法错了，应在交付前捕捉。

把个人偏好当作客观缺口

FAIL: "Score: 3. I don't like Python decorators."

“Don't like” 不是证据。引用具体可读性、可测试性或正确性问题；否则保持 4+。

最佳实践

• 评估输出，不评估过程。 用户关心你交付了什么，不关心你迭代了几轮。
• 每个弱维度一个改进。 不要为一个维度列 5 件事——挑影响最大的缺口。
• 把改进绑定到用户影响。 “Missing error handling means the user's API call will crash silently” 比 “add error handling” 好。
• 明确什么算 fixed。 “Re-run with httpx transport configured for retries” 比 “fix the library issue” 好。
• 用工具输出作证据。 测试通过就引用；lint 干净就引用。不要猜——grep 找证据。
• 如果找不到缺口，再认真找。 五个维度全满分很少见。问自己：“如果我是用户，这个输出哪里会烦到我？”

相关技能

• agent-eval — 在 benchmark tasks 上比较不同 coding agents
• verification-loop — 按预期结果系统验证输出
• security-review — 安全导向代码审查清单