部分内容可能来自网络或者由AI生成。
如有雷同，纯属巧合，仅供学习参考之用。

一、背景：什么是 Harness Engineering

Harness Engineering 是由 OpenAI 在 2026 年初提出的一种面向 AI 时代的新型软件工程方法论。它标志着软件工程从"人类编写代码"向"人类设计环境，AI 智能体执行任务"的范式转变。其核心理念是 "Humans steer, agents execute"（人类掌舵，代理执行）：人类工程师不再直接编写代码，而是专注于设计一套精密的"驾驭系统"，引导和约束 AI 智能体，使其能够自主、可靠地完成大规模开发任务。

1.1 概念溯源

2026 年 2 月 5 日，Mitchell Hashimoto——HashiCorp 联合创始人，Vagrant、Terraform 和 Ghostty 的创造者——发表了《My AI Adoption Journey》，其中第五步的标题就是 "Engineer the Harness"。他写道：

"我不知道业界是否有一个被广泛接受的术语来描述这个概念，但我越来越倾向于称之为 'harness engineering'。这个理念是：每当我发现 AI 犯了错误，我就花时间去设计一个解决方案，确保它再也不会犯同样的错误。"

这句话听起来简单，但背后的逻辑很深刻。传统的调试思维是"出错了，修一下"，而 Harness Engineering 的思维是"出错了，建一个系统防止它再错"。一个治标，一个治本。

举例：如果 AI 老是把某个 API 调错，普通人的做法是提醒它"下次注意"。但 Hashimoto 的做法是写一段代码，让 API 调用必须经过类型检查，不通过就报错——把人的判断编码成系统的约束。

这就是 Harness 的核心：不是去预测 AI 会犯什么错，而是去设计一个让错误难以发生的环境。

1.2 Harness 的核心比喻

"Harness" 原意是马具，那种套在马身上、既能约束它又能让它拉车的装置。你不能让马乱跑，但也不能捆住它的腿——你要给它一个方向，让它往对的方向使劲。

业界用三个比喻概括这一演进：

• Epsilon 博客："Prompt Engineering 是写一条指令。Context Engineering 是在桌上摆满参考资料。Harness Engineering 是架构整个办公室——Agent 在其中工作。"

• Spillwave 分析：模型是 CPU，Harness 是操作系统。Context Engineering 管理的是写入 CPU 寄存器（上下文窗口）的内容，而 Harness Engineering 设计的是整个操作系统——内存管理、进程隔离、I/O 调度和系统完整性。

• 乐队比喻：你不是在和 AI "对话"，你是在和 AI 协作——就像指挥一个乐队，或者管理一个团队。

---

二、OpenAI 的"零人工代码"实验

"我们花了 5 个月时间，写了 0 行代码，却交付了一个百万行代码的产品。"

——OpenAI 工程团队，2026 年

2.1 实验设置：给自己找不痛快

2025 年 8 月，OpenAI 的一个三人小组给自己定了一个奇怪的规矩：不许写任何代码，全部交给 AI。

听起来像是偷懒？恰恰相反。团队负责人说，这个限制是为了"迫使我们构建必要的 infrastructure，否则速度上不去"。换句话说，他们是在用极端的方式逼自己回答一个问题：如果程序员不能写代码了，他们应该干什么？

2.2 初期：比预期慢得多

实验初期，进展比预期慢了很多。不是因为 AI 不行，而是因为——环境没准备好。AI 像个新手程序员，满腔热情但不知道从哪里开始。它 lack 工具、lack 上下文、lack 清晰的边界。

团队发现，他们花很多时间不是在"用 AI"，而是在"让 AI 能用"。

这个过程很痛苦，但也很有启发：当 AI 失败时，不应该是"让它再试一次"，而应该是"问：缺了什么能力？怎么让这个能力变得可执行、可验证？"

2.3 破局：三个核心设计

经过几个月的摸索，团队逐渐总结出了三个关键设计：

（1）渐进式上下文管理

AI 的上下文窗口是有限的。你不能把所有东西都塞进去，也不能让它失忆。OpenAI 的做法是用 claude-progress.txt 这种结构化文件来传递状态，每次新开一个 session，AI 先读这个文件，就能快速了解"上一班同事干了什么"。

这就像接力赛里的接力棒——你不能指望每个选手都记得全程的细节，但你可以设计一个交接机制。

（2）Feature List：让 AI 知道"没做完"

AI 有个坏毛病：做了一半就觉得自己做完了。

团队的对策是：Initializer Agent 先把用户需求拆成 200+ 个小功能，每个都标记为"未完成"。后面的 Coding Agent 每次只拿一个来做，做完了才改状态。

这招解决了两个常见问题：

• AI 一次性想做太多，最后做不完

• AI 做了一点就觉得"差不多了"，其实还差很远

（3）自检机制：让 AI 用自己的眼睛看结果

