HarnessEngineering橙皮书AI编程时代的工程方法论

一、全书概览

花叔的橙皮书系列出到第四本，这本是整个系列的"方法论天花板"。

整本书围绕一个核心问题展开：AI 能写代码之后，人的核心能力是什么？

答案是：Harness Engineering——给 AI 造缰绳的工程方法论。

书的开头就用一个炸裂的数据开场：OpenAI 的 Codex 团队，7 个人，5 个月，零行手写代码，交付了一个 100 万行的产品。模型没换，换的是套在模型外面的那层东西。这层东西叫 Harness。

Harness 的英文原意是马具、缰绳。AI 模型是马，力气再大，没有缰绳就是一匹乱跑的野马。这个比喻贯穿全书，简单粗暴但极其精准。

全书结构清晰，五个部分层层递进：

起源篇（第 1-3 章）：从马具到航天线束到 AI 编程，追溯这个词的演变，梳理软件工程六十年简史
框架篇（第 4-5 章）：拆解 Harness 的五个组件，以及一个反直觉的核心原则——Harness 不是越多越好
案例篇（第 6-12 章）：全书最厚部分，7 个深度案例拆解
实操篇（第 13-17 章）：以 Claude Code 为核心，从空白项目开始逐层构建完整 Harness
思考篇（第 18 章）：在没人写代码的时代，谁来设计下一代的缰绳

这本书不是 AI 工具使用手册，而是工程方法论。花叔自己也说得很明白——适合已经在用 AI 编程工具、想从"对话式使用"升级到"系统化协作"的人。

二、逐章要点

第 1 章：Harness 到底是什么

开篇定义了全书的坐标系：Agent = Model + Harness。你不是模型，那你就是 Harness。

这个公式把 AI 编程领域分成了两个阵营：做模型的人和做 Harness 的人。绝大多数开发者和团队，属于后者。模型决定上限，Harness 决定底线。

书中给出的定义是：Harness 就是模型之外的一切——系统提示词、工具调用、文件系统、沙箱环境、编排逻辑、钩子中间件、反馈回路、约束机制。模型本身只是能力的来源，只有通过 Harness 把状态、工具、反馈和约束串起来，它才真正变成一个可用的 Agent。

第 2 章：六十年简史——人和工具的关系

从 1960 年代 Fortran 到 2026 年的 Claude Code，软件工程六十年的核心矛盾一直是：人要做什么，工具要做什么。

书里梳理了一条清晰的时间线：

1960s-1970s：手写汇编和 Fortran，人做一切
1980s-1990s：IDE 和编译器出现，工具开始辅助
2000s：敏捷运动，强调人的协作
2009-2014：DevOps——描述你要什么，而不是怎么做
2024-2026：AI Agent——描述你要什么，AI 直接做

每一轮变迁都在把人的工作往上推一层。从"手写代码"到"描述需求"，这个趋势不可逆。

第 3 章：三次命名

书中追溯了 Harness 这个词三次被赋予工程含义的过程：

马具——原意，控制马匹的装备
航天线束——NASA 用来描述连接各子系统的线缆总成
AI 编程 Harness——Mitchell Hashimoto 在博客中首次使用这个说法（"我不知道业界有没有公认的术语，我自己管这叫 harness engineering"），之后 OpenAI、Anthropic 纷纷跟进

这个词从"控制"到"连接"再到"赋能"的语义变迁，本身就反映了人机关系的演变。

第 4 章：Harness 的五个组件

这是全书的骨架章节。花叔从"模型做不到什么"出发，推导出 Harness 要补什么：

| 模型做不到的 | Harness 怎么补 | 核心组件 | |---|---|---| | 记住多轮对话历史 | 每次请求时拼进上下文 | 记忆系统 | | 执行代码、跑命令 | 提供 Bash + 代码执行环境 | 执行能力 | | 获取实时信息 | Web Search、MCP 工具 | 外部知识 | | 操作文件和环境 | 文件系统抽象 + Git | 工具系统 | | 知道自己做对了没有 | 沙箱 + 测试 + 浏览器自动化 | 反馈机制 | | 在长任务中保持连贯 | 上下文压缩、进度追踪 | 编排逻辑 |

