TL;DR

给AI Agent一本百科全书，它会迷失；给它一张地图，它会探索。OpenAI的Harness工程实验揭示了一个反直觉的真相：让Agent失败的不是知识太少，而是知识太乱。他们从一本1000页的”AGENTS.md”灾难中吸取教训，发展出了”地图而非百科全书”的知识管理范式——用100行的入口文档+结构化知识库，让Agent和人类都能高效导航复杂系统。

百科全书模式的失败

OpenAI 的 Harness 工程团队开始时犯了一个错误——这个错误你我可能都犯过。

他们写了一个巨大的 AGENTS.md 文件。

想象一下：一份试图涵盖所有规则、所有模式、所有注意事项的百科全书。团队满怀信心地认为，只要把足够的知识塞进去，AI Agent 就能像经验丰富的工程师一样工作。

结果？惨败。

百科全书模式的四大原罪

1. 上下文是稀缺资源

当 Agent 的上下文窗口被一本百科全书占据，留给实际任务、代码和相关文档的空间就被挤压殆尽。Agent 要么错过关键约束，要么开始优化错误的目标。

就像让人一边背诵整本《新华字典》一边写小说——不是知识没用，是加载方式错了。

2. “什么都重要 = 什么都不重要”

当文档中的每一条规则都被标记为”关键”，Agent 失去了优先级判断能力，只能在局部进行模式匹配，而不是有意识地导航。

💡 Key Insight

当文档中的每一条规则都被标记为关键，Agent 失去了优先级判断能力。

3. 文档迅速腐烂

一本单片化的手册很快就会变成”规则的墓地”——过时的约束、失效的假设、无人维护的警告混杂在一起。Agent 无法分辨哪些仍然有效，人类也懒得维护。

4. 无法机械化验证

单个 Blob 文档不适合进行覆盖率检查、新鲜度验证、归属追踪或交叉链接检查。漂移是不可避免的。

💡 Key Insight

单个 Blob 文档不适合进行覆盖率检查、新鲜度验证、归属追踪或交叉链接检查。

这不是 OpenAI 独有的问题。任何尝试过用大型知识库驱动 AI 的团队，都可能遇到同样的困境。

从百科全书到地图

从百科全书到地图

OpenAI 的解决方案简单而深刻：

把 AGENTS.md 当作地图，而不是百科全书。

渐进式披露

Agent 不再被大量信息淹没 upfront。它从一个小且稳定的入口点开始，被教导”下一步去哪里看”，而不是一次性加载所有内容。

💡 Key Insight

Agent 不再被大量信息淹没 upfront。它从一个小且稳定的入口点开始。

就像人类阅读技术文档一样：先看目录，再深入感兴趣的章节。

核心转变

百科全书模式 地图模式
前端加载所有知识 按需加载
扁平化的规则列表 层次化的导航结构
人类维护为主 机械化验证为主
静态文档 活的知识系统

知识库的系统架构

OpenAI 的知识库不是随意堆砌的文档集合，而是一个精心设计的系统：

知识库的系统架构 所有计划都入库，Agent 可以在不依赖外部上下文的情况下操作。

机械验证：让知识自我维护

地图模式的关键优势：可以被自动化工具验证。

CI 验证分为三层。第一层：结构检查——所有文档文件必须在 frontmatter 中声明 last_verified 日期，且该日期距离当前时间不得超过 30 天。这一层在 pre-commit 阶段完成，漂移文档直接被挡在提交之前。第二层：链接验证——CI 在每次 PR 时运行 link-checker，验证所有交叉引用的文档是否存在、internal link 是否可达。这一层 catch 的是”文档孤岛”问题——有入口但无出口，或出口指向已删除文件。第三层：归属追踪——每个模块的架构说明必须通过 owner 字段关联到具体的 engineer 或 team，重大代码变更触发文档更新提醒，未在 7 天内更新的文档被标记为 stale。

当验证失败时，CI 会自动在 PR 中留下评论，注明哪条规则未被满足、哪个文档需要关注。失败记录也会同步到内部的文档仪表盘，由”文档园丁” Agent 统一处理。对于关键的架构文档，还可以配置覆盖率阈值——例如”某个 API 端点必须同时有对应的接口说明、错误码文档和SDK使用示例”，缺少任一项都会触发告警。

文档园丁 Agent

OpenAI 部署了一个专门的 Agent：

这个 Agent 每周运行一次，主动发起文档修复 PR。

实践指南：构建你的知识地图

如果你正在或计划引入 AI Agent 到你的工程流程，以下是基于 OpenAI 经验的具体建议：

第1周：限制入口文档长度

目标：100 行以内。它应该回答三个问题：

  • 这个系统的核心目标是什么？
  • 从哪里开始理解架构？
  • 如何找到特定领域的详细文档？

第2-4周：建立机械验证机制

为知识库设计 CI 检查：

  • 所有文档文件必须有最后更新日期
  • 交叉链接必须有效
  • 每个模块必须有对应的架构说明

第5-8周：任命”文档园丁”

无论是人类还是 Agent，必须有人/系统负责：

  • 定期扫描陈旧文档
  • 对比代码行为与文档描述
  • 主动发起修复

第2个月起：渐进式采纳

不要试图一次性重构所有文档。从新建模块开始：

  • 新模块使用 Harness 知识管理模式
  • 旧模块逐步迁移
  • 允许两者共存

反直觉洞察

洞察 1：知识管理的终极目标是遗忘

地图模式让工程师可以安全地遗忘。不需要记住所有细节，只需要知道去哪里找。这是认知卸载的艺术。

洞察 2：约束催生创造力

100 行的 AGENTS.md 限制看似束缚，实则解放。它迫使团队思考：什么才是真正重要的？

洞察 3：Agent 友好 = 人类友好**

为 Agent 设计的知识系统，往往对人类也更友好。渐进式披露、结构化信息、机械化验证——这些对两者都是福音。

今日毒舌

OpenAI 从百科全书到地图的转变，本质上是一个残酷的自我认知过程。

承认的勇气

他们终于承认，自己写的那些长篇大论的文档，连人类都懒得看，更别说 Agent 了。

这就像一个写了 20 年技术文档的老工程师突然发现：那些他引以为傲的”详尽文档”，实际上只是数字垃圾——占着磁盘空间，浪费着后来者的生命。

但问题是：在没有 Agent 强制约束之前，有多少团队会主动清理自己的文档墓地？

也许 Harness 工程的最大价值，就是给了我们一个借口——不，是一个理由——去正视那个被忽视已久的问题：

我们的知识管理，从一开始就是一团糟。

结语

从百科全书到地图的转变，听起来像是一个技术细节。但它实际上代表了软件工程中知识管理的范式转移：

  • 从静态文档到活的知识系统
  • 从人类可读到人机双可读
  • 从被动维护到主动验证

OpenAI 用 5 个月和 100 万行代码证明：当知识被正确结构化，Agent 可以成为真正的生产力倍增器。

而人类工程师的角色，也从”知识的管理者”转变为”知识系统的设计师”。

这正是 Harness 工程的核心洞察。

深度阅读时间：约 7 分钟

参考来源：

  • OpenAI: Harness engineering: leveraging Codex in an agent-first world
  • George: Harness 工程就是控制论

← 返回 AI-Native 工程系列