最有意思的是他们的测试方法。他们给 AI 配了 Puppeteer（一个浏览器自动化工具），让它像真人一样去点自己的应用、截图、验证功能。不是看代码对不对，而是看东西能不能用。

结果发现，一旦 AI 真的去用自己做的东西，能发现很多单纯看代码发现不了的问题。

---

三、为什么需要 Harness

OpenAI 的实验证明了可行性，但那只是起点。Anthropic 的研究团队在这个方向上走得可能更远——他们发布了多篇 engineering blog，讲他们怎么设计 Harness 来支持长时运行的 AI。

3.1 长时运行 AI 的核心难题

Anthropic 团队的研究员 Justin Young 指出长时间运行的 agent 面临着一个基础性的困境：

"想象一个软件项目，工程师轮班工作，但每个新来的工程师都完全不知道上一班发生了什么。"

这就是 AI 在多 session 工作时的真实处境。每次上下文窗口满了 reset，AI 就失忆了。Anthropic 的解决方案是"结构化交接"——不是让同一个 AI 硬撑（compaction），而是设计好文档和结构，让下一个 AI 能快速接手。

3.2 Agent 的六大典型问题

我们需要 Harness Engineering，是因为 AI 模型本质上是概率性的、不可预测的，而软件工程要求确定性、可靠性和可维护性。具体来说，Agent 存在以下六类典型问题：

1. 上下文失控

给 Agent 一个全栈项目，它倾向于在一个会话里把所有功能做完。结果往往是做到一半上下文窗口耗尽，留下一堆半成品代码，功能没写完，模块接口对不上。

2. 跨会话失忆

在多人协作或者开启多个会话完成不同的功能时，项目的架构和编码风格等在使用不同的大模型时不一致。

3. "自信的即兴发挥"

AI 就像一个缺乏背景知识的实习生，当你指令有空白时，它会自己"脑补"并填补。这种未被审计的决定会形成"信任债务"——当时看起来没问题，但在未来某个时刻会引发爆炸性故障。

4. 过早宣布完成

Agent 经常在大量功能未经验证的情况下就宣布任务完成，导致后续维护成本极高。

5. 线性 vs 指数级技术债务

人写代码时，技术债务通常是线性增长的；但当 Agent 一天能生成几百个 PR（拉取请求）时，如果缺乏约束，技术债务是指数级增长的。

6. 架构漂移

Agent 不理解架构意图，生成的代码会悄悄越过模块边界（例如 Service 层反向依赖 Controller 层），导致循环依赖无声蔓延，最终系统腐化。

3.3 对抗式启发：Generator + Evaluator

Anthropic Labs 的 Prithvi Rajasekaran 做了一个很有意思的尝试：受 GAN（生成对抗网络）启发，设计了生成器 + 评估器的双 agent 架构。

他发现，如果让 AI 自己评估自己的工作，它 tends to be lenient（偏袒自己）——明明做得一般，却会说"挺好的"。但如果把评估拆成独立的 agent，事情就不一样了。

他用前端设计做实验：

• Generator 负责出设计稿

• Evaluator 用 Playwright 实际操作页面，按四个维度打分：设计质量、原创性、工艺水准、功能性

有意思的是，他在 prompt 里加了一句"最好的设计应该是 museum quality（博物馆级别）"，结果 generator 真的开始往那个方向努力，甚至做出了让人惊讶的创意效果。有一次，它把一个荷兰艺术博物馆的网站，从普通的首页重构成了 3D 空间体验——可走动的展厅、挂在墙上的画作、门口导航……这种创意效果，单次生成的 AI 基本做不出来。

---

四、核心架构

4.1 三大支柱

支柱	描述	实现方式
Context Engineering（上下文工程）	持续增强的知识库 + Agent 对动态上下文的访问	AGENTS.md、docs/ 目录、动态注入
Architectural Constraints（架构约束）	通过 LLM Agent + 确定性工具共同监控	自定义 Linter、Schema 验证、ADR、结构化测试
"Garbage Collection"（熵管理）	Agent 定期运行，发现文档不一致或架构违规	定期重构 Agent、LoopDetectionMiddleware

4.2 核心组件对比

组件	LangChain	OpenAI Codex	Anthropic	Stripe	Hashimoto
系统提示 / 指令文件	四阶段系统 prompt	~100 行 AGENTS.md → docs/	按角色分 prompt	按子目录分作用域	AGENTS.md（每行对应一个坏行为）
沙箱 / 隔离	Daytona	Git Worktrees + 原生沙箱	按会话重置	Devboxes（10 秒启动）	—
验证循环	PreCompletionChecklistMiddleware	自定义 Linter	Evaluator Agent + Playwright	2 轮 CI 上限	工具化自动检测
状态持久化	LangSmith Traces	Dotnotes + Git	claude-progress.txt + Git	现有 CI 状态	Git 提交
熵管理	LoopDetectionMiddleware	定期 GC Agent	Feature List JSON	3M+ 测试套件	迭代更新 AGENTS.md
工具访问	标准工具 + 中间件	docs/ + ARCHITECTURE.md	Puppeteer / Playwright MCP	500 MCP 工具（Toolshed）	自定义脚本