花叔把这套东西浓缩为五个字：指令、约束、反馈、记忆、编排。

第 5 章：少即是多——减法哲学

这是全书最反直觉的一章。

很多人的第一反应是：既然 Harness 这么重要，那就做得越厚越好、规则越多越好、约束越严格越好。花叔用大量案例反驳了这种想法：

AGENTS.md 写成千页手册？Agent 上下文窗口被撑爆，反而更蠢
每一步都加校验？Agent 被"保护"到寸步难行
规则越加越多？维护成本指数增长，最后没人看得懂

Harness 不是越多越好，而是越精准越好。 每一条规则都应该对应一个真实发生过的失败案例。没有失败案例支撑的规则，就是噪音。

Anthropic 自己也验证了这一点：模型越强，之前必要的保护机制可能已经冗余了。需要定期"压力测试"你的 Harness，把不再需要的组件砍掉。

第 6 章：OpenAI Codex——零行手写代码的百万行产品

全书最炸裂的案例。数据再列一遍：

3 名工程师（后扩至 7 人）
5 个月（2025 年 8 月起）
约 100 万行代码
手写代码：0 行（设计约束）
约 1,500 个合并 PR
日均 PR/人 3.5 个
效率提升约 10 倍

他们总结出五大方法论：

地图式文档：AGENTS.md 只有约 100 行，当目录用，指向更深层的设计文档。渐进式披露，需要什么加载什么
机械化约束：自定义 Linter，报错消息里直接告诉 Agent 怎么改。原话："If it cannot be enforced mechanically, agents will deviate"
可观测性接入：Chrome DevTools Protocol 接入 Agent 运行时，Agent 能自己抓 DOM 快照、截图
熵管理：后台 Agent 定期扫描，自动提交清理 PR。生成速度和清理速度必须匹配
仓库即事实源：写在 Slack 里的知识对 Agent 来说等于不存在

第 7 章：Mitchell Hashimoto——每次犯错加一条规则

Vagrant、Terraform、Ghostty 的作者，走的是完全不同的路线——坚持单 Agent，一个人深度参与。

他的六步进阶路线：

放弃聊天模式：让 Agent 在能读文件、跑程序、发 HTTP 请求的环境里直接干活
复现自己的工作：每件事做两次——一次自己做，一次让 Agent 做，他形容"痛苦至极"
下班前启动 Agent：每天最后 30 分钟给 Agent 布置任务：深度调研、模糊探索
外包确定性任务：挑出 Agent 几乎一定能做好的任务后台跑

他的核心信念：每犯一次错，就在 AGENTS.md 里加一条规则。 这个文件就是他个人工程经验的结晶，每一行都对应一个真实的失败案例。

第 8 章：Anthropic——让 AI 查 AI

Anthropic 提出了一个受 GAN（生成对抗网络）启发的三智能体架构：

Planner（规划者）→ Generator（执行者）⇄ Evaluator（评估者）

Planner：拿到 1-4 句话的产品描述，扩展成完整产品规格
Generator：按功能一个一个做 Sprint
Evaluator：用 Playwright MCP 实际点击运行中的应用，多维度打分

关键设计：生成和评估交给两个独立的 Agent。因为 Agent 自评会"自信满满地夸自己做得好，实际质量一般"。这个拆分解决了 AI 编程中最大的信任问题。

第 9 章：Stripe Minions——每周 1300 个 PR 的流水线

Stripe 代表了高度自动化的无人值守模式。开发者发一条 Slack 消息，Agent 从写代码到跑 CI 到提 PR 全部搞定，人只在最后审查。

架构亮点：

Devbox：AWS EC2 预装源码和服务，预热池分配，启动约 10 秒。"牲口不是宠物"
混合编排状态机：该确定的地方确定（跑 lint、推送），该灵活的地方灵活（实现功能、修 CI）
Toolshed MCP：近 500 个工具的集中式服务，每个 Minion 获得筛选子集
反馈回路：Pre-push hook 秒级修 lint；推送后最多 2 轮 CI（300 万+ 测试）

