此文是《Harness Engineering橙皮书：AI编程时代的工程方法论》读书笔记整理。

最近读完这本书，感觉干货满满，整理一下，方便自己，方便他人。

一、这本书真正想解决什么问题

这本书表面上在讲 Harness Engineering：给 AI agent 设计指令、约束、工具、记忆、反馈和编排，让它不只是会聊天，而是能在真实工程环境里稳定干活。

它真正想解决的问题不是「怎么让 AI 更聪明」，而是「在 AI 已经足够强但还不稳定的情况下，人应该怎样重新设计工作系统」。以前我们把注意力放在 prompt 上，后来放在 context 上，但真实项目的问题更硬：AI 会误解、偷懒、幻觉、重复犯错、写出自己也没验证过的代码。靠一句提示词管不住这些问题。

这本书和我现在最相关的一点是：我已经不是单纯在“使用 AI”，而是在用 AI 做开发、写作、写产品相关文档，以及做长期项目。真正影响结果的，不是某次对话质量，而是我有没有把经验沉淀成规则、工具、知识库和反馈循环。

如果只带走一个判断：AI 编程时代，人的核心价值不是亲手写更多代码，而是设计一个能让 AI 持续产出、持续纠错、持续积累的工作环境。

二、核心概念

1. Harness：AI 的工作环境，不是提示词

这是什么

Harness 是 AI 可以行动的那套壳：能读文件、改代码、跑测试、查资料、调用工具，也有规则、边界和反馈。模型是脑子，Harness 是手脚、护栏和仪表盘。

用在什么场景

适合真实项目：iOS App、AI 工具、写作工作流、独立产品迭代。不适合一次性闲聊或简单问答。误用是把 Harness 当成“更长的 prompt”，把所有规则塞进一个文件，最后反而污染上下文。

怎么用

给每个长期项目建一个轻量入口文件，比如 AGENTS.md / CLAUDE.md：只写 AI 从代码里看不出来的信息，例如构建命令、测试方式、项目禁区、发布流程、常犯错误。

实践步骤

• 1. 从空文件开始，不预设一堆规则。
• 2. 每次 AI 犯错，只加一条能防止复发的规则。
• 3. 每周删除 AI 能自己从代码推断出的规则。
• 4. 把复杂规范拆到独立文档，入口文件只做地图。
• 5. 规则是否有效，用“同类错误有没有复发”判断。

2. 反馈层：让 AI 必须验证自己的工作

这是什么

反馈层不是让 AI 说“我检查过了”，而是给它可执行的验证手段：测试、lint、截图、日志、Playwright、DevTools、CI。

用在什么场景

适合所有会产生结果的任务：写代码、改 UI、写文章、做产品页。不适合纯概念讨论。误用是让生成者自评，AI 很容易满足于“看起来可以”。

怎么用

开发中，每次改动后必须跑最小验证；
写作中，每篇文章用独立会话审稿；
产品设计，则用截图和用户路径验证，而不是只看代码。

实践步骤

• 1. 给项目列出 3 个最小验证命令。
• 2. 在规则文件里写清楚“改完必须跑哪些检查”。
• 3. UI 改动必须看截图，不只看源码。
• 4. 复杂任务开一个全新会话做 Reviewer。
• 5. 验证失败时先修 Harness，再修单点输出。

3. 记忆层：让错误变成复利

这是什么

记忆层解决“这次踩过的坑，下次别再踩”。它可以是 MEMORY.md、项目知识库、复盘日志，也可以是规则文件里的新增约束。

用在什么场景

适合长期项目、系列文章、App 迭代、AI 工作流。不适合短期一次性任务。误用是把记忆当垃圾桶，什么都往里丢，最后 AI 找不到重点。

怎么用

应该把 AI 协作中的高频错误、项目背景、写作口味、发布步骤沉淀下来，但控制在 100 行以内。记忆不是资料库，记忆是决策偏好和历史教训。

实践步骤

• 1. 建一个项目级 MEMORY.md。
• 2. 只记录“AI 无法从文件推断的信息”。
• 3. 每条记忆都对应一个真实错误或稳定偏好。
• 4. 每两周压缩一次，删除过时内容。
• 5. 观察 AI 是否减少重复解释成本。

4. 编排层：从一个 AI 干活到多个 AI 协作

这是什么

编排层是任务拆分和角色安排：Planner 负责计划，Generator 负责实现，Evaluator 负责挑错。多 agent 的关键不是数量，而是角色边界。

用在什么场景

适合复杂功能、长文章、重构、调研、上线前检查。不适合简单任务。误用是同时开很多会话但没有隔离工作区和明确目标，最后冲突更多。

怎么用