4.3 技术栈分层

层级	名称	职责
Layer 4	Human Oversight	站会、PR Review、架构决策
Layer 3	Harness Engineering	沙箱、CI/CD、验证循环、熵垃圾回收
Layer 2	Context Engineering	AGENTS.md、docs/、动态上下文注入
Layer 1	Skill Engineering	可复用任务模式、MCP 工具
Layer 0	Model	GPT-5.2-Codex、Claude Opus 4.6 等

---

五、核心原则

写到这里你可能会觉得：这不就是一堆工程 tricks 吗？有什么大不了的？但 Harness Engineering 背后有几个挺深刻的转变。

5.1 从"写代码"到"设计系统"

传统工程师的成长路径是：先学会写代码，然后设计模块，最后架构系统。但 Harness Engineering 把这个顺序颠倒了：你首先要会设计系统，才能用好 AI 写代码。

这不是降格，是升级。就像从"工匠"变成"工厂设计师"——你不是不做东西了，而是做的东西更有杠杆效应。

5.2 目标：Agent-legible 优于 Human-readable

OpenAI 特别强调，他们最终是围绕 agent legibility 来优化仓库，而不只是人类可读性。原因很直接：当整个仓库越来越多内容由 agent 生成时，系统必须首先让 agent 可以继续理解、导航和扩展这个仓库。

这会改变很多团队过去的工程习惯。比如：

• 命名可以不可以今天叫 service，明天叫 manager，后天叫 handler？

• 同一类设计决策，是否分散在 wiki、issue 评论、代码注释和口头知识里？

• 目录结构是不是混合了历史包袱和当前架构，只有老员工看得懂？

• 测试命令、启动命令、构建命令是不是每个子项目都不一样？

这些问题，过去是"增加维护成本"；到了 agent 时代，它们会直接变成"降低自治率"。

5.3 "约束"变成了一种创作

以前我们觉得，给 AI 加约束是在限制它。但实践发现恰恰相反：清晰的约束让 AI 更有创造性。

Anthropic 的前端实验里，评估标准里的 "museum quality" 提示 AI 往那个方向努力；OpenAI 的严格架构约束让 AI 能放心大胆地写代码，不必担心破坏什么东西。

这有点像爵士乐里的"和弦进行"——有了那个框架，乐手才敢即兴发挥。

5.4 架构边界必须机械化

Harness Engineering 另一个核心原则，是把"架构约束"从文档提升成可执行规则。

OpenAI 提到，他们不仅写文档，还把依赖方向、结构边界和代码风格通过 custom lint、structural tests 等方式强制下来，并且在错误输出中附上 remediation instructions，让 agent 能基于规则直接修正。

这意味着，未来很多 review 意见都不应该永远停留在人类 reviewer 的嘴里。例如：

• "这个模块不应该直接依赖 infra"

• "这里必须做 schema validate"

• "这个 helper 不要重复造"

• "日志字段必须统一"

• "这个文件太大，拆一下"

当一条意见重复出现三次以上，它就已经不只是"建议"，而应该被升级成规则。 因为 agent 的特点不是"偶尔犯错"，而是"高吞吐地重复当前系统允许的一切模式"。如果仓库允许坏模式存在，agent 会迅速把它放大。

5.5 质量控制的范式转移

最震撼的，是 OpenAI 团队说的这句话：

"随着时间的推移，我们将几乎所有审查工作推向 agent 对 agent 的处理。"

在传统软件工程里，code review 是人类工程师的专属领域。但现在，AI 在 review AI 写的代码。这不是因为人类变懒了，而是因为吞吐量太高了。当 AI 一天能开 3.5 个 PR 的时候，人类根本 review 不过来。

所以质量控制必须从"人工检查每一行"变成"设计让 AI 自我验证的机制"。

5.6 验证闭环比生成能力更重要

OpenAI 描述更高自治度时提到一个完整闭环：agent 可以验证代码库当前状态、复现 bug、录制问题、实现修复、再次验证、录制修复后状态、提交 PR、处理 review 反馈，必要时才升级到人工判断。

这其实说明了一件事：真正高价值的不是"能写代码"，而是"能证明自己写对了"。

在 Harness Engineering 里，最重要的不是一次生成出来多少代码，而是是否具备完整的 verification loop，包括：

• 静态检查

• 单元测试

• 集成测试

• 构建验证

• 可观测性检查

• review feedback 修复

• 失败重试与升级条件

没有这个闭环，agent 就只是一个高输出的代码生成器；有了这个闭环，它才会逐渐变成可依赖的工程执行者。

---

六、六大工程实践

6.1 环境即代码：构建智能体的栖息地