核心理念："What's good for humans is good for agents."——Agent 应该跟人类工程师用同一套基础设施，只是从一开始就被当作一等公民来设计。

第 10 章：LangChain——同一匹马，换套缰绳

这个案例直接证明了"瓶颈不在模型"。

同一模型，只换了工具调用格式（Harness），编码基准分数从 6.7% 跳到 68.3%。模型没变，变了的是外围系统。

LangChain 在 Terminal Bench 2.0 上优化了 Agent 运行环境后，从全球第 30 名升到第 5 名，得分从 52.8% 提升到 66.5%。模型没换，Harness 换了。

但这里有个坑值得注意：model-harness 耦合问题。Claude Code 等工具是模型和 Harness 一起训练的，换工具逻辑后模型表现会变差。Opus 在 Claude Code 中的 Harness 下得分，远低于它在其他 Harness 中的得分。

第 11 章：Kent Beck——极限编程教父的 CLAUDE.md

Kent Beck，XP（极限编程）的发明者，30 年软件工程智慧的集大成者。他把这些东西浓缩进了一个 CLAUDE.md 文件。

这个案例的价值在于：好的 Harness 不是发明出来的，是从经验中长出来的。 Beck 的每一行配置背后都是几十年的工程实践沉淀。

第 12 章：花叔——零代码经验到百万用户

作者自己的故事。没有编程背景，靠 AI 编程做出了百万用户产品。

这个案例的价值不在技术细节，而在视角转换：当 Harness 做得足够好，"会不会写代码"这个前提条件就被消解了。 这对产品经理、设计师、创业者来说，是一个巨大的信号。

第 13-17 章：实操篇——从空白开始构建 Harness

以 Claude Code 为核心（兼顾 Codex 和 Cursor），五步走：

第 13 章：从空白项目开始，搭建第一个 Harness 骨架
第 14 章：指令层——给 AI 一张地图，不是一本千页手册
第 15 章：约束层——建议和约束是两回事。约束必须机械化执行
第 16 章：能力层与记忆层——让 AI 能做事、能记住事
第 17 章：编排层——让十匹马同时跑，多 Agent 协作

实操篇的核心原则：渐进式构建，不要试图一步到位。 先搭骨架，再根据实际使用中的问题逐层补齐。

第 18 章：经验工程——谁来设计下一代的缰绳

全书收尾提出一个开放问题：在没人写代码的时代，"工程经验"的定义会发生什么变化？

如果代码都是 AI 写的，那理解系统架构、设计 Harness、做技术决策的能力，就变成了新的"核心工程能力"。花叔称之为"经验工程"——把人的经验变成可复用、可迁移的系统。

三、关键概念速查

1. Harness（缰绳）

模型之外的一切工程系统。包括系统提示词、工具调用、文件系统、沙箱环境、编排逻辑、反馈回路、约束机制。公式：Agent = Model + Harness。

2. 上下文焦虑（Context Anxiety）

模型在上下文窗口快填满时表现急剧下降的现象。Anthropic 发现 Sonnet 4.5 在上下文快满时会变得犹豫，倾向于提前收工。经验法则：上下文利用率控制在 40% 以内。

3. Context Resets（上下文重置）

Anthropic 的解决方案：不压缩上下文，而是启动一个全新的"干净"Agent，通过结构化交接文档恢复状态。类比：程序内存泄漏时直接重启进程，而不是手动释放每个内存块。

4. 渐进式披露（Progressive Disclosure）

给 Agent 信息的策略：先给最关键的信息（地图），需要时再加载细节（具体页码）。AGENTS.md 约 100 行当目录用，详细规则按需加载。不要把所有东西塞进一个文件。

5. 熵管理（Entropy Management）

AI 生成代码的"腐烂速度"远快于人类写的代码。必须主动对抗——定期扫描、自动清理、提交修复 PR。生成速度和清理速度必须匹配，否则技术债会快速积累到不可控。

6. Model-Harness 耦合

当前 Agent 产品是模型和 Harness 一起训练的，导致过拟合：换了工具逻辑后模型表现会变差。选择 Harness 时，不要被模型的默认 Harness 束缚。

7. GAN 式三智能体架构

