Harness Engineering：让 AI Agent 从“玩具“到“生产力“的工程革命

Harness Engineering：让 AI Agent 从"玩具"到"生产力"的工程革命

三个工程师，五个月，100 万行生产级代码------其中没有一行是手写的。

2026年2月，OpenAI Codex 团队用一组令人沉默的数据引爆了一个全新的技术概念：Harness Engineering。但真正值得思考的，不是这组数字本身，而是它揭示的一个根本性问题：为什么同样的模型，在不同团队手中会产生天壤之别的产出？

一 AI 智能体的能力鸿沟

• Claude Code、OpenAI Codex 或 OpenClaw独立完成一个完整功能的开发、测试、集成。大概率半途而废，或者产出一堆不可维护的代码。

🤔 思考题： 为什么同一个模型，在"解释 RAG 是什么"和"从零搭建一个带鉴权的 REST API"之间，能力差距如此之大？

• 这不是 Agent 的模型能力问题------OpenAI 那三个人用的是市面上人人都能用的模型，Stripe 用同样的 Claude 每周自动完成 1,300 多个 Pull Request。区别在于：他们会设计 Agent 工作的环境。

• 核心结论： 同一个 AI 模型，在简单任务上轻松搞定，在复杂系统任务上却似是非非。区别不在于模型能力，而在于使用方式。

二 三个时代：学会"用好智能体"的演进之路

• Harness Engineering 并不是突然从天而降的新概念------它经历了三个阶段自然演进，每一层都包含前一层（而非替代）：

2.1 2024年 · Prompt Engineering（提示工程）

• 提示词工程：在 ChatGPT 里精心设计一个问题，期待一个好回答。互动模式是"一问一答"，关注单次交互质量。

2.2 2025年 · Context Engineering（上下文工程）

仅靠一次好提示不够了。需要在 Agent 运行过程中，在合适的时间输入合适的內容------比如先看相关文档、再看用户需求、最后让它动手。

关键认知升级： 从"写好一个问题"变成了"导演一场多轮对话"。但即便如此，仍然依赖人类在每个环节做决策和判断。

2.3 2026年 · Harness Engineering（驾驭工程）

给 Agent 创建一个适合运行的完整环境------包括项目导航配置、自动化约束、反馈循环、多 Agent 协作机制等。让正确行为自然发生，而不是依赖人的记忆力和自觉性。

2.4 一个贯穿始终的类比

	Prompt Engineering	Context Engineering	Harness Engineering
角色	喊话技巧	提供地图与规则手册	设计并穿戴完整"马鞍"
核心	研究如何说，执行单次指令	组织信息（文档、规范、API）	设计一整套安全、可靠、高效的生态系统

💡 引导理解： 想象你在教一个人骑马。Prompt Engineering 是喊"跑起来！向左转！"；Context Engineering 是给这个人一张地图和一本骑行手册；而 Harness Engineering 是给马设计并穿戴一整套完整的马鞍------包含导航、缰绳、刹车系统，让马能安全高效地完成复杂长周期任务。你不再需要一直喊指令了。

三 Harness Engineering

Harness Engineering 是设计、构建和优化 AI Agent 运行环境的工程学科。

它的核心公式：

AI Agent 的产出质量 = AI 模型能力 + Harness 设计水平

Harness 之于 AI Agent，如同操作系统之于 CPU------裸机运算只有在其调度、约束和资源管理下，才能稳定地运行复杂应用。

2026年2月5日，HashiCorp 联合创始人 Mitchell Hashimoto 在他的博客中正式命名了这个概念。他的核心定义值得反复品味：

"每当你发现 Agent 犯了一个错误，你就花时间工程化一个解决方案，让这个错误永远不再发生。"
🤔 思考： 这句话的精髓不在于"修复错误"，而在于"工程化一个解决方案"------不是写一行提示词让 Agent "下次注意"，而是用代码、配置、自动化脚本把约束固化下来。这正是从"手工作坊"到"工程体系"的分水岭。

四 Harness Engineering 的四个支柱

支柱一：代码库即真相源（Codebase as Source of Truth）

• 一句话： Agent 的所有知识应来自项目本身的配置文件（如 CLAUDE.md / AGENTS.md），而非外部的"万页说明书"。