Harness Engineering 的首要任务是为智能体构建一个它能完全理解并操作的环境。智能体无法访问存在于人类头脑、Google Docs 或 Slack 聊天记录中的知识。

• 代码仓库作为唯一真相源（Single Source of Truth）：如 OpenAI 所述，所有文档（架构、设计、产品规范）必须存放在代码仓库内（如 docs/ 目录），并作为代码版本化。智能体运行时无法访问仓库外的信息。

• 地图优于说明书：不要给智能体一个巨大的 Prompt（"1000 页说明书"），而是给它一张地图（如简短的 AGENTS.md），让它按需去代码库中检索细节。

• 工具化可观测性：将日志、指标（Metrics）和 UI 测试工具（如 Chrome DevTools）直接接入智能体运行时，使其能自主验证代码是否生效（Self-Verification）。

6.2 仓库即知识运行时

OpenAI 很快发现，"一个超大的 AGENTS.md" 不是好主意。于是他们逐渐把知识沉淀进仓库内部，用结构化的文档系统来承载架构说明、设计文档、产品规格、执行计划、质量标准、可靠性和安全要求等内容，让 repository knowledge 成为 system of record。

他们给出的经验是：给 Codex 一张地图，而不是一本 1000 页说明书。

Agent 最怕的，并不一定是知识少，而是知识杂乱、冗长、不可导航、不可验证。因此，一个适合 agent 的仓库要做到：

• 信息分层

• 入口清晰

• 路径稳定

• 命名一致

• 关键规则有明确归档位置

• 任务执行时能够按需引用

这和传统"给新人看的文档"有点像，但要求更高。因为新人看不懂还能问人，agent 看不懂就会猜，猜错就开始写歪。

6.3 上下文工程：注入超能力

Harness 的核心功能之一是收集和注入上下文，弥补模型本身的局限性。

• 环境自感知：如 LangChain 所述，Harness 应包含中间件（Middleware），在启动时自动扫描当前目录（cwd）、可用工具（如 Python 版本）并注入给智能体，减少幻觉。

• 时间与预算管理：智能体通常不擅长估算时间。Harness 需要注入时间预算提示（Time Budgeting）或强制超时，防止智能体陷入无限循环。

• 结构化上下文注入：使用中间件（如 LocalContextMiddleware）动态地将环境信息注入到 Prompt 中，而不是依赖模型的记忆。

6.4 强制验证与反馈闭环

智能体倾向于给出第一个看似合理的答案，Harness 必须强制它们进行反思和验证。

• 构建-验证循环（Build-Verify Loop）：Harness 必须强制智能体编写测试、运行测试，并根据测试结果修正代码，而不是仅仅"确认代码看起来没问题"。

• 防死循环机制：实施 LoopDetectionMiddleware，当智能体在同一个文件上重复修改多次时，强制其重新审视计划，跳出"死循环"。

• Ralph Wiggum 循环：即使智能体声称任务完成，Harness 也应强制其进行最后一次检查或让另一个智能体进行审查（Agent-to-Agent Review）。

6.5 架构约束与品味（Architectural Guardrails）

为了保持大规模产出的代码质量，Harness 需要通过架构限制智能体的自由度。

• 严格的架构边界：强制执行分层架构（如 Types → Config → Repo → Service），通过自定义 Linter 强制智能体遵守依赖规则。

• 垃圾回收与熵减：建立自动化的后台任务（如每周的 "Doc Gardening"），扫描并重构低质量代码或过时文档，防止技术债务累积。

• 黄金原则编码化：将人类的"品味"（如命名规范、错误处理方式）转化为机器可执行的规则和 Linter 错误信息，而非口头指导。

6.6 Trace 驱动的迭代优化

Harness Engineering 是一个持续的优化过程，利用运行轨迹（Traces）来改进系统。

• Trace 驱动的改进：利用 LangSmith 等工具记录所有运行轨迹，分析失败模式（如推理错误、工具使用不当）。

• 自动化 Harness 调优：开发专门的 Agent Skill 来分析 Trace，自动生成对 System Prompt 或 Middleware 的改进建议。

---

七、行业案例分析

7.1 LangChain：推理三明治 + 中间件体系

关键创新——"推理三明治"（Reasoning Sandwich）

LangChain 的标志性创新是 xhigh-high-xhigh 推理配置：

1. xhigh：用于规划（开始时的深度推理）

2. high：用于实现（中间的快速执行）

3. xhigh：用于验证（结束时的深度推理）

原理：在规划和验证上花费更多推理计算量，同时保持实现阶段的速度。

关键中间件组件：

• PreCompletionChecklistMiddleware：在 Agent 退出前拦截，强制执行针对 Task 规范的验证

• LocalContextMiddleware：映射 cwd、父子目录、Python 安装路径

• LoopDetectionMiddleware：跟踪每个文件的编辑次数；超过 N 次编辑后注入"考虑重新思考方法"提示