Anthropic 借鉴 GAN 思路的设计：Planner（规划）→ Generator（执行）⇄ Evaluator（评估）。核心价值是把"生成"和"验证"拆给两个独立的 Agent，解决自我评价偏差。

四、核心框架/模型

Harness 五组件模型

花叔提炼的五个核心组件，构成了 Harness 的最小完整集合：

指令（Directive）    → 告诉 AI 做什么、怎么做
约束（Constraint）   → 告诉 AI 不能做什么，必须机械化执行
反馈（Feedback）     → 让 AI 知道自己做对了还是做错了
记忆（Memory）       → 让 AI 记住之前发生过什么
编排（Orchestration）→ 让多个 AI 协同工作

六层架构体系

从系统设计角度，成熟的 Harness 有六个层次：

| 层级 | 名称 | 解决什么问题 | 类比 | |---|---|---|---| | L1 | 信息边界层 | Agent 该知道什么 | 岗位说明书 | | L2 | 工具系统层 | 怎么跟外部交互 | 办公工具 | | L3 | 执行编排层 | 多步骤怎么串起来 | SOP 标准流程 | | L4 | 记忆与状态层 | 中间结果怎么管 | 项目管理系统 | | L5 | 评估与观测层 | 怎么知道做对了 | 质检流程 | | L6 | 约束校验恢复层 | 出错了怎么办 | 红线规则+应急预案 |

优先级建议：先做 L1（信息边界）和 L6（约束与恢复），这两层投入产出比最高。中间层次随项目复杂度逐步补齐。

Harness 成熟度模型

| 阶段 | 特征 | 工程师角色 | |---|---|---| | Level 0 | 无 Harness，直接给 prompt | 手动写代码 + 偶尔用 AI | | Level 1 | AGENTS.md + 基础 Linter | 主要写代码，AI 辅助 | | Level 2 | CI/CD + 自动化测试 + 反馈回路 | 规划 + 审查为主 | | Level 3 | 多 Agent 分工 + 分层上下文 | 环境设计 + 管理 | | Level 4 | 无人值守 + 自动熵管理 + 自修复 | 架构师 + 质量把关 |

三层工程方法嵌套关系

Prompt Engineering、Context Engineering、Harness Engineering 不是并列关系，而是嵌套关系：

Prompt Engineering（表达层）：怎么写好指令，让模型听懂意图
Context Engineering（信息层）：给 Agent 看什么，确保拿到正确信息
Harness Engineering（执行层）：整个系统怎么防崩、怎么持续运转

简单任务里提示词最重要；依赖外部知识的任务里上下文很关键；在长链路、可执行、低容错的真实商业场景里，Harness 才是决定成败的东西。

五、金句摘录

"模型决定上限，Harness 决定底线。" —— 全书最核心的一句话。与其纠结选哪个模型，不如先把 Harness 搭好。
"If it cannot be enforced mechanically, agents will deviate." —— OpenAI Codex 团队的原话。文档里写约束不够，必须靠工具强制执行。
"我必须不断提醒自己，我是在为 Claude 写这个测试框架，不是为自己写。" —— Carlini 用 16 个 Agent 写 C 编译器后的感悟。Harness 的设计目标是让 Agent 高效工作，不是为了人类方便。
"What's good for humans is good for agents." —— Stripe Minions 的设计哲学。Agent 应该用跟人类工程师同一套基础设施。
"Every component in a harness encodes an assumption about what the model can't do on its own, and those assumptions are worth stress testing." —— Anthropic。Harness 中的每个组件都编码了一个"模型做不到"的假设，这些假设值得定期压力测试。
"The space of interesting harness combinations doesn't shrink as models improve. Instead, it moves." —— Anthropic。模型越强，不是不需要 Harness 了，而是 Harness 的设计空间转移到了新的位置。
"写在 Slack 里的知识，对 Agent 来说等于不存在。" —— OpenAI。所有团队知识都必须作为版本控制的制品放在仓库中。

六、行动清单

每天