• 没有它，其他三根支柱都无从谈起------Agent 连这个项目用什么语言都不知道，谈何"约束"和"反馈"？用一个场景来理解：你让 Agent 在一个 Python 项目里写代码。没有 CLAUDE.md 时，Agent 不知道你用 pytest 还是 unittest 跑测试、不知道你偏好 snake_case 还是 camelCase、不知道 .env 文件不能碰。你每次开新会话都得重复说一遍------而人是会忘记的，总有一次你忘了说"别碰 .env"，然后 Agent 就真的改了。

• OpenAI Codex 团队在实践中得到了一条代价不菲的教训：他们尝试过把所有信息塞进一个巨大的 AGENTS.md------失败了。原因是上下文窗口是稀缺资源，巨大的指令文件会挤掉真正需要的代码和任务信息。Agent 面对一个 500 行的说明书，反而不知道哪些信息和当前任务相关。

• 正确做法是：AGENTS.md 作为"目录"指向结构化的文档目录------约 100 行，告诉 Agent "项目用什么技术栈、代码风格是什么、哪些命令不能碰、遇到问题怎么验证"。Agent 拿到地图后，按需跳转检索具体文档。

Hashimoto 的配置文件维护法则

• Mitchell Hashimoto 分享了一条非常值得学习的经验：CLAUDE.md 中的每一条规则，都对应过去一个真实的 Agent 犯错案例。

这是一种增量式学习机制------不是一次性写出"完美"的配置文件，而是在实际使用中不断积累。这意味着你的 CLAUDE.md 会随着项目推进越来越"聪明"，覆盖越来越多的边界情况。

🤔 引导思考： 这种"Agent 犯错 → 分析根因 → 写成规则 → 加入配置文件 → 下次自动读取 → 永不再犯"的循环，本质上是一种机器学习的离线训练过程。每一次 Agent 的错误，都是你为这个系统收集的训练样本。

三层配置策略（Claude Code）

层级	路径	作用域	典型内容
全局	~/.claude/CLAUDE.md	所有项目	个人偏好（语言、风格、工作习惯）
项目	./CLAUDE.md	当前项目	技术栈、命令、代码规范、约束边界
个人	./.claude/local.md	当前项目（仅自己）	个人在该项目的特殊偏好

💡 理解： 三层配置在 Agent 启动时自动合并加载，优先级：个人 > 项目 > 全局。这个设计和软件工程中"配置继承与覆盖"的模式完全一致------全局配置提供默认值，项目配置覆盖团队约定，个人配置覆盖个人偏好。理解这种分层思想，对后续学习其他支柱至关重要。

支柱二：机械化架构约束（Mechanized Architectural Constraints）

• 一句话定义： 用自动化工具把约束刻进执行流程，不依赖 Agent 的"自觉性"。CLAUDE.md 写的是"你应该这样做"（建议），而 Hooks（钩子）和结构测试执行的是"你必须这样做，否则操作被阻止"（法律）。

• Agent 和人类一样会犯错。但人类可以凭经验"感觉不对"，Agent 不行。你在 CLAUDE.md 里写了"不要执行 rm -rf /"------这条命令会删除整台机器上的所有文件，Agent 大概率会遵守------但**"大概率"对安全性来说是不够的**。在涉及数据安全、代码质量、架构一致性的地方，我们需要的是 100% 的确定性。

💡 核心思想： "CLAUDE.md 是建议，Hooks 是法律。"建议可以忽略，法律不行。

Hooks：AI Agent 的"安全阀"

• 如果你用过 Git，可能听说过 Git Hooks------在 git commit 或 git push 时自动触发的检查脚本。AI Agent 的 Hooks 是同样的概念：在 Agent 执行某个操作的前后，自动触发一段检查程序。 比如：Agent 准备执行一条命令时（PreToolUse），Hook 先检查这条命令是否安全；Agent 修改完文件后（PostToolUse），Hook 自动运行代码格式化。通过就继续，不通过就拦截------Agent 没有"选择忽略"的余地。

Prompt Hook：用 AI 约束 AI

prompt 类型的 Hook 是机械化约束的高阶形态------它不运行 Shell 脚本做模式匹配，而是调用另一个 LLM 来做语义理解。

	command Hook（字符串匹配）	prompt Hook（语义理解）