设计原则总结：

• "代表 Agent 进行上下文工程"——通过确定性上下文注入减少搜索/规划错误面

• "帮助 Agent 自我验证"——对抗倾向于第一个看似合理方案的偏见

• "Tracing 作为反馈信号"——同时调试工具和推理

• "为模型定制 Harness"——Codex vs Claude 需要根本不同的提示策略

• 注入时间预算警告，因为 Agent "在时间估算方面出了名的差"

7.2 OpenAI Codex：100 万行零手写代码

核心数据：3 人团队在 5 个月内产出 100 万+ 行代码，零行手写。每人产出扩展至 3–10 名工程师的水平。

AGENTS.md 设计哲学：

• 功能定位为 "目录，不是百科全书"

• 限制在 ~100 行

• 指向 docs/ 目录中的详细文档

• AGENTS.md 文件本身也由 Codex 编写

• 存储在 Slack 或工程师脑中的知识对 AI "不可见"——一切必须推入代码仓库

架构约束的强度：

• 要求通常在 "1000–10000 名工程师"规模公司才有的"刚性架构模式"

• 自定义 Linter 规则确定性地强制执行分层架构

• 目标：约束解空间，使 Agent 不可能引入结构性违规

• 使用 Dotnotes 记录每次提交的决策历史

• 通过 Git Worktrees 为每个 Agent 任务提供隔离环境

流程管理：

• 每日 30 分钟站会防止高速开发下的架构偏移

• CI/CD 管道生成的反馈供 Agent 自主消费

7.3 Anthropic：GAN 风格的多 Agent Harness

核心架构——Generator-Evaluator 模式（受 GAN 启发）

Anthropic 发现了一个关键洞察：模型"无法可靠地评估自己的工作"。据此设计了三 Agent 系统：

1. Planner Agent：将 1–4 句话的提示扩展为完整产品规范；被提示"对范围保持雄心"；避免细粒度技术细节以防止错误级联。

2. Generator Agent：按 Sprint 工作，每次实现一个功能；在每个 Sprint 前与 Evaluator 协商"Sprint 合同"。

3. Evaluator Agent：使用 Playwright MCP 与活跃应用交互；根据标准和硬性阈值打分；捕获路由排序等特定 Bug。

上下文管理策略：

• Context Resets：完全清空上下文窗口，启动新 Agent（适用于 Sonnet 4.5 的"上下文焦虑"问题）

• Compaction：保留连续性但无法提供"全新状态"

• Handoff Artifacts：会话间结构化状态载体

两层解决方案：

• 初始化 Agent：首次会话通过 init.sh 设置环境，创建 claude-progress.txt 日志，首次 Git 提交，创建含 200+ 端到端需求的 Feature List JSON（全部标记为 "failing"）。

• 编码 Agent：后续会话在单个功能上渐进推进，通过浏览器自动化（Puppeteer MCP）自验证后才标记功能为 "passing"。

启动例程：执行 pwd、读取 Git 日志/进度文件、检查 Feature List、选择最高优先级未完成项。

Sprint 合同机制：

• Generator 提出构建内容和验证方法

• Evaluator 审查以确保"构建的是正确的东西"

• 迭代直到达成一致

---

八、实战：从今天开始

理论讲完了。好在 Harness 不是全有或全无的——哪怕不搭完整的六层基础设施，一个 AGENTS.md 就能让 AI 协作体验好一截。这套方法适用于任何能跑 shell 命令的 coding agent（Qodercli、Claude Code、Codex 等都行）。多人协作、有明确分层的中大型项目收益最明显；个人项目或原型阶段，一个 AGENTS.md 加个简单的 lint 脚本就够了。

8.1 最小起步：AGENTS.md 模板

新项目最简单——告诉 creator 你要做什么，它会问几个基本问题，然后直接生成全套基础设施。老项目也不难，creator 会扫描代码库、分析 import 关系、推断层级映射，生成反映代码现状的文档。

最小起步示例：在项目根目录创建 AGENTS.md：

# [项目名] Agent Guide

## 快速链接
- [架构总览](docs/ARCHITECTURE.md) — 分层规则、数据流
- [开发指南](docs/DEVELOPMENT.md) — 构建、测试、lint 命令

## 构建命令
make build      # 构建项目
make test       # 运行测试
make lint-arch  # 运行架构 lint

## 分层规则
Layer 0: types/         → 纯类型定义，无内部依赖
Layer 1: utils/         → 工具函数，仅依赖 Layer 0
Layer 2: config/        → 配置，依赖 Layer 0-1
Layer 3: core/services/ → 业务逻辑，依赖 Layer 0-2
Layer 4: api/ cli/ ui/  → 接口层，依赖 Layer 0-3，彼此不互相引用

## 质量标准
- 结构化日志，禁止 console.log / print()
- 单文件不超过 500 行
- PascalCase（类型）、camelCase（函数）、kebab-case（文件名）

