驾驭而非编码：AI Agent 时代的 Harness Engineering
最好的代码也许不是人写的，但一定是人”驾驭”出来的。
引言：为什么 AI Agent 总是不守规矩？
你一定经历过这些场景——
在 CLAUDE.md 里精心写了编码规范，几轮对话后 AI 就忘了；修一个 bug，结果引入了两个新 bug；随着对话变长，Agent 的能力肉眼可见地下降；每个新会话都要重新解释整个项目背景；明明只要一个按钮，AI 却写了 9000 行。
这些问题不是个例。自从 Andrej Karpathy 在 2025 年初提出”Vibe Coding”以来，越来越多的开发者体验到了”放手让 AI 写代码”的快感，也同样撞上了”放手之后不可控”的墙。
这些问题的根源不在 prompt 写得不好，而在于 Agent 的运行环境缺乏约束。
从 2026 年初开始，一个新概念在社区迅速传播：Harness Engineering。它不教你怎么写更好的 prompt，也不教你怎么注入更精准的上下文——它教你如何为 AI Agent 构建一个稳定、可靠的运行环境。
这篇文章梳理这条范式演变的脉络：从 Prompt Engineering 到 Context Engineering，再到 Harness Engineering。理解了这条线，你就理解了为什么”驾驭”正在取代”编码”，成为 AI Native 时代开发者的核心能力。
一、三层工程范式
AI 编程的工程实践，经历了三个阶段的演变[1]：
| 阶段 | 关注点 | 核心动作 | 代表时期 |
|---|---|---|---|
| Prompt Engineering | 单次对话中如何措辞 | 写更好的 prompt | 早期 ChatGPT / Copilot |
| Context Engineering | 为模型提供合适的上下文 | 注入知识、管理对话窗口 | 2024–2025 AI IDE 实用化 |
| Harness Engineering | 为 Agent 构建稳定运行环境 | 约束、沉淀、编排 | 2026 年初，社区共识形成 |
这三个阶段不是互相替代的，而是层层叠加——你仍然需要好的 prompt，仍然需要精准的上下文，但在 Harness Engineering 阶段，你更进一步：将整个运行环境纳入工程化管理。
打个比方：
- Prompt Engineering 是教一个新手厨师怎么切菜（告诉它刀怎么拿）
- Context Engineering 是给厨师提供对的食材和菜谱（让它知道做什么菜）
- Harness Engineering 是设计整个厨房——灶台布局、火候控制、出菜质检流程（让它在系统里稳定产出）
二、Harness 是什么
2.1 一个公式
Agent = Model + Harness[2]
这个公式来自 LangChain 工程师 Viv Trivedy 的文章。当 harness 为模型提供了状态、工具执行、反馈闭环和可强制执行的约束后，它就可以称作 Agent。
换句话说：模型是大脑，Harness 是环境。 大脑再聪明，在混乱的环境里也无法稳定工作。
Harness 具体包含什么[2]：
- System Prompts — 定义角色和行为边界
- Tools、Skills、MCP 及其描述 — 提供能力和操作知识
- 基础设施 — 文件系统、沙箱、浏览器
- 编排逻辑 — 子 agent 调度、模型路由
- Hooks / 中间件 — lint 检查、格式化、质量闸门
2.2 Harness 的三层分类
根据与具体项目的关联程度，harness 可以分为三层[3]：
| 层次 | 内容 | 说明 |
|---|---|---|
| 通用 harness 层 | 终端交互、tool loop、权限系统、记忆、线程持久化、context compaction、hooks、任务调度 | 与具体项目弱相关，属于 Agent runtime 的通用能力。Claude Code、Codex、OpenCode 已做了大量工作 |
| 项目 harness 层 | CLAUDE.md / AGENTS.md、仓库知识布局、架构边界、lint 规则、质量标准、依赖选择原则、文档索引 | 与具体项目强相关，但不是业务功能本身。OpenAI 实践报告中最有价值的创新集中在这一层 |
| 任务/运行 harness 层 | planner-generator-evaluator 三 agent 架构、跨 session 文档交接、QA prompt、Playwright 检查脚本 | 与当前具体工作强相关 |
对个人开发者而言，通用 harness 层已由工具提供。你真正需要设计和维护的，是项目 harness 层。
2.3 起源故事
Harness 被引入 AI Agent 领域，有一条清晰的时间线[3]：
| 时间 | 事件 |
|---|---|
| 2026-02-05 | Mitchell Hashimoto 在个人博客首次提出 “Engineer the Harness”——每当发现 Agent 犯错，就花时间设计一个解决方案，让它永远不再犯同样的错误 |
| 2026-02-11 | OpenAI 发布工程报告《Harness Engineering: Leveraging Codex in an Agent-First World》，总结全 Agent 代码库的实践 |
| 2026-03-24 | Anthropic 发布长时运行应用 harness 设计研究，提出 planner-generator-evaluator 三 agent 架构 |
| 此后 | Claude Code 源码泄露事件加剧了 harness 设计讨论（通常认为 Claude Code 是 harness 设计的典范） |
Harness Engineering 不完全算全新发明。可以说，它是软件工程和工程控制论的原则在 AI Agent 中的延伸[4]，很好地总结了当前阶段的最佳工程实践——是否最佳，仍需时间检验。
三、Vibe Coding 的五宗罪
Karpathy 对 Vibe Coding 的描述是浪漫的：”完全顺应感觉，拥抱指数级增长，甚至忘记代码本身的存在。”
但当你把 Vibe Coding 从 demo 带入持续迭代的生产项目时，会遇到五个典型问题[5]：
| # | 问题 | 表现 | 根源 |
|---|---|---|---|
| 1 | Agent 不守规矩 | CLAUDE.md 写的规范，几轮对话后 AI 就忘了 | 配置没有强制执行机制 |
| 2 | 修 A 坏 B | 修一个 bug 引入另一个，AI 缺乏全局视野 | 缺乏架构约束和变更边界 |
| 3 | 上下文腐朽 | 对话越长，模型能力越下降 | 缺乏上下文管理和压缩策略 |
| 4 | 跨会话失忆 | 新会话要重新解释整个项目背景 | 缺乏跨 session 的状态持久化 |
| 5 | 任务膨胀 | 只要一个按钮，AI 写了 9000 行 | 缺乏任务边界和完成标准约束 |
这些问题有一个共同的根源：Agent 的运行环境缺乏约束。
这不是 prompt 层面的问题——你把 prompt 写得再好，Agent 在一个没有护栏、没有质检、没有沉淀的环境里，仍然会反复犯错。就像一个没有交通规则的城市，无论司机多熟练，事故率都不会低。
四、Harness 的三层实践框架
Harness 的工程实践可以归纳为三层：配置层、约束层、沉淀层。每一层解决上一层的遗留问题，层层递进。
4.1 配置层：让 Agent 知道规矩
配置层的核心载体是 CLAUDE.md（或其他工具中的 AGENTS.md）。
一个常见的认知误区：CLAUDE.md 不在 System Prompt 里。
根据 Claude Code 源码分析[6]，CLAUDE.md 的内容通过 prependUserContext() 函数注入，被包装在 <system-reminder> 标签中，作为第一条 user message 插入到对话开头。这意味着：
- 它的优先级低于 system prompt
- 模型被显式告知这些内容”可能不相关”
- 但开头有强指令对抗降权信号：These instructions OVERRIDE any default behavior
实际效果取决于指令的具体性——越具体的指令越容易被遵守，越模糊的越容易被忽略[6]。不要写”尽量简洁”，写”回答不超过 3 句话”。不要写”保持优雅的代码风格”，写”不要添加注释到未修改的代码”。
OpenAI 在其全 Agent 代码库的实践中，总结了配置文件的三条核心原则[7]：
地图而非百科全书。 他们曾尝试用一个巨大的 AGENTS.md 装下所有指令，结果发现：上下文是稀缺资源，一个巨大文件会挤掉任务、代码和相关文档；过多指导反而无效，当一切都”重要”时，一切都不重要；它会立即腐烂。最终他们将 AGENTS.md 精简为约 100 行的内容目录，指向
docs/目录中更深层的文档——实现渐进式披露（Progressive Disclosure）。Agent 看不到的知识等于不存在。 存储在 Google Docs、聊天记录或人脑中的知识不可访问。代码仓库本地的、已版本化的工件就是 Agent 能看到的全部——知识必须沉淀进 Repo。
一个有效的 CLAUDE.md 最少需要包含：项目技术栈和架构概览、编码规范和命名约定、目录结构说明、常用命令（构建、测试、运行的具体命令）、关键约束。
4.2 约束层：让 Agent 不能做错
配置层告诉 Agent “应该怎么做”，但自然语言指令的约束力是软的。约束层的核心原则：编码约束优于自然语言指令。
| 原则 | 实践 |
|---|---|
| Lint/Formatter 自动执行代码风格 | 配置 ESLint、Prettier、Ruff 等工具，通过 Hook 在保存或提交时自动执行。不要在 CLAUDE.md 里写”请保持优雅的代码风格”，让 lint 替你执行 |
| 架构不变量通过自定义 lint 强制执行 | OpenAI 实践：每个业务域划固定层（Types → Config → Repo → Service → Runtime → UI），依赖方向经严格验证，只允许有限的边。这些约束通过自定义 linter 和结构测试强制执行 |
| 错误信息注入修复指令 | OpenAI 的创新做法：当 Agent 触发自定义 lint 规则时，错误信息本身就包含了如何修复的指导。Agent 不需要”理解”规则，只需要”照着错误信息修” |
| CI 作为质量闸门 | Agent 生成代码无法通过 CI → 错误回传上下文 → 自我修正闭环。OpenAI 团队专门配置 linter 和 CI 来验证知识库的更新状况、交叉链接结构 |
| JSON 比 Markdown 更不容易被篡改 | Anthropic 发现：用 JSON 存储特性列表时，模型不太会不当修改；Markdown 格式下，模型更容易删除或编辑条目[8] |
| 文件系统边界 | 通过目录结构本身限制 Agent 的修改范围 |
4.3 沉淀层：让 Harness 自我进化
沉淀层的核心机制：每次 bug 修复都变成规则更新。
这正是 Mitchell Hashimoto 最初对 harness 的阐释——每当发现 Agent 犯错，就花时间设计一个解决方案，让它永远不再犯同样的错误[3]。
三个代表性实践：
- Trellis 框架：修复 bug →
/break-loop→ 分析根因 → 编辑.trellis/spec/下的 spec 文件 → git 提交。spec 通过 hook 自动注入每次交互中的强制上下文[5] - Anthropic：session 结束时将进度写入
progress.txt并 git commit → 下个 session 的 Agent 读取这些文件快速了解项目状态[8] - OpenAI：执行计划视为一等工件（first-class artifacts），活跃计划、已完成计划和已知技术债务都版本控制并集中存放[7]
沉淀的效果是复利式的：项目越久，积累的规则越多，Agent 犯同类错误的概率越低。
五、工具生态与常见陷阱
5.1 三种 Harness 方案
当前个人开发者可选的 harness 工具大致分为三种[9]：
| 方案 | 特点 | 适合场景 |
|---|---|---|
| 纯配置方案 | CLAUDE.md + superpowers 等 skill 集合 | 最轻量起点，做好配置层即可 |
| 框架增强方案 | Trellis、ccg-workflow 等，增加 spec 系统 + hook 自动注入 | 持续迭代项目，配置层 + 约束层 + 适度 spec 沉淀 |
| 多角色编排方案 | oh-my-claudecode、oh-my-opencode，定义 planner/executor/reviewer 等角色 | 长期项目，需要角色分工与多 agent 协作 |
一个判断标准：如果花了大量时间在维护 Harness 本身（编辑计划文件、更新进度文档、协调 Agent 通信）而实际代码产出很少，说明 Harness 已经变成了负担而非助力[9]。
5.2 三个常见陷阱
不要追求一步到位的完美 harness。 Anthropic 明确提出了一个原则[10]：
Find the simplest solution possible, and only increase complexity when needed.
找到最简方案，只在必要时增加复杂度。不要忽视模型差异。 Anthropic 的实践中，Claude Sonnet 4.5 表现出明显的”上下文焦虑”——当它认为接近上下文限制时，会过早结束工作。而 Claude Opus 4.5/4.6 在很大程度上自行解决了这个问题，使得压缩对话上下文成为更好的选择。同一套 Harness 配置不一定在所有模型上都有效[10]。
多 Agent 不等于更好。 多角色编排方案会增加通信开销和协调复杂度。社区反馈：oh-my-opencode 等套件定义了十多种 agent 角色，但实际使用中，codex + superpowers 的简单组合反而效率更高。对个人开发者的大多数场景，单 Agent 配合好的约束比多 agent 更可控[9]。
结语：驾驭能力是新的核心能力
在现代软件开发 AI Native 的模式下，个人开发者的工作重心不再是逐行编写实现代码，而是设计一个环境，让 Agent 能够可靠地完成编码工作。
可以预见，个人开发者应当具有一些基本素养：系统思维、规范能力——这些”驾驭能力”。在 Harness Engineering 的命名中就能看出：最好的代码也许不是人写的，但是一定是人”驾驭”出来的。
然而，Harness 需要辩证设计。Anthropic 的研究对此有一段原话[10]：
Harness 的每一个组件都编码了对模型自身能力的某种假设，这些假设值得反复验证，因为它们可能本来就是错的，也可能很快会因模型进步而过时。
随着模型基础能力提升，Harness 的部分组件应该能够简化甚至移除。盲目加厚 Harness 不是工程，是迷信。
最后，一个类比。历史上，珍妮纺纱机的发明让传统手工纺纱女工被机器大量取代。纺织业没有因此消亡，反而催生了一个新角色：负责操作、调试和维护机器的技术工人。
今天的软件开发正在经历类似的转变。AI Agent 取代的是”编码”本身，而”驾驭”能力将会成为新的核心能力。只会死板背诵 CRUD 的初级程序员将会或已经被 AI 取代；擅长”驾驭”的高级工程师，会在未来发挥更强的作用。
参考资料
- Shuhan_Chengxiang. 浅谈 Harness Engineering. linux.do/t/topic/1874105
- Viv Trivedy. The Anatomy of an Agent Harness. x.com/Vtrivedy10/article/2031408954517971368
- BosaBosa. 怎么都在说 Harness Engineering. linux.do/t/topic/1909881
- chumeng. harness 是互联网公司重新发明的新词还是有独特的创新之处. linux.do/t/topic/1906915
- Zimon. 【学习笔记】Trellis-一个强大的 AI 脚手架. linux.do/t/topic/1803719
- Khalil Gao. 深入浅出 Claude Code（一）：从源码理解 CLAUDE.md. linux.do/t/topic/1871216
- OpenAI. Harness Engineering: Leveraging Codex in an Agent-First World. openai.com/index/harness-engineering
- Anthropic. Effective harnesses for long-running agents. anthropic.com/engineering/effective-harnesses-for-long-running-agents
- BeMxself. 想开一个 harness engineering 实践的长期帖子. linux.do/t/topic/1791588
- Anthropic. Harness design for long-running application development. anthropic.com/engineering/harness-design-long-running-apps
- obra. superpowers skills. github.com/obra/superpowers