检测方式	关键词匹配	语义理解
速度	毫秒级	1-3 秒
能力	检测已知的危险模式	发现未知的风险模式
成本	零（本地执行）	消耗 API 额度

🤔 思考： 想象 Agent 写了一段 Python 代码 shutil.rmtree('/')------字符串匹配抓不住它，因为压根没出现 rm 这个关键词。但 prompt Hook 可以理解代码的语义："虽然这段代码没有 rm -rf，但 shutil.rmtree('/') 的效果是递归删除根目录"。这就是从"模式识别"到"语义理解"的跃迁。

最佳实践：双层防线。 用 command Hook 做高速模式匹配拦截已知威胁（速度快、零成本），用 prompt Hook 做深度语义分析捕获未知风险（能力强，但有延迟和成本）。两者不是替代关系------command Hook 是第一道筛子过滤 99% 的明显问题，prompt Hook 是第二道网兜住那些"看起来没问题但实际有隐患"的漏网之鱼。

反直觉洞察：收窄解空间反而提高成功率

• 很多人的直觉是"给 Agent 更多自由度，它能做更多事"。但 OpenAI 的实践证明了相反的结论------限制选择比提供更多自由更有效。

• 当你告诉 Agent "用任何你觉得合适的方式实现这个功能"，它面对无限可能性，选择的方差极大。但当你约束它"必须用 React 组件、遵循项目的命名规范、通过 Service 层调用后端"，它在收窄后的解空间里反而更容易找到正确答案。

💡 类比理解： 这和人类的经验类似------有明确的编码规范的团队，代码质量通常优于"自由发挥"的团队。约束不是限制创造力，而是把创造力引导到有价值的方向。

支柱三：反馈循环（Feedback Loops）

一句话： 让 Agent 在每一步都能自动获知"做得对不对"，而不是在完成所有工作后才发现错了。没有反馈的 Agent 就像在黑暗中射箭------可能偶尔命中，但大多数时候偏离靶心。

• 反馈循环是 Harness 的核心：Anthropic 在他们的长时运行 Agent 博文中提出了一个极其精准的类比：Agent 的每个新会话开始时没有之前的记忆------就像轮班的工程师没有交接记录。反馈循环就是确保每一位"轮班工程师"都知道做到哪了、做得对不对、下一步应该做什么。

多层反馈机制：从即时到跨会话

实践中，反馈循环分为四个层次，从即时到跨会话逐层递进：

层级	触发时机	机制	代表实现
即时反馈	工具调用前后	Hooks（格式检查、安全拦截、语法验证）	Claude Code PreToolUse/PostToolUse
构建反馈	PR 创建时	CI/CD Pipeline（测试结果、lint 报告、类型检查）	GitHub Actions、Stripe CI
运行时反馈	应用部署后	可观测性工具（日志、指标、性能追踪）	OpenAI Chrome DevTools 集成
评审反馈	功能完成后	独立评估者（质量评分、改进建议）	Anthropic Evaluator Agent

🤔 思考： 这四层不是"选一个就好"------它们互相补充。缺少任何一层，都意味着某类问题会"静默通过"直到造成实际损害。比如：没有即时反馈，Agent 可能写出语法错误的代码；没有构建反馈，功能缺陷可能在测试阶段被遗漏；没有运行时反馈，性能问题要到用户投诉才被发现。

Anthropic 的两阶段会话协议：设计"交接制品"

Anthropic 在长时运行 Agent 的实践中设计了一套优雅的反馈协议，解决"Agent 重启后不知道做到哪了"的问题：

• Phase 1（Initializer Agent）： 首次会话搭建基础设施，产出 init.sh 启动脚本和 progress.txt 进度文件。

• Phase 2（Coding Agent）： 后续每次会话启动时，先执行 git log + progress.txt 了解做到哪了，选最高优先级的未完成功能开始实现。

• Harness 的核心价值之一------设计"交接制品"。 Agent 不需要记住上一个会话做了什么，因为 git log 和 progress.txt 已经记录了一切。

💡理解： 这个协议的精妙之处在于：它不依赖 Agent 的记忆力（记忆是不可靠的），而是把状态外化到持久化的文件系统中。这正是软件工程中的经典模式------用文件系统作为进程间通信的媒介。

评估与生成的分离：GAN 式架构

