Harness文件实战测评：AI成功率从20%提升至100%的完整指南
最近，AI编程圈里有个词的热度居高不下：Harness。
甚至，连DeepSeek这样的头部玩家，也开始公开招聘专门的Harness工程师。这不禁让人好奇，它到底是什么，又为何如此重要？
两组数据，一个结论
答案其实很直接：Harness不是某个具体的工具或提示词技巧，而是围绕AI编程智能体搭建的一整套工程基础设施。它由指令、工具、环境、状态、反馈五个子系统构成。
为什么它值得大书特书？因为就在2026年前后，Anthropic和OpenAI几乎同时在各自的工程实验中得出了同一个碘伏性的结论：AI编程智能体频频失败，问题往往不在模型本身，而在于模型之外那套缺失的“缰绳”——也就是Harness。
两家公司都用一组对照实验提供了有力证据。
Anthropic的对照实验
他们使用同一个Claude Opus 4.5模型，挑战同一道编程题。结果令人深思：
- “裸跑”模型：花费9美元，生成的代码完全无法通过测试。
- 搭载Harness的模型：花费200美元，最终成功交付了可用的代码。
多花的这191美元，几乎全部用在了“验证循环”上——每写一段代码就自动运行测试，不通过就立刻修改，如此循环直至真正通过。这笔钱，买的是确定性和可靠性。
OpenAI的百万行实验
OpenAI的Codex团队在真实代码仓库上进行了验证。他们只做了一处微小的改动：在仓库根目录添加了一个名为AGENTS.md的文件，内容不到100行Markdown。
就是这一个小小的文件，将智能体在复杂任务上的成功率，从令人沮丧的20%，直接提升到了可用的80%。
Harness的五个核心子系统
这套基础设施的五个子系统，每一个都旨在解决一种特定的、常见的失败模式。
1. 指令子系统
这就是OpenAI实验中的“魔法文件”。它通常是仓库根目录下的一个Markdown文件（OpenAI系叫AGENTS.md，Anthropic系叫CLAUDE.md）。当Codex、Claude Code或Cursor等智能体启动时，会自动读取并注入其中的内容作为“系统提示词”。
解决什么问题：智能体不了解项目特定约定，导致代码风格混乱、用错包管理器、甚至随手执行破坏性命令。
不到15行的内容，就能把需要反复口头强调的项目规范，变成智能体启动时自动加载的“常识”。
2. 工具子系统
这个子系统明确限定智能体在本次任务中能够调用哪些终端命令或工具。
解决什么问题：防止越权操作。例如，避免智能体执行rm -rf误删文件、使用git push --force覆盖远程仓库，或在禁止联网时调用外部API。
其逻辑清晰直接：允许的命令直接执行，禁止的命令断然拒绝，处于灰色地带的操作则弹出确认提示。
3. 环境子系统
它的目标是锁定项目依赖的版本、运行时配置乃至数据库状态，为智能体创造一个确定性的、可复现的“沙箱”。
解决什么问题：杜绝“在我机器上能跑”的虚假成功。避免代码在本地智能体测试中通过，但一到持续集成（CI）环境就彻底失败。
关键往往在于一行配置，例如在Node.js项目中使用pnpm install --frozen-lockfile，就能确保智能体无法擅自升级任何依赖版本。
4. 状态子系统
智能体通常没有“记忆”。状态子系统通过一个持久化的文件（如PROGRESS.md）来记录跨会话的工作进度、断点和未完成任务。每个新会话的第一件事，就是读取这个文件。
解决什么问题：克服“跨会话失忆”。防止第二个会话从头开始，写出与第一个会话成果相冲突的代码。
通过在AGENTS.md中固化约定：新会话必须首先读取PROGRESS.md；任务完成或断点变化时，必须立即回写更新。
5. 反馈子系统
这是整个Harness工程成败的关键。它定义了一系列机器可执行的验证命令，如运行测试、代码检查、类型检查、构建打包等。智能体在宣布任务完成前，必须成功跑通这些验证，任何一项的退出码不为0，都意味着任务尚未完成。
解决什么问题：根治“过早宣布胜利”。这正是Anthropic那个9美元实验失败的核心原因——智能体感觉“写完了”，但代码一行都跑不通。
它将“完成”的判定权，从智能体的主观感觉，移交给了客观、无情的机器退出码。
三大致命失败模式
Anthropic和OpenAI的实验，不约而同地揭示了AI编程智能体最常见的三种致命失败模式，而Harness正是它们的克星。
失败模式一：过早宣布胜利
典型场景：智能体兴冲冲地输出“已完成！”，提交了500行新功能。结果一合并，CI流水线全线飘红：类型检查报出12个错误，单元测试一个都没通过。
根本原因：缺乏强制性的反馈循环。任务是否完成的判定，来自于智能体的“自我感觉”，而非可验证的事实。
Harness解法：部署反馈子系统。将判定标准与自动化验证命令的退出码绑定，退出码不为0，任务就不算完。
失败模式二：上下文焦虑
典型场景：一个长任务进行到70%，上下文窗口的Token占用快满了。智能体开始感到“压力”，为了在当前会话内结束，它开始走捷径：跳过测试、删除边界情况处理、用存根代码收尾，然后仓促宣布完成。
根本原因：没有断点续传机制。智能体感知到上下文限制时，会倾向于牺牲代码质量来换取会话内的“终结”。
Harness解法：结合状态子系统与主动重启策略。每完成一个子任务就立即回写进度到PROGRESS.md；当上下文使用量超过70%时，主动暂停，保存断点，然后开启一个新会话继续。
失败模式三：跨会话失忆
典型场景：第一个会话编写了用户模块。第二个会话开始编写订单模块时，智能体完全“忘记”了用户模块的存在，又重新实现了一个getUserById函数，导致与之前版本的接口签名冲突。
根本原因：没有持久化状态机制，也没有“新会话先读状态”的强制约定。
Harness解法：组合使用状态子系统和指令子系统。用PROGRESS.md维护已完成功能清单；在AGENTS.md中明确规定，新会话第一指令是读取进度文件；同时确立原则：当进度文件与仓库实际代码冲突时，以代码仓库为唯一事实来源。
五步搭建你的第一个Harness
搭建一套基础的Harness并不复杂，无需复杂框架，用一个文本编辑器，遵循下面五个步骤，总计不超过200行配置就能完成。
- 第一步：在根目录创建AGENTS.md
执行touch AGENTS.md。文件内容至少应包含三个核心部分：项目简要说明、明确禁止的操作、以及“完成”的正式定义。 - 第二步：配置权限文件
根据你使用的智能体（如Claude Code或Codex），编辑对应的配置文件（.claude/settings.json或~/.codex/config.toml）。最关键的是设置两条权限规则：允许执行的安全命令列表，以及需要明确禁止的高风险命令。 - 第三步：编写环境锁定脚本
如果项目已有Dockerfile或devcontainer.json，可跳过此步。否则，编写一个setup.sh脚本，将所有依赖版本明确写死。其中最核心的一行，就是类似pnpm install --frozen-lockfile这样的锁定安装命令。 - 第四步：创建PROGRESS.md
执行touch PROGRESS.md。建议包含“已完成”、“进行中”、“待办”、“已知问题”四个板块。将这个文件提交到Git仓库，将其作为项目本身的一部分进行维护。 - 第五步：在AGENTS.md中固化“完成定义”
这是画龙点睛的一步。在AGENTS.md文件的末尾，明确写出验证任务完成的命令序列，例如：pnpm type-check && pnpm test && pnpm lint && pnpm build。并严格约定：这些命令的退出码必须全部为0，任务才算真正完成。如果项目还没有这些验证命令，那么今天就是创建它们的最好时机。
必须强调的是，缺少了反馈循环，Harness就等于形同虚设。这正是Anthropic那个9美元实验带给我们的核心教训：即使前四步都做对了，唯独缺了第五步的强制验证，一切努力依然会归零。
殊途同归的启示
过去一年，整个行业似乎都在追逐下一个更强大的基础模型。
然而，2026年Anthropic和OpenAI用两组不同的实验，给出了同一个清晰的答案：别急着换模型，先把Harness装好。
一个生动的比喻是：模型能力决定了智能体所能达到的“上限”，而Harness则决定了你在实际工作中，能稳定地用出这个上限的“几成”。
没有Harness，即便是顶级的Claude Opus 4.5生成的代码，可能连编译都无法通过；而配备了完善的Harness，即使模型能力稍逊一筹，也能稳定地交付可用的成果。
当然，下一个更强的模型必然会再次抬升这个上限。但问题在于，如果今天连Harness都没有，那么即使明天更强大的模型到来，你的智能体成功率可能依然会尴尬地停留在20%。
所以，与其等待下一个奇迹般的模型，不如现在就动手，为你的AI编程智能体套上这副可靠的“缰绳”。