1. 什么是Harness？
包裹在模型外面的那套系统，也就是所谓的 harness。直译过来是"挽具"，套在马身上用来控制方向的那套装备，这里意味着把模型驯服的意思。一个很形象的比喻：模型是马，很有力量，但如果没有缰绳、马鞍和嚼子，马想去哪就去哪。Harness 就是让这匹马按照你的意图跑的那套东西。
有研究者用同一个 AI 模型跑同一套编程基准测试，第一次得了 42 分，第二次得了 78 分。模型没换，测试没换，温度参数没调，什么都没变。唯一变了的，是Harness。
Harness的设计，包括注入给 AI 的规则文件、工具配置、技能模块、记忆文件、以及各种反馈回路。它决定了 AI 在接到任务之后怎么理解需求、怎么拆解步骤、怎么避免犯错、怎么在出错之后自我纠正。
LangChain 的团队独立验证了同样的结论。他们的编程智能体在 Terminal Bench 2.0 基准测试上，从排名30开外直接冲进前 5。模型没换，只换了 Harness。OpenAI 的 Codex 团队更夸张，他们用 AI 写了一个超过一百万行代码的生产级应用，其中没有一行是人手写的。工程师全程没有写代码，他们做的事情就是设计Harness。
这些案例指向一个非常清晰的结论：模型的选择远没有大家以为的那么重要，真正决定 AI 编程质量的，是围绕模型搭建的Harness系统。
2. Harness Engineering
软件开发正在经历一场根本性的变革。过去半个世纪里，我们一直在培养工程师编写代码的能力。但现在，正在进入一个AI驱动软件开发实践的新时代 ------ AI智能体编程。
实际情况远比想象的复杂。当给AI一个简单的提示时，它可能表现惊艳。但当让它处理一个真实的、复杂的、长期的项目时，就会发现AI智能体：
1）很快就会"迷失"在代码的海洋中；
2）会在同一个错误上反复尝试（Doom Loops）；
3）生成的代码缺乏一致性；
4）文档和代码会逐渐失去同步；
5）架构边界会被悄然突破。
这些问题的根源不在于AI模型本身不够强大，而在于缺乏一个能够有效引导、规范和管理AI行为的系统 ------ Harness Engineering。
马跑得快，马具是关键。
2.1 案例分享
1）OpenAI 的百万行实验
2025年8月至2026年1月，OpenAI团队进行了一项为期五个月的实验：
- 从0开始 构建一个拥有 100 万行代码 的产品
- 0 行人工编写代码 ------ 全部由 Codex 智能体生成
- 仅有 3 名工程师 驱动约1500个PR（Pull Request，代码合并请求）
- 吞吐量：每人每天 3.5 个PRs
2）LangChain的性能飞跃
LangChain的编程智能体在Terminal Bench 2.0上的表现：
|--------|--------|--------|
| 阶段 | 分数 | 排名 |
| 优化前 | 52.8% | Top 30 |
| 优化后 | 66.5% | Top 5 |
关键点：模型没变，只是改了Harness
2）Stripe的Minions
Stripe的编程智能体（称为Minions）现在每周产生超过1000个合并的PR：
1）开发者在Slack发布任务；
2）Minion编写代码；
3）Minion通过CI；
4）Minion打开PR；
5）人类审查并合并。
步骤1）到5）之间，没有任何开发者交互。
2.2 技术洞察
"模型是商品，Harness才是护城河"------ LangChain
这个结论来自真实的实验数据，而不是理论推测。当所有人都在追逐更强大的模型时，真正的竞争焦点已经转移到：谁能在模型周围构建更好的系统。
以前拼的是写多少代码，现在拼的是能不能指挥AI高效地写出高质量的代码。
软件工程师的能力评价标准变了，展示能力的方式自然也会跟着变。这个变化意味着什么？意味着"我会写 Python"这句话在简历上已经没有任何区分度了。面试官想看到的是怎么驾驭 AI 来构建真正可用的软件。
区分一个开发者是在随便玩 AI 还是在用 AI 交付生产级软件，关键看他在输入提示词和提交代码之间做了什么。他会不会先写规格说明？会不会批判性地审查 AI 的输出？会不会写测试？还是把 AI 当成一个许愿池，生成完就不管了？
企业的面试环节，关键点也发生了变化。面试官已经不再让候选人从零开始手写代码了，他们开始关注候选人怎么跟 AI 协作。
2.3 什么是Harness Engineering
Harness Engineering，驾驭工程，设计和实现以下系统的科学：
|---------------|-------------------------------|
| 能力 | 说明 |
| Constrain（约束） | 规范智能体能做什么（架构边界、依赖规则） |
| Inform（告知） | 告知智能体应该做什么（上下文工程、文档） |
| Verify（验证） | 验证智能体是否正确完成了任务（测试、linting、CI） |
| Correct（修正） | 智能体出错时，进行自动纠正（反馈循环、自我修复） |
"Harness" 这个词来自马具 ------ 缰绳、马鞍、嚼子 ------ 一套用来引导强大但不可预测的动物的完整装备，比喻的具体含义：
|-------------|-------------------------|
| 隐喻 | 含义 |
| 马 | AI模型：强大、快速，但不知道何去何从 |
| Harness（马具） | 基础设施：约束、规范、反馈循环，引导模型的力量 |
| 骑手 | 人类工程师：提供方向，而不是亲自奔跑 |
没有Harness的AI智能体，就像是一匹不受控的奔马。速度惊人，令人印象深刻，但对于完成实际任务完全无用。
Harness Engineering与Prompt Engineering、Context Engineering两个系统工程的区别：
|-----------------|--------------------|--------------------------------------|----------------------|
| Engineering | 问题 | 比喻 | 范围 |
| Prompt | 怎么说？ | 语音命令："向右转""跑快点" | 单个提词的设计 |
| Context | 给智能体看什么 | 地图和路标：传达路线和周围条件 | 所有传输到LLM的token的设计和管理 |
| Harness | 系统防止什么、测量什么、修复什么么？ | 缰绳、马鞍、栅栏、道路维护：无论多聪明的马，没有这些无法安全同时运行多匹 | 整个系统架构，包括工具、反馈、安全 |
2.4 关键术语
|------------------------------|------------------------|
| 术语 | 定义 |
| Context Rot（上下文腐化） | LLM性能随着上下文窗口填满而下降的现象 |
| Context Pollution（上下文污染） | 上下文中存在过多无关、冗余或冲突的信息 |
| Doom Loops（厄运循环） | 智能体在同一个错误方法上反复尝试的循环 |
| Mechanical Invariants（机械不变量） | 通过linter/CI机制强制执行的架构规则 |
| Agent Captain（智能体队长） | 每个团队指定负责智能体工作流程的负责人 |
| Entropy Management（熵管理） | 对AI生成的代码进行持续清理和维护 |
2.5 核心组件
根据OpenAI的实践框架，Harness Engineering包含四大核心支柱：
2.5.1 上下文架构（Context Architecture）
核心原则 ：智能体只能推理它能"看到"的内容：提示上下文、检索的文档、工具输出、运行时观察。存储在Slack、Google Docs或工程师头脑中的知识和经验，除非刻意将其导入工作集，否则在操作上是不可见的。
渐进式披露 ：给智能体一张地图，而不是1000页手册。AGENTS.md应该作为目录索引，指向/docs中的深层信息，而不是包含所有细节。
最好的开发者不会只写一个扁平的文件，会建一个多层级的配置体系：最顶层是全局约束和规范，比如编码风格和快捷习惯；中间层是项目级的架构规范和技术栈说明；最底层是子目录级的细分指令，比如 /docs 目录下的文档格式要求，/tests 目录下的测试规范。
有人搭了一个 6 层结构、106 行的配置，在 AI 写第一行代码之前，就已经把语音笔记路由、凭证管理、命名规范全部安排好了。
实践要点，包含静态上下文 和动态上下文两方面：
1）静态上下文
- 仓库、本地文档：架构规范、API规范、编码风格；
- Agents.md文件，软件编码特定规则；
- 通过linter验证的交叉链接设计文档。
2）动态上下文
- 可观测性数据：日志、指标、跟踪；
- 启动和运行时，目录结构映射
- CI/CD管道状态和测试结果
关键规则：仓库必须是单一真实来源，团队不断将更多上下文推送进仓库。所有系统配置相关的markdown（.md）文件，都将变成一个个带版本控制的文件，存在仓库里。
2.5.2 智能体专业化（Agent Specialization）
限定作用域：不要给智能体一个模糊的、高层次的目标，而是将其分解为明确定义的小任务。
受限工具集：单个智能体不需要访问所有工具，根据完成当前任务的智能体所需，提供最小必要的工具集。
深度优先工作流：大任务或复杂任务拆解为小任务，设计 → 代码 → 评审 → 测试
2.5.3 持久记忆（ Persistent Memory）
基于文件系统，而非对话历史：智能体需要记忆跨会话的信息。将关键状态存储在文件中，而不是依赖对话历史的临时记忆方式。本质是通过结构化文件系统实现的持久化知识管理。
跨会话连续性：通过结构化文件（如进度文件）和Git历史记录实现多轮任务的状态传递。使用claude-progress.txt或类似文件记录工作进度，让新会话可以快速了解状态。
Git历史，所有知识必须编码为Markdown文件，并纳入版本控制。Git历史本身就是一个丰富的状态来源。
知识可验证性：所有记忆内容必须可追溯、可审计，作为代码和文档的一部分存在。
不同于传统的易失性内存，它提供持久化存储能力，即使会话结束仍能保留状态。解决了对话历史上下文有限的问题，使复杂任务可分阶段推进，每个阶段有明确的输入输出边界。
分层架构对应：工程实践中对应"Types → Config → Repo"等知识导入路径，确保记忆内容可被各层工具复用。
2.5.4 结构化执行（ Structured Execution）
**工作流分层：**典型工作流，研究（Research）→ 规划（Plan）→ 执行（Execute）→ 验证（Verify）。研究Agent，负责探索分析；规划Agent，负责拆解任务；执行Agent，负责落地实现；验证Agent，负责审计质量。
反馈循环：每个阶段都应该有明确的输入和输出，以及验证标准。执行结果通过测试、审查等验证机制反补前序阶段，形成持续优化回路。
工具链支撑：依赖确定性Linter、结构测试等工具确保AI生成代码符合预设的架构约束（如Types → Config → Repo的单向依赖规则）
结构化执行是解决大规模代码生成任务中"无边界探索导致效率低下"问题的关键机制，通过分离思考与执行过程，让Agent在受控阶段内专注处理特定任务，同时借助架构约束和工具链确保最终结果的合规性。
这种模式已在OpenAI等团队实践中验证：通过将思考与执行分离，百万行代码项目实现零手写生成，日均PR达3.5个，证明结构化执行是驾驭AI工程规模化的核心支柱。
2.6 核心实践
2.6.1 架构约束作为机械不变量
分层架构：定义每域的依赖方向：
html
Types → Config → Repo → Service → Runtime → UI每层只能从左侧层导入，这不是建议 ------ 而是通过结构测试和CI验证强制执行。
为什么约束能提高产出：约束解决方案空间，使智能体更高效，而不是更低效。当智能体可以生成任何东西时，它会浪费token探索死胡同。当Harness定义了清晰的边界时，智能体会更快地收敛到正确的解决方案。
约束执行工具：
|------------------|----------------------|
| 工具 | 说明 |
| 确定性Linter | 自定义规则，自动标记违规行为 |
| LLM审计员 | 审查其它智能体代码的架构规范性 |
| 结构测试 | 如ArchUnit，但针对AI生成的代码 |
| Pre-commit Hooks | 提交前自动检查 |
2.6.2 可观测性接入
让应用对智能体可读：智能体不仅需要能编写代码，还需要能观察代码的运行结果。
- 将日志、指标、跟踪接入智能体可访问的系统；
- 智能体可以使用LogQL、PromQL、TraceQL查询；
- 可以在独立版本上运行任务，完成后删除。
Chrome DevTools 协议：将Chrome DevTools协议接入智能体运行时，可以实现：
- DOM快照捕获；
- 截图；
- 浏览器导航。
这使得智能体可以通过直接驱动UI来复现bug，验证修复。
2.6.3 自动化Code Review
智能体对智能体审查：一个智能体编写的代码由另一个智能体审查，模仿人类工程师相互之间的Code Review机制。
Ralph Wiggum （拉尔夫·威格姆）循环：智能体自我循环，直到所有审核者满意。
"Ralph Wiggum循环"， 并不是一个正式的计算机科学或数学术语，而是出自《辛普森一家》动画片的一个网络迷因。它指的是角色 Ralph Wiggum 说的一句台词："我在吃玉米片，现在我正在吃玉米片。" 这句话的幽默点在于，Ralph 描述了一个没有进展、没有状态变化、完全自我重复的循环：
起始状态：我在吃玉米片
下一个时刻：我还在吃玉米片
再下一个时刻：我还在吃玉米片...
因此，这个迷因被程序员和极客社群用来戏谑地指代一个无限循环，其内部没有任何变量更新或退出条件，比如：
while True:
eat_nachos()
用自然语言理解就是："我执行了一个动作，然后说'现在我正在执行这个动作'------结果跟执行前完全一样，没有任何进展。"
在编程笑话中，它常与"无限循环"或"没有副作用的死循环"类比，区别在于它强调循环中连状态都不变，纯粹是逻辑上卡在同一个点。
2.6.4 垃圾回收（Entropy Management，熵管理
为什么需要：随着时间推移，AI生成的代码库会积累熵（系统的无序性）：
- 文档偏离实现；
- 命名约定分化；
- 冗余代码累积。
解决方法：定期运行的后台任务（清理智能体）：
- 文档一致性智能体：验证文档与当前代码匹配；
- 约束违规扫描器：发现逃脱早期检查的代码；
- 模式执行智能体：识别并修复与既定模式的偏差；
- 依赖审计员：跟踪并解决循环或不必要依赖。
关键洞察：技术债务像高息贷款 ------ 小额常还 > 一次还清
3 实践方法论
3.1 OpenAI方式：零人类代码
|--------|------------|-------------------------|
| 角色 | 传统 | Harness Engineering |
| 写代码 | 主要工作 | 从不 |
| 设计架构 | 工作一部分 | 主要工作 |
| 写文档 | 事后考虑 | 关键基础设施 |
| 审查PRs | 代码审查 | 审查智能体输出+ harness有效性 |
| 调试 | 读代码 | 分析智能体行为模式 |
| 测试 | 写测试用例和测试策略 | 设计智能体执行的测试策略 |
3.2 Stripe方式：Minions at Scale（Minions大规模应用）
- 每周1000+合并的PR；
- 开发者在Slack发布任务 → Minion写代码 → 通过CI → 打开PR → 人类审查；
- 无开发者交互在任务发布和PR打开之间；
- 通过MCP服务器访问400+内部工具。
关键洞察：智能体需要与人类工程师相同的上下文和工具，而不是附加的、事后整合的东西。
3.3 LangChain方式：Middleware-First（中间件优先）
Agent Request
→ LocalContextMiddleware (映射代码库)
→ LoopDetectionMiddleware (防止重复)
→ ReasoningSandwichMiddleware (优化计算)
→ PreCompletionChecklistMiddleware (强制验证)
→ Agent Response
每个中间件层添加特定能力，而不修改核心智能体逻辑。这种模块化方法使Harness可测试和可演进。
3.4 Mitchell Hashimoto方法
每当智能体犯错时，都是改进Harness的机会。将错误转化为系统性的改进，而不是一次性的修复。
Mitchell Hashimoto 的AI时代编程方法概括：
1 ）AI 协作：从"聊天"到"智能体工程"
- 核心纪律："始终保持一个智能体在运行"：每天工作结束前花30分钟，给AI智能体（如 Claude Code）分配任务，让它在夜间或他处理其他事务时，进行调研、代码重构或编写测试。他坚信，AI 在工作时间内不应该闲置，应该利用一切时间"异步"完成工作。
- 协作模式：像指导"初级工程师"一样指导 AI：他不会给 AI 开放式、模糊的任务。相反，他会像给团队里的新人布置工作一样，提供非常具体、有明确边界和"护栏"的问题，并清晰地指定架构和数据流应该是什么样的。
- " 工具工程"（Harness Engineering） ：这是 Mitchell 提出的一个核心概念。当 AI 犯错时，他的第一反应不是单纯地修正错误，而是构建一个工具（如一个验证脚本、一个测试用例或一个 Linting 规则），让 AI 下次能自己调用这个工具来检查和避免重复犯错。这种做法会随时间产生复合效应，让 AI 越来越可靠。
- 并行运行"AI 锦标赛"：对于难度高或重要的任务，他有时会同时在多个代码库副本上运行不同的 AI 模型或智能体（如 Claude 和 Codex），然后选择效果最好的那个结果。
2 ）项目管理：通过"演示"驱动
即使在开发 Ghostty 这样复杂的大型项目时，Mitchell 也坚持"通过演示驱动开发"。
- 每周至少做 1-2 次演示 ：他主张将大型任务分解成能产生切实的、可演示的进展的块。即使是后端项目，也应尽早通过自动化测试或原型 UI 来获得反馈。
- 目标导向：演示不仅能验证技术可行性，更重要的是能让自己和团队保持兴奋度和对产品的感觉，确保项目始终朝着正确的方向前进。
3 ）质量控制：上下文相关的实用主义
Mitchell 对代码质量的要求是分层的，完全取决于项目的生命周期和重要性。
- 逐行审查（高严格） ：对于 Ghostty 这类需要长期维护、对性能极其敏感（例如追求每帧 9 微秒）的核心项目，他会审查每一行 AI 生成的代码，确保其可维护性和架构一致性。
- 零审查（低严格）：对于只使用两个月的一次性项目（如家庭婚礼网站），他的标准是"在三个浏览器里渲染正确就行，上线吧"。
- AI 贡献默认拒绝：由于收到了太多低质量的 AI 生成 PR，Mitchell 现在对 Ghostty 的贡献者采取了"默认拒绝"的态度，如果没有关联的 Issue 编号，他会直接关闭 PR 甚至不读。
4 ） 技术栈与性能：锐意创新
- 选择 Zig ：在构建 Ghostty 时，他选择了新兴的系统编程语言 Zig，而不是更主流的 Rust。他认为 Zig 提供了更好的性能和与 C 语言的互操作性，同时也更符合他对"无隐藏控制流"的偏好。
- 直面 AI 局限 ：他坦承，即使是顶尖的 AI 模型，在处理 Zig 代码的复杂修改时也几乎"毫无希望"。他的一个巧妙应对方法是：让 AI 先用它擅长的语言（如 C、Python）写出解决方案，然后他亲自将其翻译成 Zig。
5 ） 核心哲学
- 选择你思考的内容 ：AI 的价值不是让你产出更多行代码，而是将你的认知能力从重复劳动中解放出来，重新聚焦在架构、设计和真正满足用户需求上。
- 保持掌控 ：他明确将自己定义为项目的"架构师"。AI 是实现目标的工具，但关于"状态存在哪里"、"数据流如何设计"等关键决策，必须由他自己做出。
- 热爱可抵岁月漫长：无论是从估值 50 亿公司的 CTO 职位上退下来成为全职程序员，还是自学编程时的执着，都体现了他对编程本身最纯粹的热爱。
Mitchell Hashimoto 的编程方法为开发者提供了一个非常有价值的参考：如何在 AI 能力爆发的时代，既充分利用工具提升效率，又坚守工程师本质，将人类的智慧投入到最具创造性的部分。
4 构建自己的Harness
4.1 Level 1：基础Harness（单个开发者）
搭建时间：1~2小时
系统设置：
- CLAUDE.md或.cursorrules文件，包含项目约定；
- Pre-commit hooks用于linting和格式化；
- 智能体可以运行的测试套件，用于自我验证；
- 具有一致命名的清晰目录结构。
影响：防止最常见的智能体错误
4.2 Level 2：团队Harness（3-10人团队）
搭建时间：1~2天
系统设置：
- AGENTS.md包含团队范围约定；
- CI强制的架构约束；
- 共享prompt模板；
- 文档即代码，由linter验证；
- 专门针对智能体生成PR的代码审查清单。
影响：团队中智能体行为的一致性。
4.3 Level 3：生产Harness（工程组织）
搭建时间：1~2周
系统设置：
- 自定义中间件层：目录映射、循环检测、推理优化、强制验证；
- 可观测性集成：智能体读取日志、指标、跟踪、git历史、运行结果；
- 熵管理智能体定时运行：后台运行、垃圾清理；
- Harness版本控制和A/B测试；
- 智能体性能监控仪表板；
- 智能体卡住时的升级策略。
影响：智能体作为自主贡献者运营
5 常见错误与教训
5.1 过度工程化控制流
过度工程化控制流，下次模型更新可能会破坏整个系统。2024年需要复杂流水线的功能，现在可能只需要一个简单的提示。构建Harness时，要可剥离：当模型足够聪明，应该能够移除"智能"逻辑。
Harness 设计两分离：
1）思考和执行分离； 2）控制流和控制策略分离
5.2 将Harness视为静态
Harness需要随模型演进。当新模型发布改进了推理时，推理优化中间件可能变得适得其反。在每个主要模型更新时，审查和更新Harness组件。
5.3 忽略文档层
最有效的Harness改进通常是：最简单：更有效的文档。
如果AGENTS.md模糊，智能体输出就会模糊。投资精确的、机器可读的文档，作为智能体编程的ground truth（基准事实/真实值）。
5.4 无反馈循环
没有反馈的Harness是牢笼，而非指南。需要构建：
- 任务完成前的自我验证步骤；
- 作为智能体工作流一部分的测试执行；
- 按任务类型的智能体成功率指标。
6 展望未来
6.1 趋势
1）多模型系统：Codex、Gemini和Claude组合使用，在不同阶段使用不同模型；
2）记忆原语：持续学习，让智能体能够自主改进任务；
3）自适应推理：模型自己决定在每项任务上花费多少计算（已见于Claude和Gemini）。
6.2 挑战
1 ）Context Windows的物理限制：有效上下文窗口往往远小于广告的Token限制；
2 ）安全性：智能体吞吐量改变了代码库的风险状况；
3）Retrofitting Existing Codebases（重构现有代码库）：为现有应用添加Harness是否值得？
6.3 哲学思考
随着模型变得越来越强大，我们不应该构建更多的脚手架，而应该让模型自由发挥。
Context Engineering不是添加更多上下文，而是找到下一步所需的最小有效上下文。
7 总结
Harness Engineering代表了软件工程的根本性转变。从"写代码"到"设计环境"。从"自己做事"到"管理和指挥智能体"。
Harness Engineering不是对人类工程师的替代，而是角色的进化。工程师不再是代码的生产者，而是系统的设计者 和智能体的管理者。
关键洞察：
- 模型是商品，Harness是护城河；
- 约束产生自由和高效；
- 文档即代码：文档设计是系统设计的重要组成部分；
- 渐进式披露：设计地图，而不是工程师手册；
- 自动化品味；
- 反馈驱动。
如果正在构建AI驱动的应用开发，Harness Engineering不是可选的 ------ 它是让智能体真正可用的必要条件。
附录A：AGENTS.md模板
AGENTS.md - 项目智能体指南
构建和测试
运行测试: `npm test`
构建: `npm run build`
Linting: `npm run lint`
架构概述
主要模块: `/src/components`, `/src/hooks`, `/src/utils`
状态管理: 使用Zustand
API层: `/src/api`
安全
不要提交secrets到git
使用环境变量
Git工作流
功能分支: `feature/xxx`
PR前运行测试
约定
组件使用TypeScript
样式使用Tailwind CSS
提交信息遵循Conventional Commits
参考链接
|----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 资源 | 链接 |
| OpenAI Harness Engineering | https://openai.com/index/harness-engineering/ |
| Martin Fowler | https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html |
| Anthropic | https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents |
| LangChain | https://blog.langchain.com/improving-deep-agents-with-harness-engineering/ |
| GTCode Guide | https://gtcode.com/articles/harness-engineering/ |
| NxCode Guide | https://www.nxcode.io/resources/new |