地图而非百科全书：Harness 工程的知识管理革命

TL;DR

给 AI Agent 一本百科全书，它会迷失；给它一张地图，它会探索。

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

📋 本文结构

一场预料之中的失败 —— 当百科全书成为累赘
地图思维的核心原则 —— 渐进式披露的艺术
知识库的系统架构 —— 不是文档堆，而是信息基础设施
机械验证：让知识自我维护 —— 文档园丁 Agent 的诞生
实践指南：构建你的知识地图 —— 从明天开始的具体步骤
反直觉洞察 —— 关于知识管理的三个悖论
结语 —— 知识管理的终极目标是遗忘

一场预料之中的失败

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

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

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

结果？惨败。

百科全书模式的四大原罪

1. 上下文是稀缺资源

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

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

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

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

3. 文档迅速腐烂

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

4. 无法机械化验证

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

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

地图思维的核心原则

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

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

渐进式披露

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

AGENTS.md (约100行)          → 作为目录/入口点
docs/ (结构化知识库)          → 作为真相来源

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

核心转变

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

知识库的系统架构

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

repository/
├── AGENTS.md              # 入口点 (~100行)
├── docs/
│   ├── beliefs/          # 核心信念与原则
│   │   └── 验证状态追踪
│   ├── architecture/     # 架构地图
│   │   └── 领域与包分层
│   ├── quality/          # 质量评估
│   │   └── 各领域健康度
│   ├── plans/            # 执行计划
│   │   ├── active/       # 进行中
│   │   └── completed/    # 已完成
│   └── debt/             # 已知技术债务
└── .ci/
    └── knowledge-linter/ # 知识库验证工具

设计文档的目录化

每份设计文档都有元数据：

---
title: "用户认证模块设计"
status: verified      # verified | stale | deprecated
last_verified: 2026-03-15
owner: @alice
beliefs:
  - "JWT 适合无状态认证"
  - "刷新令牌应该旋转"
related:
  - docs/architecture/auth-domain.md
  - plans/active/oauth-migration.md
---

计划作为一等公民

在 Harness 工程中，计划不是临时的待办事项，而是版本化的产物：

# plans/active/api-v2-migration.md

## 目标
将 REST API 迁移到 GraphQL

## 决策日志
- 2026-03-10: 选择 GraphQL 而非 tRPC（原因：前端团队熟悉度）
- 2026-03-12: 决定分阶段迁移（原因：零停机要求）

## 当前状态
Phase 1: 用户模块 ✅
Phase 2: 订单模块 🔄 (50%)
Phase 3: 支付模块 ⏳

## 阻塞项
- 等待 @bob 完成支付服务的测试覆盖

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

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

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

文档园丁 Agent

OpenAI 部署了一个专门的 Agent：

# doc-gardener-agent.py (概念示意)

def scan_knowledge_base():
    for doc in docs.walk():
        # 检查最后验证日期
        if doc.last_verified < today() - timedelta(days=30):
            # 检查文档是否与代码一致
            if not verify_against_code(doc):
                create_fix_pr(doc, "文档与代码不符")
        
        # 检查死链接
        for link in doc.links:
            if not link.exists():
                create_fix_pr(doc, f"死链接: {link}")
        
        # 检查 orphaned 文档
        if not doc.has_incoming_links():
            flag_for_review(doc, "孤立文档")

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

CI 验证规则

# .github/workflows/knowledge-check.yml
name: Knowledge Base Validation

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - name: Check doc freshness
        run: |
          ./scripts/check-doc-freshness.sh --max-age 30
      
      - name: Verify cross-links
        run: |
          ./scripts/verify-cross-links.sh
      
      - name: Check orphaned docs
        run: |
          ./scripts/check-orphaned-docs.sh
      
      - name: Validate ADR format
        run: |
          ./scripts/validate-adr-format.sh

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

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

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

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

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

# AGENTS.md 示例结构

## 系统目标
这是 X 服务，负责 Y 功能。

## 架构入口
- 整体架构: docs/architecture/overview.md
- 领域划分: docs/architecture/domains.md
- 包结构: docs/architecture/packages.md

## 工作方式
- 代码风格: docs/style-guide.md
- 提交规范: docs/commit-conventions.md
- 测试要求: docs/testing-guidelines.md

## 快速参考
- 常用命令: docs/cheatsheet.md
- 故障排查: docs/troubleshooting.md
- 关键决策: docs/decisions/

第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 工程的核心洞察。

参考来源：

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

← 返回 AI-Native 工程系列