代理自我评估
在完成一项复杂任务后，代理暂停下来，根据一个结构化的5轴标准对自己的输出进行评分。这不是一个通过/失败的门槛——它是一个有意的反思步骤，用以在用户介入之前发现遗漏、标记过度自信、并指出需要改进的领域。
何时激活
- 在编写跨越3个以上文件或超过50行代码后
- 在完成一个多步骤工作流（实现 → 测试 → 审查）后
- 在涉及3次以上尝试的调试会话后
- 在产出一份设计文档、架构决策或书面分析后
- 当用户问“刚才那个做得好吗？”或“给自己打个分”时
- 在任何会话结束的
Stop钩子中（如果配置了——请参阅references/hook-integration.md）
核心概念
5个评估轴
| 轴 | 问题 | 它捕捉什么 |
|---|---|---|
| 准确性 | 事实、声明和输出是否正确？ | 幻觉、错误的API名称、不正确的语法、虚假陈述 |
| 完整性 | 是否涵盖了用户要求的所有内容？ | 遗漏的边界情况、未处理的错误路径、遗忘的需求、跳过的子任务 |
| 清晰度 | 解释是否易于理解且结构良好？ | 令人困惑的解释、未定义的术语、缺少上下文、冗长 |
| 可操作性 | 用户能否立即根据输出采取行动？ | 模糊的建议、缺少步骤、“你应该做X”但不展示如何做、没有验证路径 |
| 简洁性 | 是否使用了最少的词语/令牌？ | 冗余、过度解释、逐字重复用户的问题、填充内容 |
评分标准
5 — 卓越：没有合理的改进空间
4 — 良好：只有微小的吹毛求疵，没有实质性差距
3 — 合格：满足要求，但至少在某一轴上有一个显著的弱点
2 — 薄弱：存在一个明显的差距，影响了可用性或正确性
1 — 差：从根本上未能满足要求，或包含重大错误
证据规则
任何低于5的分数都必须引用具体的证据。一个3分不能仅仅说“可以做得更好”——它必须确切地说出缺少什么或什么错了。核心口诀：“展示差距，不要只是命名它。”
工作流程
步骤1：收集原始材料
收集你将评估的内容：
- 原始用户请求（从对话中重新读取）
- 你的最终响应/输出（交付物）
- 验证正确性的任何工具输出（测试结果、退出码、lint输出）
- 在任务期间收到的任何用户反馈（更正、“重试”、“那不对”）
步骤2：独立评分每个轴
一次一个地完成5个轴的评估。对于每个轴：
- 阅读该轴的问题
- 在输出中找到证据（或证据的缺失）
- 分配1-5的分数
- 如果分数 < 5，写一句引用差距的改进说明
不要先在脑子里平均分数，然后再反推。对每个轴进行新的评分。
步骤3：生成评估报告
使用 templates/evaluation-report.md 中的模板。报告必须包含：
- 一句话总结
- 5轴评分卡（每个轴的分数 + 证据）
- 总体评分（简单平均值，四舍五入到一位小数）
- 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— 安全重点的代码审查清单