01 · 什么是Harness Engineering
2026年2月，OpenAI工程师Ryan Lopopolo发表了一份实践报告，讲述一个3人团队如何在5个月内用Codex Agent生成了100万行代码。标题就叫《Harness Engineering》——"驾驭工程学"。
这个"驾驭"这个词很关键。它不是说AI Agent有多强，而是说如何围绕Agent构建结构、工具、反馈机制，使得Agent能够高效、可靠地完成复杂工作。
这份报告揭示了一个核心真相：AI Agent的瓶颈不在模型本身的能力，而在于它周围的生态。你给Agent什么样的环境、什么样的指导、什么样的反馈机制，它就会有什么样的表现。
核心洞察：要让AI Agent在真实工作中可靠地工作，关键不是选择最强的模型，而是设计一个系统化的"驾驭框架"。这个框架包括文件组织、信息结构、错误反馈、自动化质控等维度。
本章就是对这份报告的深入解读，并将其方法论应用到你的日常AI工作流中。
02 · 五大核心实践
Harness Engineering的核心是五个实践，分别解决Agent工作的五个关键问题：存储、导航、学习、结构、维护。
① 文件系统即持久化
问题：Context Window（对话窗口）是有限的。如果所有信息都存在对话中，超过窗口大小后就会被遗忘。Agent无法积累知识。
解决方案：把重要信息写入文件系统。把对话窗口当作"RAM"（临时内存），把文件系统当作"硬盘"（持久化存储）。
具体怎么做？在你的Agent工作目录建立这样的结构：
目录结构示例
project/
├──
.plans/ ← Agent的工作日志
│ ├── 2026-03-25-task-001.md
│ ├── 2026-03-25-task-002.md
│ └── current.md
├──
docs/ ← 项目文档（供Agent查阅）
│ ├── architecture.md
│ ├── API-reference.md
│ └── known-issues.md
├──
src/ ← 代码
└──
tests/ ← 测试
.plans目录的妙处：
- 每个任务一个文件：Agent在开始任务时创建一个文件，记录目标、步骤、发现、决策。
- 可查阅的历史：Agent可以随时查看过去的plan文件，了解自己做过什么，避免重复。
- 人可读的记录：你可以定期查看这些文件，理解Agent的思路，发现问题。
- 持续改进的依据：通过分析这些文件，你可以发现Agent容易出错的地方，优化指导。
② 给地图不给手册
问题：Agent会被巨大的信息量淹没。一个项目的完整文档可能有1000行，Agent无法高效地处理。
解决方案：给Agent一个简短的"导航索引"而不是完整的手册。索引告诉它"有什么"和"在哪里"，让它自己去查。
对比一下：
❌ 坏做法
把800行的API文档全部给Agent：
POST /api/users
POST /api/users/{id}
GET /api/users
DELETE /api/users/{id}
... [重复700行]
结果：Agent淹没在细节中，搜索困难，容易出错。
✓ 好做法
给Agent一个100行的索引：
# API Index
- Users: docs/api/users.md
- Auth: docs/api/auth.md
- Data: docs/api/data.md
Agent需要什么就查什么。索引本身很短，容易管理。
③ Linter即教师
问题：Agent犯了错，怎么让它学习？靠语言说教很低效。
解决方案：定义自定义的Linter规则。当Agent生成的代码违反规则时，Linter会给出明确的错误信息和修复建议。
例如，在一个TypeScript项目中，你可以定义这样的规则：
自定义Linter规则示例
// Rule: 所有API调用必须有超时设置
- ✗ 错: const result = await api.fetch(url);
- ✓ 对: const result = await api.fetch(url, {timeout: 5000});
// Rule: 错误处理必须记日志
- ✗ 错: try { ... } catch (e) { }
- ✓ 对: try { ... } catch (e) { logger.error(e); }
// Rule: 不允许使用var，必须用const/let
- ✗ 错: var x = 1;
- ✓ 对: const x = 1;
当Agent的代码违反这些规则时，你的Linter会输出：
Linter输出
Error in fetch.ts:23
Missing timeout configuration on API call.
Expected:
await api.fetch(url, {timeout: 5000})
Reference: docs/style-guide.md#api-timeouts
这样做的好处：
- Agent把Linter错误当作具体的、可修复的问题，而不是模糊的建议。
- 同样的错误只需要在Linter里修正一次规则，所有未来的任务都会遵守。
- 错误反馈是程序化的，确保一致性。
④ 严格分层架构
问题：如果整个代码库结构混乱，Agent很难理解"这个改动会影响什么"。它容易做出看起来对但实际上破坏了其他地方的改动。
解决方案：强制清晰的分层架构。每一层都有明确的职责，层之间有清晰的边界。
OpenAI的报告中提到的架构分层：
Types（类型定义）
所有数据结构的TypeScript接口或类定义。这是最底层，所有其他层都依赖它。
Config（配置）
常量配置、环境变量、系统参数。Agent修改了配置后，其他部分应该自动适应。
Repo（数据仓库）
数据访问层。所有的数据操作（读写、查询、持久化）都通过这一层。
Service（业务逻辑）
应用的核心逻辑。不直接操作数据，而是调用Repo层，然后处理业务规则。
Runtime（运行时）
服务启动、初始化、事件循环的代码。
UI（用户界面）
最上层，调用Service提供的接口。
这样的分层有什么好处？Agent可以明确地理解：
- 修改Types会影响所有其他层 → 要格外小心
- 修改Service只会影响业务逻辑，不会影响数据访问 → 相对安全
- 修改UI只影响展示，不影响数据 → 最安全
⑤ 自动化垃圾回收
问题：Agent在工作过程中会产生"扫描偏差"——某些决策是基于过时的信息或错误的假设做的。这些偏差会在代码中积累。
解决方案：定期运行自动化扫描，发现代码质量问题，自动生成修复PR。这样能防止技术债快速堆积。
具体做法：
- 定期扫描：每周或每两周跑一次自动化分析（可以用Agent自己做）
- 问题评分：给发现的每个问题打分（bug风险高、代码重复、过时依赖等）
- 自动生成PR：对于低风险的问题（如代码格式、依赖更新），直接生成修复PR
- 人工审查：高风险问题标记为"需要人工审查"，等待你的决策
03 · 三大工程纪律协议
除了那五个实践，OpenAI还提出了三个"工程纪律"——遵守这些规则能显著提高Agent工作的可靠性。
协议1：2-Action Rule
规则：每当Agent进行搜索或查询时，在进行第3次搜索之前，必须停下来写一次"findings"（发现总结）。
为什么？信息膨胀。Agent搜索了10次，积累了大量的片段信息，最后可能根本记不清哪些是关键的。定期的总结强制Agent整理思路，防止信息爆炸。
2-Action Rule示例
搜索1：查询API文档 ✓
搜索2：查询代码示例 ✓
📝 Findings总结：
- API支持X和Y两种调用方式
- 推荐方式是Y（更高效）
- 需要传入token参数
搜索3：查询错误处理 ✓
搜索4：查询超时配置 ✓
📝 再次Findings总结：
- 错误code有3种：A, B, C
- 默认超时是5秒
- 推荐设置为10秒
然后才能进行实现
协议2：3-Strike Escalation
规则：如果Agent连续3次尝试同一个问题都失败了，必须升级策略（问人、查文档、换方法）。
为什么？防止无限循环。Agent有时候会陷入"卡壳"状态——不停地尝试同一种方法，就是不成功。3次失败应该是触发"我的策略有问题"的信号。
3-Strike规则执行
尝试1：用方法A修复测试 → 失败
尝试2：用方法A修复测试 → 失败
尝试3：用方法A修复测试 → 失败
❌ 触发3-Strike Rule
升级策略：
① 查阅docs/troubleshooting.md
② 搜索同类问题的历史解决方案
③ 如果还是失败，标记为"需要人工介入"
协议3：Doc-Code Sync
规则：每当修改API接口、函数签名或配置结构时，必须同时更新文档。不更新文档的改动不算完成。
为什么？代码和文档的不一致是Agent（和人类）犯错的常见原因。强制同时更新能让这个问题永不出现。
怎么实施？在你的CI/CD中加一个检查：
Doc-Code Sync检查
// 检查规则
if (修改了src/api.ts) {
if (未修改 docs/api-reference.md) {
❌ 拒绝合并。错误信息：
"API改动必须同步更新 docs/api-reference.md"
}
}
04 · 对非程序员的启示
上面的内容是针对软件开发的，但Harness Engineering的原则完全可以应用到你的日常AI工作流中。不管你是写手、分析师、学生还是企业员工。
原则转化1：重要信息写入文件，不只存在对话中
编程世界的原则：用文件系统做持久化存储。
你的应用：每当AI给了你一个有价值的信息（数据、观点、框架），把它记在笔记或知识库中。不要只靠对话历史，那是易失的。
具体做法：
- 建一个"AI工作日志"目录，记录每次重要对话的总结
- 用Markdown格式，便于搜索和回顾
- 定期归档成"周总结"、"月总结"
原则转化2：给AI简短索引，不是巨大的上下文
编程世界的原则：给Agent导航索引而不是完整手册。
你的应用：不要在每次对话中都粘贴整个项目文档。相反，先告诉AI"有什么"，让它按需查阅。
具体做法：
好的上下文结构
我有一个营销项目，结构如下：
- Brand Guidelines: 〜200字的品牌定位
- Product Catalog: 产品列表
- Campaign History: 过去的营销案例
我现在需要<做什么>。
请问需要我提供什么具体信息吗？
而不是一上来就粘贴5000字的品牌手册。
原则转化3：每次失败都记录成未来的护栏
编程世界的原则：自定义Linter规则，把犯过的错"编码"成检查。
你的应用：每当AI给了你一个不满意的回答，分析一下"为什么不满意"。下次对话时，提前说明这个限制。
具体做法：
建立个人的AI使用"Linter"
过去的失败1：
AI写的文案太学术，不够通俗
→ 现在每次都加：(用第8年级学生能理解的语言写)
过去的失败2：
AI忽视了时间限制
→ 现在每次都说：(这个项目的deadline是...)
过去的失败3：
AI的建议太理想化，没考虑成本
→ 现在每次都提：(我们的预算是...)
原则转化4：按功能纵切而不是按步骤横切
编程世界的原则：严格的分层架构让Agent清楚地理解影响范围。
你的应用：将大任务分解时，按"功能模块"而不是"时间步骤"来分。
❌ 步骤横切
第1步：收集信息
第2步：整理数据
第3步：分析数据
第4步：写报告
问题：步骤之间有依赖，不清楚每步的边界。
✓ 功能纵切
模块A：财务数据整理
模块B：市场数据整理
模块C：财务分析
模块D：报告生成
优势：每个模块独立，AI可以并行处理或选择性修改。
05 · 实战应用案例
让我们看三个具体的例子，展示如何把Harness Engineering的原则应用到真实工作中。
案例1：写手的AI辅助工作流
场景：你每月要写10篇文章，用AI来加速创作过程。
应用Harness原则：
- 文件系统持久化：建一个/articles目录，存放每篇文章的大纲、初稿、修改历史。别只在对话里。
- 导航索引：建一个/guidelines目录，里面有：
- tone-of-voice.md（你的文风指南）
- target-audience.md（目标读者）
- past-articles-summary.md（过去5篇文章的总结，让AI学习你的风格）
- Linter规则：你发现AI经常犯的错：
- 过度使用"很"、"非常"这样的词
- 开头段落太长
- 用词过于正式
→ 每次都提前说明这些点。
案例2：学生的论文研究辅助
场景：你在写一篇学位论文，需要整理大量文献、提取关键观点。
应用Harness原则：
- .plans日志：每次文献阅读完成后，写一个文件：
- 2026-03-25-paper-001.md：关键观点、引用、与其他文献的关系
- 2026-03-26-paper-002.md：类似格式
- 文档索引：
- research-questions.md（你的核心研究问题）
- methodology.md（你采用的研究方法）
- key-concepts.md（领域的关键概念定义）
- 2-Action Rule：每读2篇论文后，停下来写一个"当前的理解"总结，防止信息爆炸。
案例3：产品经理的功能规划
场景：你用AI来帮助规划新产品功能、做用户研究分析。
应用Harness原则：
- 分层架构思维：
- Types（用户需求的类型分类）
- Config（产品的约束条件：预算、时间、技术限制）
- Service（功能优先级评分逻辑）
- UI（最终的功能清单）
- Doc-Code Sync：每当改变功能需求时，同时更新用户需求文档。让AI能始终看到最新的需求。
- 3-Strike Rule：如果AI提的方案连续3次都不符合你的要求，停下来问自己："我的需求描述是不是有问题？"
06 · 总结与展望
Harness Engineering不是关于如何选择最强的模型，也不是关于如何写最复杂的提示词。
它是关于系统思维。当你在和AI一起工作时，不要把它当作一个黑盒——输入问题，得到答案就完事。相反，要设计一个完整的工作系统：
- 清晰的信息架构（什么信息存在哪里）
- 有效的反馈机制（AI怎么知道它做对了或做错了）
- 自动化的质量检查（定期扫描，发现问题）
- 可追踪的决策历史（你能看到AI的思考过程）
这样的系统不仅能让AI更高效，也能让你更清楚地思考自己的工作是怎么做的。
关键要点：AI工程化的未来方向，不是让AI越来越聪明，而是让AI周围的系统越来越清晰。清晰的系统让普通的AI能做出杰出的工作。
练习：为你的一个AI项目设计.plans目录结构
选择你当前正在进行的一个AI辅助项目（写作、学习、工作任务都可以），按照本章的方法论，设计一个简单的文件组织方案。
- 定义你的项目名称和目标
- 列出这个项目会产生哪些"重要信息"（数据、决策、发现）
- 设计一个.plans目录的命名规则（比如日期+任务名）
- 定义一个"findings总结"的模板（包括哪些字段）
- 列出3-5个"Linter规则"（AI常犯的错误，你想要防止）
建议：先从一个小项目试验一周，体验一下这套系统的效果。