为什么叫 AGENTS.md？这个文件名是业界的标准（https://agents.md/），Agent 打开项目时会自动查找并读取它，作为了解项目的起点。类似于 README.md 是给人看的，AGENTS.md 是给 Agent 看的。

建议的节奏：今天先把 AGENTS.md 建出来；这周加一个 lint-deps 脚本把层级规则定下来；这个月搭完整的验证管道；之后开启 Critic → Refiner 反馈循环，让 Harness 跟着代码一起长。最佳实践是先用 creator 把 Harness 建到 70 分以上，再开始用 executor 日常开发。

8.2 渐进路径：从静态规则到自我成长

前面讲的 Harness 还是静态的——人定规则，Agent 遵守。但真正有意思的地方在于，Harness 能从 Agent 的失败里学东西。

每次 Agent 犯错都是一个信号。如果同一类错误反复出现，说明 Harness 本身有缺口——要么某个包没被 linter 覆盖，要么某条规则的错误信息写得不够清楚，要么某个场景缺少文档。与其靠人去发现这些缺口，不如让系统自己分析。

每次验证失败都被结构化地保存到 harness/trace/failures/。Critic 脚本定期分析这些记录，找出模式和根因——比如发现 internal/cache 被 7 次违规 import，根因是它没被加入层级映射表，建议修复是把它加入 Layer 1。然后 Refiner 根据建议去更新 Harness：把遗漏的包加入 linter 规则，改写含糊的错误信息，补上缺失的文档。

整个循环跑起来就是：

Agent 执行 → 验证抓到问题 → Critic 分析模式 → Refiner 更新规则 → 下一个 Agent 受益

8.3 三种 Harness 记忆

Harness 维护着三种"记忆"：

• 情景记忆：记录具体事件和教训。比如"macOS 下 /var 是 /private/var 的符号链接，会导致工作区路径比较失败"——这类教训可能只要 10 秒加载，却能省下一整个重试循环。

• 程序记忆：记录成功的操作步骤。比如"添加 API 端点的标准五步流程，成功率 90%"，新的子代理执行同类任务时会先查这里。

• 失败记忆：专门供 Critic 分析用。

每次任务开始时，executor 会查询相关记忆，这些记忆的价值随着项目演进不断累积。

8.4 轨迹编译：成功模式 → 确定性脚本

这套闭环走到极致会出现一个很有意思的东西：轨迹编译。

当同一类任务被成功执行了三次以上，而且步骤高度一致——比如"添加 API 端点"每次都是创建类型文件、写服务方法、加 handler、注册路由、写测试——这个模式就可以被"编译"成一个确定性脚本，像 make add-endpoint NAME=foo 这样。以后再做同类任务直接跑脚本，LLM 都省了。脚本失败了再回退到 Agent 模式就好。

这是个棘轮效应：每一个被编译的成功模式都变成了永久基础设施，Agent 被释放去处理真正需要创造力的新问题。整个系统的运行成本越来越低，能力越来越强。

Agent 不需要更聪明——它只是能看见更多了。

环境设计的投入回报远高于 prompt 调优。一套好的 Harness 能让普通模型产出可靠的代码，而没有 Harness 的顶级模型照样会在同样的坑里反复栽。搭建的前期成本不高——一个下午就能建好基本的 AGENTS.md 和 lint 脚本。但它的价值会随着时间复利式增长：记忆越来越丰富，lint 规则越来越完善，越来越多的操作模式被编译成确定性脚本。

竞争优势不再是 Prompt，而是 Trajectory。这些积累，换个模型复制不来。

---

九、AI 工程范式发展历程

9.1 Prompt Engineering（提示工程）：精妙的"台词"

Prompt Engineering 是你直接对 AI 说的那句话。它的核心在于通过优化措辞、结构和示例，让 AI 听懂你的意图。

• 糟糕的 Prompt："帮我看看这个案子怎么回事。"（AI 可能会胡编乱造）

• 优秀的 Prompt Engineering：

"你是一位拥有 20 年经验的资深刑侦专家（角色设定）。请阅读下方的案件描述，分三个步骤（思维链）进行推理：1. 分析嫌疑人动机；2. 寻找矛盾点；3. 得出结论。最后请以 JSON 格式（输出控制）输出你的分析报告。"

它的局限：如果你只给这一句话，AI 虽然知道怎么"演"侦探，但它手里没有案卷，只能靠它训练时背下来的通用知识瞎编（产生幻觉）。Prompt Engineering 只解决了"你说什么"这一维度——一段静态的指令文本。当 LLM 应用从单轮问答演化为需要编排工具、数据库和 API 的多步骤 Agent 时，一串静态指令就显得无能为力了。

9.2 Context Engineering（上下文工程）：完备的"档案室"

Context Engineering 是在 AI 开口回答之前，你悄悄塞进它手里的"资料包"。它的核心在于决定模型看到什么信息、什么时候看到、以及信息的优先级。