• Anthropic 在 2026 年 3 月发布的最新博文中，将反馈循环推进到了全新高度------受 GAN（生成对抗网络）启发，设计了三 Agent 协作架构：

Agent	职责	类比
Planner（规划者）	把简短描述扩展为完整产品规格	产品经理
Generator（生成者）	按 Sprint 迭代实现功能	开发工程师
Evaluator（评估者）	用 Playwright 做端到端测试，基于客观标准打分	QA 工程师

• 他们发现了 LLM 的一个根本性问题：当 Agent 被要求评估自己的工作时，它会表现出不合理的自信和宽容------即使产出很平庸，自评也倾向于打高分。 解决方案不是"让 Agent 学会自我批评"（这很难），而是把评估交给独立的 Agent。

💡洞察： "调校独立评估者的怀疑度，比让生成者对自己的工作保持批判性要容易得多。"------这正是 GAN 的核心思想：判别器不需要有创造力，只需要足够挑剔。

支柱四：熵管理（Entropy Management）

一句话定义： 主动管理 AI 代码生成带来的独特"系统退化"------不是传统意义上的 bug，而是渐进式的文档漂移、架构侵蚀和风格不一致。如果不管理，Agent 产出的代码库会越来越难以维护，最终陷入"生成得越快、烂得越快"的恶性循环。

• AI 代码的"独特垃圾"：Harness Engineering 中最具原创性的洞察。

传统软件开发中，代码质量问题主要是"bug"------程序崩溃、逻辑错误、安全漏洞。但 AI 生成的代码有一种全新类型的质量问题------不是某一行代码有错，而是整个代码库在缓慢退化：

熵类型	表现	AI产生原因
文档漂移	注释/文档说的和代码做的不一致	Agent 改了代码但忘了更新注释
架构侵蚀	绕过设计约束的"捷径代码"越来越多	Agent 倾向于选择最短路径而非最规范路径
风格不一致	同一项目出现多种命名风格、多种实现模式	不同会话的 Agent "不记得"之前的风格选择
重复代码	功能相似但不完全相同的代码块散落各处	Agent 有时会重新实现已有的功能而非复用

🤔 思考： 这些问题每一个单独看都不严重------不会让程序崩溃，不会触发报错。但它们的累积效应是致命的：代码库变得越来越难以理解和维护。这就是"熵"的本质------不是爆炸性的灾难，而是渐进式的腐烂。

• OpenAI Codex 团队提出了一个精妙的类比：把代码熵的管理当作编程语言的垃圾回收（GC）来做 ------不是等技术债积累到爆发才一次性清理，而是持续运行、定期回收。
  1. 将编码原则固化为 linter 规则------人类的"品味"和审美判断，通过规则编码为自动化检测。
  2. 后台 Agent 定期扫描------专门的"清理 Agent"周期性运行，扫描文档不一致、约束违规、架构漂移。
  3. 持续重构而非积压技术债------发现问题立即修复，而非放入"以后再说"的 backlog。

💡理解： OpenAI 对此有一句非常精练的概括："品味捕获一次，强制执行无限次。"你只需要把你对代码质量的判断标准编码为规则一次，然后 Agent 就会持续不断地按照这个标准执行检查。人类的品味是珍贵而稀缺的------通过机械化，它的价值被无限放大了。

• Philipp Schmid 在分析 Harness Engineering 时发出了一个重要警告，他称之为 Bitter Lesson（苦涩的教训） ：Harness 必须设计成可删除的。因为今天需要复杂管线来完成的任务，明天可能一个提示词就搞定了。 具体数据很有说服力：

  • Manus 团队在 6 个月内重构Harness 5 次，每次都是为了删掉过时的复杂逻辑
  • Vercel 删除了 80% 的 Agent 工具后，效果反而更好
  • LangChain 一年内重架构 3 次

• 这些血泪教训都指向同一个设计原则：Start Simple（从简单开始）、Build to Delete（为删除而构建）。 不要一上来就搞复杂的控制流。先提供稳健的原子工具，用模块化架构让每个组件都可以独立替换或删除。如果一个模块和十几个模块深度耦合、删除它的成本比开发它还高------那已经违反了 Bitter Lesson。

六、LangChain 的实验：改善 Harness 的效果是换模型的 2 倍

