一、AI 现在到底差在哪
SWE-Bench 的作者刚放出一组让人后背发凉的数据。
一个新的硬核评测标准 ProgramBench，要求 AI 从零开始完整重建真实的开源软件项目，不允许联网，不看代码相似度，只验证最终行为。
结果是：Claude Opus 4.7、GPT-5.4、Gemini 3.1 Pro，所有一线模型完成率全部 0%。
注意，这不是说 AI 写不出代码。它能写很多代码，能把函数写得很漂亮。
但让它从零搭一个能真正跑起来的真实项目，它就会把所有逻辑塞进一个单体文件，没有模块化、没有架构、没有长期规划，最终通不过行为验证。
这说明什么？
代码生成能力早就不是瓶颈了。卡点在全局架构设计和工程实践。
再看另一组数据。
LangChain 做过一个实验。同一个 gpt-5.2-codex 模型，权重一字没动，只优化模型周围的工程结构。结果 coding agent 在 Terminal-Bench 2.0 上从 52.8 分涨到 66.5 分，排名从 Top 30 开外冲进 Top 5。
OpenAI 公开过一个更夸张的案例。三个人的小团队，五个月时间，驱动 Codex 写出大约 100 万行代码，合并了约 1500 个 PR。这不是 demo，是真正有内部日活用户、有外部 alpha 测试用户的软件产品。OpenAI 团队自己说，他们的工作重心已经从写代码转到了四件事上：设计环境、明确意图、搭反馈回路、让 Agent 自己能看见、能验证、能修复。
把这两组数据放一起看，结论就很清楚了：
裸模型在严肃工程任务上完成率 0%。同一个模型加上一套合适的工程基础设施，能让三人小团队做出生产级软件。
中间那个差距，就是 Harness。
二、Harness 到底是什么
Harness 的直译是马具。
大模型 (Opus 4.7 / gpt 5.5) 就像一匹烈马，如果你无法缰绳控制住它，它跑的再快也没有任何意义。
Harness Engineering 就是如何打造马具，如何通过马具来控制住这匹烈马的技术。
Hooks、Skills、MCP、CLAUDE.md / AGENTS.md、sub-agents、plugins、tools，这些东西你大概都听过或者用过几个。Harness 也可以理解为把它们当成一个系统来设计的统称。
很多人用 AI 的方式是这样的：看到一个新 MCP 觉得好玩就装，看到一个 hook 例子就抄一个，CLAUDE.md 随便写两行就忘了，遇到 bug 也不知道该补哪一块，各种功能无法配合使用，过多的 harness 也会使你的马匹感到疲惫，效果有限。
Harness Engineering 这个词存在的意义就是逼你把这些零散动作当成一个系统来审视。
它给你一份检查清单：你的 AI 工作流在 5 个核心维度上是否完整？保证你的马匹永远处在最佳状态。
业界给出过一个公式：
Agent = Model + Harness
这就是为什么你会觉得有些工具就是更顺手，有些工具模型也很强但用起来像没长脑子。马具不一样而已。
放在 AI 工程的演进脉络里看：
- 最内层是提示词工程，关心怎么给 AI 下指令。
- 中间一层是上下文工程，关心给 AI 什么信息、什么时候给。
- 最外层的 Harness 工程把前两者都包在里面，再加上工具编排、状态持久化、验证循环、任务拆解、子 Agent、权限沙箱、回滚机制，构成一套完整的工程基础设施。
接下来我们用 Harness 的 5 个维度回头看你现在的 Claude Code / Codex / OpenClaw / Cursor 的配置，你就会更好的理解你的 Agent 是需要一些额外的马具还是帮它减减负，轻装上阵。
三、Harness 的 5 个核心维度
把零散的 Harness 概念落到具体工程动作上，可以拆成 5 个维度：
上下文管理、执行能力、任务编排、反馈机制、架构护栏
3.1 上下文管理：三层记忆架构
AI 在多轮对话里忘掉项目规则，根源在上下文窗口的工作方式。每一轮模型看到的内容是一个扁平的消息列表，你过去说过的每句话和当前问题混在一起，没有项目规范和普通聊天的层级区分。对话越长，前面定的约束被稀释得越厉害。
OpenAI 在 Codex 工程文章里有一句话点破了这层：从 Agent 的角度看，运行时拿不到的知识就等于不存在。你嘴上说的、Slack 里讨论的、团队心里默认的规则，如果没有以文件形式存在于仓库里，AI 一概看不见。
Harness 在这一层的核心做法是把规则文件化、结构化。生产实践分三层。
第一层是项目根目录的 AGENTS.md 或 CLAUDE.md，相当于项目的地图。每次新对话都被加载到上下文头部。内容包括技术栈、目录结构、禁止事项、提交前必须跑的命令、UI 风格禁区。控制在 100 行左右。
第二层是 docs 目录下按主题拆分的详细规则文件，比如 frontend.md、security.md、api-design.md。AI 在 AGENTS.md 里看到指引后按需读取，不一次性塞进上下文。
第三层是 Claude Code 这类工具内置的记忆机制：每条约 150 字符的轻量级索引始终加载、详细文件按需拉取、原始记录仅通过 grep 等搜索访问。这套设计在 AI 能看见全貌和上下文不被塞爆之间找到了平衡。
OpenAI 在文章里承认踩过一个坑。他们最初把所有规则塞进一个几千行的大 AGENTS.md，结果 AI 反而更容易忽略关键信息。后来改成地图加详细文档两层结构才修好。
核心原则：分层持久化上下文，避免上下文空间占用过大影响模型注意力。
3.2 执行能力：让模型拥有手脚
模型本身只能输出文本。它能告诉你在终端运行 npm install，但没法自己跑命令、没法看运行结果、没法根据报错调整下一步。这种纯输出能力让 AI 没办法闭环工作，每一步都需要人当传话筒。
Harness 在这一层的工作是把模型接入真实操作环境。从基础到进阶有三层。
基础层是终端加文件系统加浏览器。终端让 AI 跑命令、装依赖、执行测试、查日志。文件系统让它读代码、改文件、写中间文档。浏览器让它看真实页面、点按钮、截图验证。
进阶层是 MCP。MCP 是一个让 AI 接入外部能力的标准协议，常见的接入对象包括数据库、搜索引擎、爬虫、设计工具、监控系统。
更高层是 Skills。Skills 把多步骤工作流封装成可复用的能力包，比如写一篇技术推文、生成一份周报、从某网站抓取竞品数据。AI 遇到对应需求时直接调用整个 Skill，不需要每次重新设计步骤。
但工具层不能无限堆。Vercel 在做内部 text-to-SQL Agent 时踩过一个反例。他们最初造了一堆专用工具：schema lookup、query validation、error recovery。做下来成功率 80%。后来删掉了 80% 的专用工具，只让 Claude 用 grep、cat、find、ls 这些 Unix 基础工具自己读文件再写 SQL。成功率涨到 100%，速度快 3.5 倍，token 省 37%。
原因是工具越多，模型在每一步的选择空间越大，选错工具、走错路径的概率也越大。
核心原则：合理选择你的每一个工具，多不如精。
3.3 任务编排：让 AI 能够执行长任务
AI 在长任务上最典型的失败模式是想 one-shot 一个完整功能。模型上下文窗口有限，让它一次吃下"带搜索、过滤、分页的列表页"这种规模的需求，相当于让一个工程师不写设计文档、不拆任务、不分迭代、闷头干到底。失败是必然。
Anthropic 在长任务 Harness 那篇文章里详细描述过这个失败模式：模型尝试一次性写完，结果上下文用完，做到一半发现前面方案不对，又回头改前面的代码，越改越乱。
Harness 在这一层做的是把长任务结构化。
第一步是 Plan Mode。AI 先输出任务方案（拆成哪几个子任务、每个子任务怎么实现），人工确认后再动手。这一步是刹车，把方向走偏的成本提前到方案阶段消化掉。
第二步是步进执行。每次只做一个子任务，做完一个验证一个。这避免了做着做着上下文塞满的崩溃。
第三步是状态外置。每完成一个功能就让 AI 沉淀一份文档，一般叫 progress.md 或 plan.md。这份文档要详细写：当前完成了哪些功能、用了什么技术方案、做了哪些关键架构决策、有哪些未解决的 bug、还有什么待做事项。这份文档是跨上下文窗口的外置记忆。下一轮新对话开始时 AI 读它就能立刻进入状态。
第四步是并行。互不依赖的子任务用 sub-agents 同时跑。
Anthropic 在长任务工程里给了一个更进阶的方案叫 Ralph Loop，本质是两段式接力。
第一段叫 Initializer Agent，只在项目最开始跑一次。它的任务是搭好开发环境、把整个需求拆成功能列表、写第一份 progress.md、做首次 git commit。
第二段叫 Coding Agent，每个新对话窗口都跑这一段。它的固定动作是：先读 git log 看历史提交，再读 progress.md 看进度，知道前一轮做到哪儿了；从未完成功能列表里挑当前优先级最高的一项做掉；做完之后提交 git，更新 progress.md，写清楚这一轮完成了什么、下一轮该做什么。
哪怕中途 AI 断了、模型版本换了、对话窗口塞满了，下一轮只要读 git log 和 progress.md 就能立刻进入状态。
**核心原则：progress.md 和 git commit 是 AI 的存档点，存了档才能放心做长任务。
3.4 反馈机制：AI 测试驱动开发
模型不会跑代码。它读代码字面，根据看起来像不像能跑通来做判断。如果一段代码符合常见模式、变量名对得上、缩进整齐，它就判为通过。但代码能不能跑跟它看起来像不像无关，这件事只有真跑一遍才能确认。这就是为什么 AI 经常自信地说"已经修好了"，但你打开项目还是一堆错。
Harness 在这一层的工作是把验证从人工搬到自动。三类反馈：
规则反馈：让 AI 在每次提交前自动跑 linter、typecheck、单测、集成测试。任何一项失败都不算完成。
视觉反馈：UI 类任务让 AI 用 Playwright 之类的工具自己打开浏览器，按用户路径点一遍，截图作为完成证据。
LLM 评审反馈：让另一个 AI 单独评审刚写完的代码，找逻辑漏洞、找架构问题、找潜在 bug。
Anthropic 在工程博客里给过一个具体数字：给模型一个能验证自己工作的回路，产出质量能提升 2 到 3 倍。这是单个最确定的 Harness 投资。
这里有一个反直觉的设计要点。让生成代码的 AI 自己评审自己，效果会比想象中差很多，因为生成者天然偏向替自己找理由。Anthropic 的经验是把 generator 和 evaluator 分成两个独立的 Agent，让它们用不同的角色配置和不同的提示词。互审才能真正发现问题。这跟传统软件开发里"自己写的代码不能自己 review"是同一个道理。
核心原则：AI 嘴巴说修好没有用，跑通测试才算完成。
3.5 架构护栏：在提交前拦住 AI 的烂代码
AI 写代码有一个隐性问题：它会模仿仓库里已有的模式。好代码会被模仿，烂代码也会被模仿。而且每一次单看 AI 的提交都看起来合理，叠加起来却是项目越改越烂。
OpenAI 在 Codex 文章里专门提到这个现象：Agent 会复制仓库里已有模式，如果已有模式不稳定、不一致、有坏的代码风格，AI 会把它放大。
Harness 在这一层的工作是把架构规则从文档搬到可执行的代码里，让坏代码在进入主干之前被自动拦住。
最基础的层是 pre-commit hooks。在 git 提交前自动跑一批检查脚本，不合规的提交直接被拦下。
第二层是架构 linter。专门检查架构层面的违规，比如 UI 层不能直接访问数据库层、模块依赖必须单向、文件大小超阈值要拆。这跟 3.4 的语法 linter 不一样，3.4 查语法错误，这里查架构错误。
第三层是 CI gate 兜底。即使本地 hooks 被绕过，CI 上也会再跑一遍检查，确保主干分支永远满足架构约束。
OpenAI 还有一个更激进的做法叫"垃圾回收"：定期跑后台 Codex 任务扫描整个代码库，发现偏离架构原则的地方就自动开小 PR 偿还技术债。逻辑是 AI 写代码越快，技术债产生得越快，所以清债也必须自动化。
核心原则：提前考虑到 AI 的局限，设置好护栏。
四、看顶级团队怎么搭 Harness
4.1 Anthropic / Claude Code：教科书级的长任务工程
Claude Code 是 Anthropic 自己用来驱动 Claude 的 agent harness。它把 Harness 拆成 12 个独立组件，但这里不展开列，只挑两个最值得借鉴的设计讲清楚。
设计一：三层记忆架构
Claude Code 的记忆系统有三层。
最上层是轻量级索引，每条约 150 字符，始终被加载到上下文里。它的作用是让 AI 永远知道这个项目里有什么文件、有什么模块、有什么核心约定。但因为每条很短，几十上百条也塞不爆上下文窗口。
中层是详细文件，比如 README.md、ARCHITECTURE.md、API 文档、各模块的设计说明。这些文件不会默认加载。AI 在轻量级索引里看到某条提到"详见 docs/architecture.md"，需要的时候才主动去读这个文件。读完该信息进入上下文，不再用时也可以被压缩出去。
底层是原始记录，比如完整的 git log、完整的对话历史、完整的日志文件。这一层不会被自动加载，AI 只能通过 grep、tail 这些命令主动检索。数据量最大，但完全不污染上下文。
这三层的核心思想是：上下文是稀缺资源，必须按"读到的频率"和"重要性"分层。永远要看的放最上面，偶尔要查的放中间，可能用得到的放最下面。
设计二：Ralph Loop 跨上下文长任务
针对那种做完要几天、要跨多次对话窗口的长任务，Anthropic 设计了一种工作流叫 Ralph Loop。本质是两段式接力。
第一段叫 Initializer Agent，只在项目最开始跑一次。它做四件事：搭好开发环境、把整个需求拆成功能列表、写第一份 progress.md 记录待做事项、做首次 git commit。
第二段叫 Coding Agent，每个新对话窗口都跑这一段。它的固定流程是：
- 先读 git log，看历史提交记录
- 再读 progress.md，看当前进度和未完成列表
- 从未完成列表里挑当前优先级最高的一项
- 完成这一项，跑验证，提交 git
- 更新 progress.md，写清楚这一轮做了什么、下一轮该做什么
哪怕中途 AI 断了、模型版本换了、对话窗口塞满了，下一轮的 AI 只要读 git log 和 progress.md 就能立刻进入状态。这套设计的关键不在 AI 多聪明，在 progress.md 和 git 历史共同构成了一个跨上下文的外置记忆。
你能从这套设计里学到的：
- 自己的项目至少要有一份 progress.md，写清楚当前完成了什么、有哪些关键架构决策、有什么未解决的 bug、下一步要做什么。不要只把这些东西留在脑子里。
- 把每个功能的完成作为一次 git commit。git 历史本身就是 AI 可读的工作记录。
- 上下文要分层。AI 永远要看见的写进 AGENTS.md，可能查得到的放进 docs，剩下的交给搜索。
4.2 OpenAI / Codex：面向 AI 重构开发环境
OpenAI Codex 团队用 5 个月、3 个人驱动 AI 写了 100 万行代码的那个案例背后，最关键的不是模型多强，是他们提出的一个工程理念叫 Codex legibility。
Codex legibility 翻译成中文大致是"对 Codex 可读"。它的意思是未来的代码库不只要给人读，也要给 Agent 读。这意味着原来只给人类工程师用的所有开发基础设施（日志、监控、调试工具、本地环境），都需要被改造成 AI 能直接使用的形式。
OpenAI 的具体做法有 5 项。
1. 每个 git worktree 自动启动独立应用实例。 Codex 在做一个改动时，可以让对应分支自动起一个独立的开发服务器。AI 可以自己打开这个实例、操作它、看响应、验证改动到底有没有按预期生效。原来要工程师手动 npm run dev 看效果，现在 AI 自己做。
2. Chrome DevTools Protocol 接入 Agent runtime。 这让 AI 在浏览器层面拥有和工程师一样的调试能力：看 DOM 结构、监听网络请求、注入 JS、截图。复现一个 UI bug 不再需要工程师亲自打开浏览器，AI 自己就能复现并定位。
3. 日志、指标、trace 暴露给 AI 查询。 OpenAI 让 Codex 能直接用 LogQL、PromQL、TraceQL 这些查询语言访问生产监控数据。这意味着 AI 在排查问题时不需要工程师把日志手动贴给它，自己就能 grep 日志、看 metric 异常、追 trace。
4. Custom linter 把架构约束写成可执行规则。 OpenAI 把哪些层不能调用哪些层、哪些命名必须统一、哪些模式是禁止的，全部写成自动检查的 linter 规则。AI 写出的代码只要违反就被拦住。
5. 后台垃圾回收任务。 这是最有意思的一项。OpenAI 让后台定期跑一批 Codex 任务，扫描整个代码库找偏离架构原则的地方，自动开小 PR 来修。也就是说，技术债的偿还也被自动化了，不再依赖工程师手动重构。
这 5 项加在一起，核心是把整个开发环境改造成 AI 可读、可操作、可验证的工作台。
你能从这套设计里学到的：
- 如果你项目的日志连人都看不懂，AI 就更看不懂。重构日志为结构化格式（JSON、固定 schema）是 AI 友好化的第一步。
- 把脑子里、Slack 里、code review 评论里的架构原则都搬到 linter 规则里。这件事的真正价值不只在防止违规，更在于它让架构变成可学习的对象，AI 看了 linter 的报错信息就能学会怎么写合规代码。
- 系统设计阶段问自己一个问题：AI 能看见这个状态吗？如果不能，看怎么把它暴露出来。
4.3 Nous Research / Superpowers：开源可复用的 Skills 框架
Superpowers 是 Nous Research 开源的 Agent Skills 框架。如果说 Claude Code 是 Anthropic 内部的工程实践、Codex 是 OpenAI 重构开发环境的样板，那 Superpowers 是个人开发者可以直接抄回家用的开源版本。
它内置了几个常用工作流。
TDD workflow：让 AI 先写测试再写实现。测试通过才算完成。这套流程把 3.4 的反馈机制做到了默认开启，AI 必须经过测试才能交付。
两阶段 Code Review：第一阶段让 generator agent 写代码，第二阶段让 reviewer agent 评审。两个 agent 用不同的角色配置和提示词，强制做到 generator 和 evaluator 分离。
Sub-agent 协作模板：内置了任务拆解、并行执行、结果汇总的标准流程，开箱即用。
Superpowers 的姐妹项目 Hermes Agent 还有一个更前沿的方向叫 Self-Evolution。这套系统用 DSPy 和 GEPA 两个工具持续优化 Harness 本身。简单理解，DSPy 把 prompts 和工具描述当成可优化的参数，GEPA 用类似遗传算法的方式从执行记录里成功失败的轨迹中找出更好的配置。整个过程不重新训练模型，只调 Harness。也就是说 Harness 可以从自己过去做过的任务里自动变好。
你能从这套设计里学到的：
- 不想从零设计 TDD workflow 和两阶段 review，直接抄 Superpowers 的模板就能起步。
- 把做得最多的几类任务（比如写一篇博客、分析一份数据）封装成 Skill，下次 AI 自己调用，不用每次重新教它流程。
- 关注 DSPy / GEPA 这条技术线。模型变强是大势，但 Harness 自动变好可能是更接近你工作场景的进步路径。
五、三个反直觉的 Harness 原则
讲完顶级团队的具体做法，下面把这个领域几个最容易踩坑的原则单独拎出来。
原则一：Harness 不是越多越好
直觉上工具越多 AI 越强。实际上工具越多，模型在每一步的选择空间越大，选错工具、走错路径、调用不该调用的接口的概率也越大。
Vercel 在内部 text-to-SQL Agent 上做过最直接的验证。他们最初为这个 Agent 配了一整套专用工具：schema lookup、query validation、error recovery，做下来成功率 80%。后来删掉 80% 的专用工具，只让 Claude 用 grep、cat、find、ls 这些 Unix 基础工具自己读 schema 文件再写 SQL，成功率涨到 100%，速度快 3.5 倍，token 省 37%。
Manus 也观察到同样规律：一个 heavily armed agent 会变笨。
实操层面的判断标准很简单：每接一个工具之前问自己，它解决的具体行为缺口是什么。答不上来就先不接。
原则二：上下文怎么组织比上下文有多大重要得多
很多人看到 Claude 4 Opus 有百万 token 上下文窗口的第一反应是"那就全塞进去"。这是个昂贵的误解。
Chroma 研究院做过一项 Context Rot 研究，测试了 18 个主流模型在长上下文下的表现。结论是：随着输入长度增长，模型使用上下文的能力会变得越来越不可靠。即使任务难度不变，单纯把上下文从 1 万 token 加到 50 万 token，性能也会显著下降。
斯坦福那篇著名的 Lost in the Middle 论文证明了另一个现象：模型对上下文头部和尾部的信息使用得最好，对中间位置的信息容易忽略。这意味着关键信息放在上下文的什么位置，直接影响 AI 用不用得到它。
Manus 团队还从经济学角度补了一刀。在他们的典型 Agent 任务里，输入 token 和输出 token 比例约 100:1。Agent 大部分时间和成本花在反复把上下文喂给模型，而 KV-cache 命中和未命中的价格差 10 倍。同一个任务，上下文组织得让缓存能复用，每月 API 账单能差一个数量级。
这三件事加起来意味着，上下文设计是真正的工程问题，不是把所有信息扔进去让模型自己挑那么简单。
原则三：Harness 应该随着模型的进化不断精简
每一个 Harness 组件背后都有一个隐含假设：模型自己做不到这件事，所以需要外部补丁。但模型在快速进步，旧的补丁可能已经过期。
Anthropic 在 Harness Design 那篇博客里讲过一个具体例子。他们在早期版本的 Claude Code 里加了一个显式的"规划"步骤，强制 AI 在动手前先输出计划。后来某个新版本的 Claude 发布之后，Anthropic 发现规划能力已经被模型内化，外置的规划步骤反而变成了冗余开销，于是直接删掉。
实操层面的判断方法是：每次模型版本升级之后，回头审视一下你的 Harness。哪些组件还在真正补能力？哪些只是历史包袱？哪些校验已经可以交给模型？
好的 Harness 是在模型能力边界外保持刚刚够用的厚度。
结语：Harness Engineering 变成了核心能力
所有大模型的 ProgramBench 全员 0% 这个结果反过来说明了一件事：Harness Engineering 越来越重要。
以现在 AI 能帮你写掉相当大一部分代码，但 AI 不会替你做需求分析、不会替你拆任务、不会替你设计上下文架构、不会替你判断哪个工具该接哪个该删、不会替你建立验证标准、不会替你守住架构边界。
这些事情的总和就是 Harness Engineering。
它听起来像一个新名词，本质上是把传统软件工程里的方法学系统化地迁移到 AI 工作流上：
- AGENTS.md 对应需求文档和设计文档；
- 任务编排对应敏捷开发的迭代拆分；
- 反馈机制对应单元测试和 code review；
- 架构护栏对应代码规范和安全问题检查。
这些东西本来就是优秀工程师的基本功。
下次你的 Agent 又把事搞砸了，可以回头看一遍你的 Harness 在 5 个维度上分别处于什么状态。
绝大多数情况下，AI 已经足够聪明，缺少的是能够好好操控它的缰绳。
评论