在这个阶段，你不再纠结于怎么写那句话，而是构建一个系统来管理信息：

• 短期记忆（对话历史）：把用户刚才问的"嫌疑人穿红衣服吗？"和 AI 回答的"是的"记录下来，作为下一轮对话的背景。

• 长期记忆（用户画像）：系统自动注入："该用户是法律系学生，需要详细的法条引用，而不是简单的科普。"

• 外部知识库（RAG）：当用户问"嫌疑人张三的过往记录"时，系统自动去数据库检索张三的档案，把最相关的 3 页 PDF 内容截取出来，放在 AI 眼前。

• 工具定义（Tools）：告诉 AI："你现在手里有一个计算器工具和一个联网搜索工具，遇到算数或查新闻时可以使用。"

七大组成要素：

1. 系统提示与指令——基础行为规范

2. 用户即时查询——当前任务的直接输入

3. 对话历史（短期记忆）——当前会话的上下文连续性

4. 跨会话的持久知识（长期记忆）——用户偏好、历史决策

5. 外部检索信息（RAG）——从向量数据库、搜索引擎等获取的实时知识

6. 可用工具定义及其返回结果——函数调用的接口与输出

7. 结构化输出模式——约束模型输出格式

与 Prompt Engineering 的本质区别：区别在于范围与动态性。Prompt engineering 制作一段静态指令；Context engineering 架构一个在运行时动态组装正确信息的系统。正如 Hugging Face 的 Phil Schmid 所言："大多数 Agent 的失败不再是模型的失败，而是上下文的失败。"

Context engineering 不替代 prompt engineering——它包含了 prompt engineering。提示词是其中一个组件；上下文才是整体。但 context engineering 仍有其局限：它回答了"模型应该看到什么"，却没有回答"整个系统应该如何运作"。

9.3 Harness Engineering（驾驭工程）：一套"马鞍"

Harness Engineering 是 Context Engineering 的自然延伸。它不仅关心"给模型看什么"，更关心"如何让模型在看的过程中保持专注、自我纠正、持续前进"。

Harness engineering 给出了一个简洁的公式：

Agent = Model + Harness

Harness 就是模型本身之外的每一行代码、每一段配置和每一条执行逻辑。其组件包括：

• 工具集成与选择——定义 Agent 可以调用什么，不可以调用什么

• 记忆系统——工作上下文、会话状态、长期记忆的分层管理

• 编排逻辑——子 Agent 委托、模型路由、任务分解

• 验证与测试——代码检查器（linter）、CI 流水线、自动化测试套件

• 护栏与安全——人机协同控制、权限系统

• 错误处理与恢复——重试逻辑、"死循环"检测

• 可观测性——追踪每次工具调用、指标、成本

• 架构约束——强制依赖分层、模块化边界

Louis Bouchard 给出了精炼的概括："Context engineering 是关于发送什么给模型，使其能够自信地回答。Harness engineering 是关于整个系统如何运作。"每一层包含前一层，竞争优势已经从"你在用哪个模型？"决定性地转移到"你的 harness 有多好？"

但即便如此，harness engineering 仍然有一个巨大的盲区：它关注的是模型周围的编排逻辑，却没有系统性地思考 Agent 运行的真实世界本身。

9.4 Environment Engineering（环境工程）：从编排逻辑到运行世界

Agent 不是一个纯粹的信息处理系统。它需要从真实环境中读取文件、查询数据库、调用 API 来收集信息；它编写的代码需要在真实的操作系统上编译和运行；它创建的 Pull Request 需要通过真实的 CI/CD 流水线；它部署的服务需要在真实的云基础设施上承载流量。

无论你的 prompt 多么精巧、context 多么丰富、harness 多么完善——如果 Agent 没有一个经过精心工程化的运行环境，一切都是空中楼阁。这就是 Environment Engineering 的核心命题。

这个概念涵盖六个核心维度：

1. 工具与动作（Tools & Actions）——哪些工具存在、哪些被允许或禁止

2. 资源与数据（Resources & Data）——只读访问模式、显式的副作用声明

3. 运行时与网络（Runtime & Network）——容器、沙箱、出站调用白名单

4. 认证与身份（Authentication & Identity）——Agent 的专用身份、最小权限原则

5. 人类监督（Human Oversight）——对不可逆操作的审批门

6. 反馈回路（Feedback Loops）——可操作的错误信息、行为追踪、日志

9.5 四阶段对比

