第 1 章 · 为什么强模型仍会失败
本章目标：理解为什么 SWE-bench 上 50-60% 的通过率在真实任务中继续下滑，掌握 Harness Engineering 的核心定义和五大失败模式。
1.1 benchmark 与现实之间的鸿沟
2025 年末，SWE-bench Verified 上最强的编码智能体平均通过率达到 50-60%。初看这个数字似乎不错——但请不要过早庆祝。这些任务经过精心挑选，Issue 描述清晰，测试用例现成。把任务换成你每天面对的真实需求：模糊的规格、没有测试、业务规则散落在代码库各处。真实任务的通过率会进一步下滑。
你满怀信心地交付一个任务，智能体运行 20 分钟后告诉你"完成了"，但你看到代码：功能加上了，测试却挂了；Bug 修了，新的问题又出现；更糟糕的是，它实现的根本不是你想要的。
这时大多数人的第一反应是"模型不够好，换更贵的试试"。但在掏钱之前，请考虑：问题可能根本不是模型。
1.2 Anthropic 的对照实验
Anthropic 做了一个控制实验，完美说明这一点。同样的提示词（"构建一个 2D 复古游戏编辑器"），同一个模型（Opus 4.5），两次运行。
第一次运行：裸跑，没有任何支持。20 分钟，$9，游戏核心功能根本无法工作。 第二次运行：完整 Harness——planner + generator + evaluator 三智能体架构。6 小时，$200，游戏完全可玩。
模型没变。Opus 4.5 还是那个 Opus 4.5。变的是 harness。
OpenAI 的 Harness Engineering 文章说得更直接：在一个配置良好的仓库中，Codex 可以从"不可靠"直接跃升到"可靠"。注意措辞——不是"好一点"，而是定性飞跃。这里的 Harness 指的是模型权重之外的一切工程基础设施。
1.3 五大失败模式
智能体的具体失败模式可以归结为五类：
1.3.1 模糊需求——智能体只能猜测
"加一个搜索功能"——这句话几乎什么都没说。搜索什么？全文检索还是结构化查询？结果要分页吗？要高亮吗？你没说清楚，智能体只能猜。猜对了是运气，猜错了意味着返工，成本可能是当初说清楚的数倍。
1.3.2 隐性规范未写入——智能体无从遵循
你们团队都用 SQLAlchemy 2.0 语法，但智能体默认写 1.x 代码。所有 API 端点必须经过 OAuth 2.0 认证，但这条规则只存在于你的大脑和三个月前的一条 Slack 消息里。智能体不是不想遵守，它根本没见过这条规则。
1.3.3 环境不完整——智能体在修环境而不是干活
开发环境不完整、依赖缺失、工具版本错误——智能体宝贵的上下文窗口消耗在 pip install 报错和 Node 版本冲突上，而不是做你交给它的实际工作。
1.3.4 没有验证手段——智能体"感觉完成了"就宣布结束
没有测试，没有 lint，或者验证命令从未告诉智能体。智能体写完代码，看一眼，觉得还行，就宣布完成。Anthropic 还观察到一个有趣的现象：当智能体感觉到上下文即将耗尽时，会表现出"仓促收尾"行为——匆忙结束当前工作、跳过验证步骤、选择简单方案而非最优方案。Anthropic 称之为上下文焦虑（context anxiety）。
1.3.5 跨会话状态丢失——每次新会话从零开始
上一次会话的所有发现都丢失了。每次新会话都要重新探索项目结构、重新理解代码组织。没有持久化状态的智能体在超过 30 分钟的任务上失败率急剧上升。
1.4 核心概念
| 术语 | 含义 |
|---|---|
| 能力鸿沟 (Capability Gap) | 模型在 benchmark 上的表现与真实任务表现之间的巨大差距。SWE-bench 50-60% 的通过率意味着近一半真实问题未被解决 |
| Harness | 模型权重之外的一切：指令、工具、环境、状态管理、验证反馈。Anthropic 将 Claude Agent SDK 直接称为"通用智能体 harness" |
| Harness 诱发失败 | 模型能力足够，但执行环境存在结构性缺陷。Anthropic 的对照实验已证明这一点 |
| 验证差距 (Verification Gap) | 智能体对自己输出的信心与实际正确性之间的差距。这是最常见的失败模式 |
| 诊断循环 (Diagnostic Loop) | 执行 → 观察失败 → 归因到特定 harness 层 → 修复该层 → 重新执行 |
| 完成定义 (Definition of Done) | 可用命令验证的一组条件——测试通过、lint 干净、类型检查通过 |
1.5 失败时，先修 Harness
只有一个核心原则：失败时，不要先换模型——先检查 harness。 如果同一个模型在结构良好的类似任务上能成功，就假设是 harness 问题。
实践中这意味着什么？把每次失败归因到具体层次。不要只说"模型不够好"。问自己：任务不清晰？上下文不足？没有验证手段？映射到五个防御层——任务规格、上下文提供、执行环境、验证反馈、状态管理。
然后，为每个任务写一个明确的完成定义：
完成标准：
- 新端点 GET /api/search?q=xxx
- 支持分页，默认 20 条
- 结果包含高亮片段
- 所有新代码通过 pytest
- 类型检查通过 (mypy --strict)在仓库根目录放置一个 AGENTS.md 文件，告诉智能体项目的技术栈、架构规范和验证命令。这是 harness 工程的第一步，也是 ROI 最高的一步。一份 AGENTS.md 可能比升级更贵的模型更有效——这不是玩笑。
1.6 本章小结
- 强模型 ≠ 可靠执行；SWE-bench 50-60% 是精心挑选的任务，真实任务通过率更低
- Anthropic 对照实验：同模型同提示，有 harness vs 无 harness 结果天差地别
- 五大失败模式：模糊需求、隐性规范、环境不完整、无验证手段、跨会话状态丢失
- 核心原则：失败时先修 harness，不要先换模型
- 每个任务写明确的 Definition of Done，放置 AGENTS.md
🧪 随堂测验
点击你认为正确的选项。答错时会展示正确答案与原因解析。
1. 根据 Anthropic 的对照实验，同模型同提示下，完整 harness 相比裸跑的主要优势是什么？
2. "上下文焦虑" (context anxiety) 指的是什么现象？
3. 以下哪项不是 OpenAI 提出的 Harness 核心工作？
4. Definition of Done 的核心特征是什么？
🛠️ 动手实践
- 找一个你参与过的项目，列出其中"智能体无法看到的隐性规范"——那些只存在于口头、Slack 或 senior 工程师头脑中的规则。
- 为这个项目写一个最小化的 AGENTS.md（100 行以内），包含技术栈、目录结构、验证命令。
- 尝试用
/goal命令让 Claude Code 或 Codex 完成一个小任务，观察它在没有 AGENTS.md 时的表现。