[ ] 维护 AGENTS.md：每次 Agent 犯错，加一条对应规则。确保每条规则都有真实失败案例支撑，没有案例的规则就是噪音
[ ] 检查上下文利用率：如果超过 40%，触发压缩或 context reset。不要等到 Agent 开始变蠢再处理
[ ] 代码审查时问自己：这个错误是模型能力问题还是 Harness 设计问题？80% 的情况是后者

每周

[ ] 审查 AGENTS.md：删掉不再需要的规则。模型在进化，去年必要的约束今天可能已经冗余
[ ] 熵管理检查：扫描 AI 生成物中的低质量代码、文档不一致、冗余实现。生成速度和清理速度必须匹配
[ ] 测试 Harness 假设：挑一个 Harness 组件，临时移除它，看 Agent 表现是否变差。如果没变差，这个组件就是多余的
[ ] 更新知识仓库：把 Slack 讨论中的重要决策、架构变更写进仓库文档。Slack 里的知识对 Agent 等于不存在

每月

[ ] 评估 Harness 成熟度：对照 Level 0-4 模型，判断当前阶段，规划下一步
[ ] 尝试减少一层约束：Anthropic 的经验——模型越强，Harness 应该越薄。定期做减法
[ ] 复盘 Agent 协作模式：单 Agent 够用还是需要多 Agent 分工？参考 Hashimoto（单 Agent）vs Carlini（16 个 Agent）的两种极端
[ ] 更新团队知识仓库化进度：确保所有关键知识都在仓库中，而不是散落在 Wiki、Slack、Notion 各处

七、一句话总结

承认模型有边界，然后把边界之外的需求一个个工程化地补上——这就是 Harness Engineering 的全部。

八、读者热议

1. "棕地项目怎么办？"

这是目前被讨论最多的问题。书中所有成功案例——OpenAI、Anthropic、Stripe、Hashimoto——全部是在全新项目上从零搭 Harness。但现实中绝大多数团队面对的是跑了多年的代码库，有历史架构、技术债、遗留逻辑。怎么把 Harness 引入一个十年历史的项目？目前没有任何公开方法论。

Martin Fowler 团队的 Birgitta Böckeler 把这比作"在从没用过静态分析的代码库上跑静态分析"。她提出了"Ambient Affordances"概念：环境本身的结构特性（类型系统、模块边界、框架抽象）决定了 Harness 能做多好。这意味着，在一个架构混乱的项目上，Harness 的效果天花板天然就低。

2. "AI 生成代码的长期可维护性呢？"

LLM 生成的代码经常重新实现已有功能（Carlini 在编译器项目中专门安排了一个"去重 Agent"来处理这个问题）。Greg Brockman 提出过这个问题，至今无人回答。一个月后代码是否还能看懂？半年后能否安全修改？三年后技术债会不会压垮整个项目？

这些问题的答案，需要时间来验证。但有一个共识正在形成：如果没有熵管理机制（定期清理、自动去重、架构守卫），AI 生成代码的腐烂速度会远快于人类写的代码。

3. "Agent 写的代码用 Agent 的测试来验证，这靠谱吗？"

Böckeler 直接批评了这个做法："用 AI 生成的测试来验证 AI 生成的代码，本质上是'用同一双眼睛检查自己的作业'——that's not good enough yet。"

Anthropic 的解决方案是把生成和评估拆给两个独立的 Agent（GAN 式架构），这是一个进步，但并没有从根本上解决问题。两个基于同一个模型的 Agent，共享同样的盲区。

Stripe 的方案更务实：最终审查环节还是人来做。每周 1300 个 PR 全程无人值守，但最后一步——合并前的审查——人还是在的。这可能是目前最务实的平衡点。

4. "单 Agent 还是多 Agent？"

Hashimoto 坚持单 Agent，认为"多 Agent 增加了不必要的复杂性"。Carlini 用 16 个并行 Agent 写了个 C 编译器。Stripe 用数百个 Minion 并行处理 PR。

花叔没有给出非此即彼的答案，但提供了一个判断标准：规模决定。小项目单 Agent 够用，大项目几乎必然需要专业化分工。关键是找到你自己项目规模对应的平衡点。

笔记生成：2026-04-28 by 喵喵 🐈

📚 喵喵的笔记库

探索