维度	Prompt Engineering	Context Engineering	Harness Engineering	Environment Engineering
核心问题	怎么说？	模型看到什么？	系统如何运作？	Agent 在什么世界中运行？
诞生时间	2020（GPT-3）	2025 年 6 月（概念结晶）	2026 年 2 月（概念结晶）	2025 年 10 月（概念浮现）
关键人物	Jason Wei, Shunyu Yao	Tobi Lutke, Karpathy, Chase	Mitchell Hashimoto, OpenAI	Aymen Furter（微软）
操作对象	一段文本	整个上下文窗口	模型周围的所有代码	Agent 运行的整个世界
类比	写邮件措辞	准备会议资料包	设计公司运营流程	建造办公楼与基础设施
RL 类比	—	State 表示	Policy + Reward	Environment 本身
关键度量	输出质量	信息覆盖率与相关性	任务成功率与可靠性	安全性、延迟、成本、可扩展性
失败模式	措辞不当 → 输出偏差	信息缺失 → 决策错误	编排失当 → Agent 漂移	环境缺陷 → 安全漏洞、执行失败
核心隐喻	念咒语（Magic）	给记忆（Memory）	造系统（System/OS）	造世界（World）
你的角色	提问者	图书管理员	系统架构师 / 驯兽师	城市规划师

AI 工程范式的进化遵循一个清晰的范围扩张逻辑：

• Prompt Engineering 问："我应该怎么表达？"

• Context Engineering 问："模型应该看到什么？"

• Harness Engineering 问："整个系统应该如何运作？"

• Environment Engineering 问："Agent 在什么世界中运行？"

每一层的出现都是因为前一层被证明是必要但不充分的。而 Environment Engineering 之所以是终极工程，不是因为它比其他层"更高级"，而是因为它是所有其他层的物质基础。没有环境，提示词无处发送，上下文无法获取，harness 无法执行。

最重要的洞察是经验性的而非理论性的：围绕模型的基础设施现在比模型本身更重要。 当 Dario Amodei 预测 AI 将在 12 个月内接管几乎所有编码工作时，他实际上在暗示——模型能力正在快速商品化。在一个模型能力趋同的世界里，差异化竞争的唯一来源就是你为 Agent 构建的运行环境有多好。

正如传统软件工程的重心从"编写代码"逐渐转移到"构建平台"——从写出正确的算法到设计可靠的分布式系统——AI 工程的重心也正在从"与模型对话"转移到"为 Agent 构建世界"。

Intent 决定了你需要什么 context，context 决定了什么 prompt 有意义，harness 编排一切如何运作，而 environment 定义了一切可能性的边界。

在这个新的工程层级中，能够跨越全部四层同时工程化的从业者——不是 prompt engineer，不是 context engineer，而是 Karpathy 所说的 "agentic engineer"——将是这个时代最稀缺的人才。

---

十、启示

10.1 别慌，但别等

Harness Engineering 的出现，不代表程序员要失业了。

你看 OpenAI 那个实验：三个人 supervision 了一百万行代码。他们不是被取代了，而是换了一种工作方式——从"写代码的人"变成了"设计系统和把控质量的人"。

但另一方面，也别等。这个转变不会等你准备好了才发生。

10.2 "无聊"技术可能更值钱

有个反直觉的发现：OpenAI 团队说他们偏好"无聊的技术"——API 稳定、文档完善、可组合性强。

不是追新，而是求稳。因为 AI 在可预测的环境里表现更好。

这对技术选型有暗示：可能未来 React 比 Svelte 更适合 AI（因为前者文档更全），或者 Python 在某些场景下比 Rust 更适合（因为训练数据更多）。

10.3 软技能变得更重要了

如果 AI 能写代码，那什么技能更值钱？

• 系统设计能力：知道怎么拆分问题、怎么定义接口

• 产品感：知道用户要什么，能把模糊的需求变成清晰的定义

• 质量评判：知道什么是"好的"，什么只是"能跑"

• AI 管理能力：知道什么任务适合交给 AI，什么必须人类来做

这些都不是新技能，但它们的相对重要性在变。

Harness 工程师关注的不再是编码和测试相关工作，更多的精力是花费在编码前的环境准备，通过结构化思考给大模型编码操作制定规范，以及当模型出错或者不符合预期时调整规则。考验的是设计能力和任务规划能力。

• 范式错位：传统的软件工程实践（如人工 Code Review、依赖人脑记住架构规范）在 AI 生成代码的速度面前已经失效。

• 新的工作流：当 Agent 遇到困难时，工程师的思考不应是"我该怎么帮它写这段代码"，而应是"Agent 缺乏什么能力？需要什么工具？需要什么抽象层？"。

---

总结

Harness Engineering 给我们提供了一个框架：不是把 AI 当成神秘的黑盒，而是当成一个需要被设计的系统组件。 你不是在和 AI "对话"，你是在和 AI 协作——就像指挥一个乐队，或者管理一个团队。

未来的软件工程师，可能更像是一个"导演"或"指挥"：不亲自演奏每个音符，但决定整首曲子的走向和风格。

Harness Engineering 是 AI 工程化的必经之路。它标志着我们从"手工作坊时代"（靠人写代码）进入了"自动化流水线时代"（靠人设计流水线，AI 生产代码）。