独立开发场景，一个会话写需求，一个会话实现，一个新会话审查；
写作场景，一个会话出结构，一个会话写正文，一个会话挑逻辑漏洞。

实践步骤

• 1. 复杂任务先让 Planner 写计划。
• 2. 实现会话只负责执行，不扩展需求。
• 3. 审查会话必须是全新上下文。
• 4. 并行开发时每个任务用独立 worktree。
• 5. 合并前由人判断结构、取舍和风险。

三、对我真正有用的 4 个点

1. 不要发布自己不理解的代码

Insight

AI 可以写实现，但责任不能外包。真正危险的不是 AI 写错，而是我因为省事接受了自己无法解释的东西。

我的理解

我可以让 AI 写 iOS App、Java 工具类、脚本、测试，但架构边界、数据流、状态管理必须自己看懂。看不懂就不合并，这条线不能松。

如何用在我身上

我的开发工作里，AI PR 合并前必须能回答三个问题：改了什么、为什么这样改、坏了怎么回滚。答不上来就继续拆小。

2. 规则应该从错误里长出来

Insight

提前写 500 行规则通常是在制造噪音。真正有价值的规则来自真实失败。

我的理解

我以前容易把“理想工作方式”写成规范，但 AI 不会因为规范漂亮就遵守。更好的方式是等它犯错，然后把错误工程化成约束。

如何用在我身上

我的每个新项目都从一个空 AGENTS.md 开始：构建命令、测试命令、禁止事项，然后每次踩坑补一条。

3. 评估者要独立

Insight

让同一个 AI 自己写、自己审，天然会漏。它会偏爱自己的第一个方案。

我的理解

这点可以迁移到写作。我写完文章后，不应该让同一个上下文“润色一下”，而应该开新会话让它专门找逻辑漏洞、废话和不成立的判断。

如何用在我身上

写作流程改成三步：结构会话、正文会话、审稿会话。
审稿只允许指出问题，不允许直接改成一篇更“顺”的废话。

4. 上下文不是越多越好

Insight

上下文太长会腐烂，失败方案会污染后续判断。修两次还错，继续补丁式纠正往往更差。

我的理解

我需要更果断地清空重来。尤其是调 bug、写复杂逻辑、做 UI 时，如果 AI 连续两轮走偏，就应该重开上下文，给它干净的状态和更窄的问题。

如何用在我身上

我的开发和写作都可以采用“二次失败重启规则”：同一个问题纠正超过两次，就生成当前状态摘要，重开会话继续。

四、经验、反直觉点和被忽略的细节

最反直觉的是：AI 越强，越需要工程纪律。模型能力提升不会自动带来可靠产出，反而会让人更容易过度信任它。

容易忽略的是基础设施。Stripe 的案例说明，AI PR 能跑起来，不只是模型强，而是团队本来就有测试、部署、回滚和审查信号。个人开发也一样，没有测试和发布清单，AI 只会把混乱放大。

一个容易误用的观点是“多 agent 并行”。并行不是同时开很多窗口，而是任务可隔离、结果可验证、冲突可合并。否则只是把上下文切换成本转嫁给自己。

此外，我们还要保持怀疑：书里很多高产案例证明了速度，但没有完全证明长期可维护性。AI 写出的代码是否能在半年后继续演进，仍然需要靠架构、测试和人的判断来兜底。

五、读完此书，接下来需要做的事 - 可执行清单

一个可以立刻尝试的小实验

今天选一个小功能或一篇短文，用三个会话完成：第一个只规划，第二个只执行，第三个只审查。不要让同一个会话包办到底。看最终返工次数是否下降。

一个长期可以坚持的习惯

每周做一次 Harness 垃圾回收：删掉过时规则、合并重复规则、补充真实错误、压缩记忆文件。记录文件行数和重复错误次数。

六、未来应该避免什么

避免把时间花在收藏提示词上。真正影响长期产出的，不是某句神奇 prompt，而是项目自己的规则、反馈和记忆。

避免让 AI 写完后只看解释不看结果。AI 的解释经常很顺，但结果要靠测试、截图、日志和 diff 判断。

避免把规则文件写成百科。语言惯例、框架常识、AI 能从代码里读出来的东西，不值得占上下文。

避免接受自己看不懂的实现。短期像省时间，长期会变成无法维护的债务。

避免在一个失败上下文里无限纠正。连续两次走偏，就应该重开，而不是继续把错误路径加厚。

七、一句话总结

这本书真正改变我的，是把“使用 AI”的问题，改成了“设计一个让 AI 不断变可靠的系统”的问题。

2026.05.06 19:58
沪·赵巷

📌 声明：本文由 AI 辅助完成