• 理解了四大支柱，我们回到核心公式：AI Agent = AI Model + Harness。
• 这不是理论推导------LangChain 团队用一个精心控制变量的实验证明了这一点。2026年3月，他们在 Terminal Bench 2.0 基准测试上的实验数据：

对比维度	改善前	改善后	变化
Terminal Bench 2.0 得分	52.8%	66.5%	+13.7pp
排名	30+	Top 5	提升 25+ 位
模型	GPT-5.2-Codex	GPT-5.2-Codex	未更换
改了什麼	---	系统提示词 + 工具 + 中间件 Hooks	Harness 三变量

作为参照，同期如果是通过换更强的模型来提升成绩，通常能获得约 +6.8pp 的提升。也就是说：

改善 Harness 的效果（+13.7pp）是换模型的 2 倍（+6.8pp）。

这组数据彻底颠覆了"性能不够就更换大模型"的朴素直觉。对于大多数团队来说，优化 Harness 的投入产出比远高于追逐最新模型。

七 工程师角色的深层转变：从"写代码的人"到"设计环境的人"

• 四大支柱和核心公式共同指向一个更大的命题：工程师的角色正在发生根本性转变。

• Mitchell Hashimoto 这样描述自己的新角色定位："我是软件项目的架构师。我仍然负责代码结构、数据流设计、状态管理。但具体的代码编写，越来越多地交给了 Agent。"

• 用一个"厨师"的类比来理解这个转变：

  • 过去： 厨师亲自做菜（工程师亲自写代码）
  • 现在： 厨师设计菜单 + 训练厨房团队 + 检查每道菜的出品质量（工程师设计约束 + 配置环境 + 验证 Agent 的产出）

🤔思考： 这不是降级，而是升级------它需要更高层次的系统思维。你需要同时理解：Agent 擅长什么、哪里会犯错、怎样的约束能最小化错误、怎样的反馈循环能让系统越用越好。你从"执行者"变成了"系统设计者"。

八 局限性与冷思考

• 在兴奋之余，我们也需要保持清醒。Martin Fowler 团队（ThoughtWorks）在对 Harness Engineering 的分析中提出了两个的质疑：

  1. 验证缺口： Harness 擅长检查代码是否"合规"（风格、结构、类型），但对代码是否"正确"（功能逻辑是否对）的验证仍然不够。Linter 能抓住格式问题，但抓不住业务逻辑错误。
  2. 遗留代码困境： 目前的成功案例几乎都是从零开始的新项目。对于已有数万行遗留代码的项目，如何设计 Harness 使 Agent 能在其中安全工作，还没有成熟的方法论。

• 此外还有一个被反复验证的事实：复杂度转移而非消失。 "写代码的复杂度"转移为"设计环境的复杂度"------Harness Engineering 没有让软件开发变简单，它让复杂度从一个地方搬到了另一个地方。只不过，这个新的地方更适合人类发挥系统思维的优势。

---

九 写在最后：Bitter Lesson 的三条设计原则

回顾整个Harness Engineering 的知识体系，可以提炼出三条贯穿始终的设计原则：

1. Start Simple（从简单开始）------不要一上来就搞复杂的控制流，先提供稳健的原子工具。
2. Build to Delete（为删除而构建）------每个组件都应该可以被独立替换或删除，避免深度耦合。
3. Mechanize Taste（品味机械化）------把你对质量的判断标准编码为规则一次，让机器无限次执行。

最后的思考： Harness Engineering 的价值不局限于 AI 编程。它的本质是让任何 AI 智能体从"玩具级问答"进化到"生产级产出"的通用方法论。当内容创作、数据分析、自动化工作流等场景都需要 Agent 完成复杂系统性任务时，这套方法论同样适用。

2026年，"如何用好智能体"不再是一个技巧问题------它是一个工程学科。而工程的本质很简单：

不要依赖人的记忆力和自觉性，要设计一个让正确行为自然发生的环境。

---

参考资料：OpenAI Codex 博文《Engineering in an Agent-First World》、HashiCorp Mitchell Hashimoto《My AI Adoption Journey》、Anthropic《Effective Context Engineering for AI Agents》及《Harness design for long-running application development》、LangChain Blog《Improving Deep Agents with harness engineering》、Philipp Schmid《The importance of Agent Harness in 2026》等。