评估 AI Coding Agent 不是跑几个 benchmark 出分数，而是建立一套"可重复、可对比、可改进"的反馈系统。
用 Claude Code 一段时间后，每个人都会遇到这些问题：
- "它这次改对了，下次同样的任务为什么错了？"
- "我换了一个 prompt，效果变好了还是变差了？"
- "团队里每个人用法不一样，怎么知道谁的方法更稳？"
- "这个 Agent 适不适合我们的代码库？"
没有评估，这些问题只能靠感觉。而感觉是不可靠的、不可迁移的、不可规模化的。
评估的价值不是打分，而是：
- 建立基线：当前 Agent 在我这个场景下是什么水平。
- 定位问题：失败是因为 prompt、RAG、工具、模型，还是任务本身？
- 验证改进：我改了一个配置，真的变好了吗？
- 团队共识：让"好不好用"有共同语言。
我们把 AI Coding Agent 的评估拆成三层：
┌─────────────────────────────────────┐
│ Agent Eval │ 端到端任务：能不能独立完成？
│ （任务完成度、效率、安全性） │
├─────────────────────────────────────┤
│ RAG Eval │ 上下文质量：读到的内容对不对？
│ （检索准确率、答案忠实度） │
├─────────────────────────────────────┤
│ Prompt Eval │ 提示词质量：输入输出是否稳定？
│ （指令遵循、鲁棒性、可迁移性） │
└─────────────────────────────────────┘
目标：验证提示词（系统提示、project instructions、SKILL.md、单次用户输入）是否稳定、可迁移、抗干扰。
核心问题：
- Agent 是否遵循了明确的指令？
- 同一个 prompt 多次运行，输出差异有多大？
- 把 prompt 换到另一个模型上，效果是否一致？
- 用户输入有歧义或恶意时，prompt 是否还能保持行为？
常见失败模式：
| 失败 | 表现 | 例子 |
|---|---|---|
| 指令遗漏 | 忽略 prompt 中的约束 | prompt 说"不要修改文件"，结果改了 |
| 格式不稳定 | 输出格式时好时坏 | 有时返回 JSON，有时返回 Markdown |
| 模型敏感 | 换模型后行为巨变 | Claude 4 能做的事，3.5 完全跑偏 |
| 输入污染 | 被用户输入带偏 | 用户说"忽略前面的指令"，Agent 真忽略了 |
目标：验证 Agent 在代码库中检索到的上下文是否相关、完整、不产生幻觉。
核心问题：
- 给定一个查询，检索到的文件/片段是否包含答案？
- 排名靠前的结果是否更相关？
- 生成的回答是否基于检索内容，而不是模型记忆？
- 跨文件调用、类型依赖、版本差异是否被正确处理？
代码库 RAG 的特殊性：
- 代码是结构化的，不只是文本。
- 一个函数的定义和调用可能分散在多个文件。
- 同样的函数名在不同模块里含义不同。
- 需要结合 AST、import 图、git 历史，不只是向量相似度。
目标：验证 Agent 能否在给定真实任务下，自主完成目标。
核心问题：
- 任务是否完成？（功能正确性）
- 花了多少步？多少 token？（效率）
- 有没有破坏现有功能？（安全性）
- 失败时能否自我修复？（鲁棒性）
任务分类：
| 类型 | 例子 | 成功标准 |
|---|---|---|
| 功能实现 | "加一个用户登录接口" | 测试通过、接口可用 |
| Bug 修复 | "修复 #123 的崩溃" | 复现失败、回归通过 |
| 代码审查 | "审查这个 PR" | 找到真正的问题、不误报 |
| 重构 | "把回调改成 async/await" | 行为不变、测试通过 |
| 理解查询 | "这个项目怎么启动？" | 回答准确、引用正确 |
推荐按以下步骤设计一次评测：
不要问"这个 Agent 好不好"，要问"这个 Agent 在 X 场景下做 Y 任务，Z 指标如何"。
好的目标：
评估 Claude Code 在我们 Django 项目中修复单文件 bug 的成功率。
不好的目标：
评估 Claude Code 强不强。
如果任务经常失败但不知道原因，从 Agent Eval 开始。
如果 Agent 行为不稳定，从 Prompt Eval 开始。
如果 Agent 读错文件、引用错代码，从 RAG Eval 开始。
每个评测任务需要：
- 输入：用户指令、初始代码库状态
- 期望输出：测试通过、文件变更、返回结果
- 判断标准：自动判断规则 + 人工复核说明
数据集不是越多越好，而是要有代表性、可复现、有区分度。
不同目标用不同指标：
| 目标 | 推荐指标 |
|---|---|
| 功能正确性 | Pass@K、成功率 |
| 效率 | 平均步数、平均 token 数、耗时 |
| 安全性 | 回归测试通过率、误删/误改率 |
| 稳定性 | 同任务多次运行的标准差 |
| 上下文质量 | Recall@K、MRR、幻觉率 |
不要只看分数。每个失败案例都要问：
- 是 prompt 导致的吗？
- 是 RAG 检索漏了关键文件吗？
- 是工具调用顺序错误吗？
- 是模型能力不够吗？
- 是任务本身描述不清吗？
评估的最终目的是改进。每次评测后应该产出：
- 改进建议清单
- 需要调整的 prompt / 配置 / 工具
- 下一轮评测计划
SWE-bench 很好，但它测的是"能不能修 GitHub issue"，不是"能不能在我的代码库里按我的规范工作"。
一个 Agent 80% 成功率，另一个 75%，不一定前者更好。要看失败案例的类型和严重性。
如果 Agent 用到了和评测任务相似的公开代码，分数会虚高。
一个 Agent 成功率 90% 但平均消耗 100 万 token，另一个 85% 但只用 10 万 token，在不同场景下选择会不同。
自动指标会漏掉"看起来对但实际有问题"的情况。至少抽 10% 案例人工复核。
如果你只想快速开始，最小评测只需要：
- 5-10 个有代表性的任务
- 一个明确的通过标准（如"测试通过"）
- 一个运行脚本
- 一个记录结果的表格
不要等"评测系统很完善"才开始。先用最简单的方式跑起来，再逐步完善。
- frameworks/agent-eval/：Agent Eval 的具体框架
- frameworks/prompt-eval/：Prompt Eval 的具体框架
- frameworks/rag-eval/：RAG Eval 的具体框架
- benchmarks/：具体场景的评测设计
- datasets/schema.md：统一数据格式
- workflows/：可落地的工作流