本章你将学到
- 知识库的整体信息架构——AGENTS.md（地图）→ ARCHITECTURE.md（图谱）→ docs/（正文）的三层关系；
- OpenAI 那套可直接抄的 docs/ 目录范例，逐项解析每类文档的职责；
- 渐进式披露（Progressive Disclosure）的信息架构：小而稳定的入口 → 引导去哪找 → 按需深入；
- 索引与交叉链接工程——如何让 Agent 能"导航"而非"搜刮"；
- 面向 Agent 的文档与面向人的文档，到底有什么不同。
从"知识要进仓库"到"知识怎么摆"
第 15 章立住了原理：知识必须进仓库。但只是"进仓库"还不够——一堆杂乱堆放、互不链接、层级不清的文档，会让 Agent 和人一样迷失。更糟的是，Agent 的上下文窗口有限（第 2 章上下文经济学），你不可能把整个知识库一股脑塞给它。知识库不仅要"全"，更要"结构化"到 Agent 能高效导航。
OpenAI 给出了一套经过百万行代码、上千个 PR 验证的知识库结构。本章就把这套结构逐项拆开，让你能直接照着搭。它的核心思想只有一句：让知识库成为一张 Agent 能自己走的地图，而不是一座需要它硬闯的迷宫。
本章源级：本章为 A 级。docs/ 的完整目录结构、AGENTS.md 约 100 行作为地图、design-docs（含 index、core-beliefs、验证状态）、exec-plans、generated、product-specs、references（llms.txt）、QUALITY_SCORE.md 及各专题文档、"渐进式披露"、机制化校验等，均为 OpenAI 明确记载的一手事实（原文附目录树）；对每类文档职责的展开解释与写作规范为本书的工程化整理（B 级）。
16.1 整体信息架构：地图 → 图谱 → 正文
先看最顶层的三层结构。OpenAI 的知识库入口是这样组织的：
- AGENTS.md —— 地图（约 100 行）：这是被注入上下文的入口文件，故意保持简短（约 100 行）。它本身不承载大量知识，而"主要用作一张地图，指向别处更深的事实来源"。它回答的是"要了解 X，去哪看"，而不是把 X 的全部内容都塞进来。
- ARCHITECTURE.md —— 图谱：提供领域与包分层的顶层地图——有哪些业务领域、它们如何分层、依赖方向如何。它让 Agent 在动手前先建立起对整个系统结构的鸟瞰。
- docs/ —— 正文：结构化的知识主体，被当作记录系统（system of record）。所有深入的设计、规格、参考、生成文档都住在这里，按类别分门别类。
这三层的关系，恰如"地图 → 分区图 → 详细条目"：AGENTS.md 告诉你这座城市有哪些区、该去哪个区；ARCHITECTURE.md 给出各区的布局；docs/ 里才是每个地点的详细信息。关键在于入口（AGENTS.md）必须小而稳定——因为它每次都要进上下文，太大就会挤占 Agent 的上下文预算（第 2 章），太频繁变动则会破坏它作为稳定锚点的价值。
回扣 Harness：这个三层结构是第 2 章"上下文经济学"的直接产物。上下文窗口是稀缺资源，所以入口只放"地图"（少量、稳定、高价值的导航信息），把"正文"留在 docs/ 里按需加载。这与第 8 章 Skills 的"按需加载"、第 6 章 AGENTS.md 的"精简"是同一条原则在知识库层的体现。
16.2 完整目录范例逐项解析
下面是 OpenAI 公开的 docs/ 目录结构（一手事实），我们逐项解析每类文档的职责：
AGENTS.md
ARCHITECTURE.md
docs/
├── design-docs/
│ ├── index.md
│ ├── core-beliefs.md
│ └── ...
├── exec-plans/
│ ├── active/
│ ├── completed/
│ └── tech-debt-tracker.md
├── generated/
│ └── db-schema.md
├── product-specs/
│ ├── index.md
│ ├── new-user-onboarding.md
│ └── ...
├── references/
│ ├── design-system-reference-llms.txt
│ ├── nixpacks-llms.txt
│ ├── uv-llms.txt
│ └── ...
├── DESIGN.md
├── FRONTEND.md
├── PLANS.md
├── PRODUCT_SENSE.md
├── QUALITY_SCORE.md
├── RELIABILITY.md
└── SECURITY.md
逐类拆解：
-
design-docs/ —— 设计文档：编目并建立索引（
index.md），且记录每份文档的验证状态（这份设计是否已在代码中落地/验证）。其中的core-beliefs.md尤其关键——它定义了"智能体优先"的核心信念，即这个项目做技术决策时的底层价值观（比如"偏好无聊而稳定的技术"）。核心信念是最高层的品味约束，它统摄着下面所有具体规则。 -
exec-plans/ —— 执行计划：计划被当作一等产物（第 17 章详述）。目录分为
active/（进行中）、completed/（已完成）和tech-debt-tracker.md（技术债追踪），全部版本化、集中存放，让 Agent 无需外部上下文就能知道"现在在做什么、做过什么、欠着什么"。 -
generated/ —— 自动生成文档：如
db-schema.md，由工具从真实代码/数据库自动再生成（第 18 章）。这类文档的要害是"绝不手写、只由流水线产出"——因为手写的生成类文档必然滞后于真实结构。 -
product-specs/ —— 产品规格：带索引（
index.md）的产品规格文档（如new-user-onboarding.md），把"要做成什么样"讲清楚。这是"意图"落库的地方，与第 17 章的规格撰写工程呼应。一份对 Agent 友好的产品规格，至少应包含五个要素：目标与背景（这个功能为谁解决什么问题、为什么现在做）、用户故事或使用场景（谁、在什么情境下、期望得到什么）、可执行的验收标准（用 "Given/When/Then" 或明确的输入输出对写清"做成什么样才算对"——这是 Agent 能据以自检、也是任何传感器唯一能对齐的正确性锚点）、明确的边界与非目标（这次不做什么，专门用来遏制 Agent 过度设计、擅自扩张范围）、以及未决问题（还没拍板、需要人类澄清的点，显式留白胜过让 Agent 猜）。把这五项写全，规格才既是给人看的意图说明，又是给 Agent 用的验收契约（验收标准如何驱动行为验证，详见第 17、28 章）。 -
references/ —— 第三方参考：注意这里的文件名后缀是
-llms.txt（如uv-llms.txt、nixpacks-llms.txt）——这是专为 LLM 准备的第三方库参考文档。与其让 Agent 去联网搜一个库的用法（不可控、可能过时），不如把该库的权威用法以 llms.txt 形式沉进仓库，让 Agent 有一份稳定、可信的本地参考。 -
专题根文档：
DESIGN.md、FRONTEND.md、SECURITY.md、RELIABILITY.md、PRODUCT_SENSE.md等，各自承载一个横切主题（cross-cutting concern）的深入规范。所谓"横切"，是指这些主题不隶属于某一个业务模块，而是贯穿所有模块——任何一处代码都可能触及安全、可靠性、前端约定。把它们各自收进一份稳定、可被指针指向的根文档，Agent 处理相关任务时就能被精准导航到唯一权威来源，而不必在散落各处的注释里拼凑。逐份看它们各自该写什么：SECURITY.md：安全编码的红线与规范——鉴权/授权怎么做、敏感数据如何处理、哪些操作绝对禁止、输入在哪些边界必须校验。它是第 25 章"安全边界"、第 27 章"安全适应度"在知识库里的落点。RELIABILITY.md：可靠性约定——错误处理规范、超时与重试策略、降级与熔断、幂等性要求。对应第 27 章的可靠性驾驭。DESIGN.md：全局设计原则与架构风格——分层规则、依赖方向、命名与结构约定等统摄性的设计取舍（与design-docs/的区别见下）。FRONTEND.md：前端专属约定——组件规范、状态管理、样式体系、可访问性要求等只在前端生效的规则。PRODUCT_SENSE.md：产品品味与体验准则——把"什么是好的用户体验"这类原本靠资深产品直觉的判断，显式写成 Agent 可依据的准则。
这里有一个容易混淆、必须讲清的分界：专题根文档 vs
design-docs/。专题根文档是长期稳定的"宪法级"规范——它规定"我们在这个主题上永远遵守什么"，变动很慢；而design-docs/里是一份份具体的、带决策理由与验证状态的设计档案——它记录"某个具体功能/模块当时是怎么设计的、为什么"。前者是稳定的规则集，后者是可增长的设计历史。一条新的安全约定，往往先在某份具体设计里被提出（design-docs），一旦升格为"所有代码都必须遵守"，就应被提炼进SECURITY.md。 -
QUALITY_SCORE.md —— 质量评分：一份给每个产品领域和架构层评级、并随时间追踪差距的文档。它把"我们哪块质量好、哪块欠债"从模糊感觉变成了显式、可追踪的记录。具体怎么写？给每个领域（如支付、订单、用户）和每个架构层（如 Service、Repo）打一个分级（例如 A/B/C/D，或"达标/有缺口/高风险"），并为每一格附上评级维度——典型维度包括：测试覆盖与质量、类型严格度、架构合规度、文档新鲜度、已知技术债规模。但关键不在分数本身，而在每格后面那句"差距说明 + 下一步"：为什么是 C、缺什么、打算怎么补。这样它就同时是一张"质量地图"（Agent 和人一眼看清该优先加固哪里）和一份"待办来源"（垃圾回收 Agent、文档园艺 Agent 可据此自动派活）。这是把质量本身也纳入知识库管理的精彩一笔（评级如何驱动后台清理，第 22、23 章会再展开）。
这套结构的可抄之处在于：它按"知识的种类"而非"随意"来切分目录，每一类都有明确职责和索引入口。你不必照搬每个文件名，但这套分类法（设计/计划/生成/规格/参考/专题/质量）几乎适用于任何项目。
举个把自己项目往这套分类上套的例子。假设你维护一个普通的电商后端："下单/支付/库存各模块的职责与依赖方向"属于架构图谱，进 ARCHITECTURE.md；"为什么支付金额统一用分存整数"这类带着决策理由的设计，进 design-docs/；"会员等级体系该做成什么样"进 product-specs/；数据库表结构进 generated/（自动再生成）；支付安全、幂等、重试等横切主题各自一份专题根文档（如 SECURITY.md）。真正需要你拿主意的不是"该不该分类"，而是"这条知识属于哪一类"——而这个判断，恰恰又回到了第 15 章的新员工测试：一个新人会到哪个目录去找这条知识，它就该放在那里。
core-beliefs.md 值得单独再说一句，因为它是整棵知识树的根。所谓"核心信念"，是那些统摄具体规则的最高层价值观——比如"偏好无聊而稳定的技术（boring technology）""宁可多写一点重复代码，也不引入错误的抽象"。它的价值在于：当具体规则没覆盖到某个新情境时，Agent（和人）可以回到核心信念去推导该怎么做，而不是卡死或胡乱发挥。没有核心信念，下面的几百条具体规则就是一盘没有灵魂、彼此可能矛盾的散沙。
最后，把上面每类文档的"该写什么"浓缩成一张可随手对照的模板要点速查表——不确定某类文档到底该写成什么样时，照着"必备要点"填、拿"反面信号"自检即可：
| 文档/目录 | 核心职责 | 必备要点 | 反面信号（写歪了） |
|---|---|---|---|
AGENTS.md | 地图/入口 | 约 100 行、只给"要了解 X 看 Y"的指针、稳定 | 变成百科全书、塞满细节、频繁大改 |
ARCHITECTURE.md | 图谱 | 领域划分、分层、依赖方向的鸟瞰 | 陷入某个模块的实现细节 |
design-docs/ | 具体设计档案 | 每份含决策理由、验证状态；带 index、core-beliefs | 只有结论没有"为什么"、无索引 |
product-specs/ | 意图/验收契约 | 目标、场景、可执行验收标准、边界与非目标、未决问题 | 只写"做个 X"、无可执行验收标准 |
generated/ | 派生事实 | 从真实来源自动再生成、绝不手写、CI 校验一致 | 有人手改、与来源漂移 |
references/ | 第三方参考 | -llms.txt 形式、权威用法沉本地 | 让 Agent 联网现搜、版本不定 |
| 专题根文档 | 横切主题"宪法" | 稳定的红线与规范、可被指针指向 | 与 design-docs 职责混淆、随每次改动而变 |
QUALITY_SCORE.md | 质量地图 | 分领域分层评级 + 每格差距说明与下一步 | 只有分数、无差距解释、从不更新 |
16.3 渐进式披露：小入口 → 被引导 → 按需深入
这套结构服务于一个核心的信息架构原则——渐进式披露（Progressive Disclosure）。OpenAI 明确点出它的目标：
"这实现了渐进式披露：智能体从一个小而稳定的入口点开始，并被引导下一步该查看何处，而非一开始就面临信息过载。"
拆开看，渐进式披露有三个动作：
- 小而稳定的入口：Agent 每次从约 100 行的 AGENTS.md 出发。入口小，就不会一上来就吃掉大半个上下文窗口；入口稳定，就成了一个可靠的起点锚。
- 被引导去哪里找：入口不直接给答案，而是给指针——"要改架构，看 ARCHITECTURE.md""要了解鉴权，看 docs/SECURITY.md"。Agent 顺着指针，只加载当前任务真正需要的那部分知识。
- 按需深入：只有当任务确实需要某块深入知识时，Agent 才去读对应的详细文档。不相关的知识永远不进它的上下文。
这与它的反面——"一次性把所有文档都塞进上下文"——形成鲜明对比。后者不但会撑爆上下文预算，还会用大量无关信息淹没真正相关的部分，反而降低 Agent 的判断质量（这正是第 2 章、第 6 章反复强调的"信息过载即噪声"）。
把三个动作串成一次真实的任务走查，就能看到渐进式披露是怎么节省上下文的。假设你让 Agent 去"给登录接口加一个限流"：① 它先读约 100 行的 AGENTS.md，从中看到"安全相关看 docs/SECURITY.md、限流约定看 docs/RELIABILITY.md"；② 它不会去加载无关的 FRONTEND.md 或产品规格，只顺指针打开这两份；③ 在 RELIABILITY.md 里它读到"限流统一用中间件 X、配置见某文件"，才再顺链接深入到具体实现。全程下来，Agent 的上下文里只装进了与当前任务直接相关的两三份文档，而不是整个知识库。这就是"地图 + 指针 + 按需"三者合作的实际收益。
回扣 Harness：渐进式披露本质是一种上下文的惰性加载（lazy loading）。它把"知识库很大"和"上下文窗口很小"这对矛盾，用"分层 + 指针 + 按需"化解掉。这也解释了为什么入口文件的价值不在于"写了多少"，而在于"能把 Agent 精准导航到哪里"——一个好的 AGENTS.md，是一张好地图，不是一本百科全书。
16.4 索引与交叉链接工程：让 Agent"导航"而非"搜刮"
渐进式披露能成立，靠的是一套扎实的索引与交叉链接（cross-linking） 工程。如果文档之间没有链接、没有索引，Agent 就只能靠全文搜索去"搜刮"（grep 式地大海捞针）——这既慢、又不可靠、还容易抓错。理想状态是让 Agent 像人点超链接一样"导航"。
要做到"可导航"，有几条关键实践：
- 每个目录有
index.md：如 design-docs 和 product-specs 都带索引。索引是这一类文档的"目录页"，Agent 读一个索引就知道这类下有什么、各自讲什么、该点哪个。 - 稠密的交叉链接：文档之间用明确的相对路径链接互相指引（"详见
docs/SECURITY.md"）。链接让知识形成一张可遍历的图，而不是一堆孤岛。 - 指针优于复制：当 A 文档需要 B 的知识时，链接到 B，而不是把 B 的内容复制一份过来。复制会制造两份会各自漂移的副本（第 18 章腐化）；链接则保证单一事实来源。
- 入口指向深处：AGENTS.md 作为总地图，把最常见的任务类型直接映射到对应的深入文档，让 Agent 一步就能找到起点。
OpenAI 把这套"可导航性"上升到了机制强制的高度：他们用"专用 linter 和 CI 任务，验证知识库是否处于最新状态、正确交叉链接且结构无误"。也就是说，"交叉链接的完整性"不是靠自觉维护，而是被当作一条可被传感器（第 11 章）检查的硬约束——断链会被 CI 抓出来（第 18 章的知识库健康度）。
为什么这件事非机制化不可？因为断链是知识库里最隐蔽、最高频的腐化形式。设想有人把 docs/auth.md 重命名为 docs/security-auth.md，却漏改了另外三处指向它的链接。人读到时顶多多点一下发现 404、手动搜一下就找到了；但 Agent 顺着一个指向不存在文件的链接走去，拿到的就是空——那块知识对它瞬间从"存在"变成了"不存在"（第 15 章第一性原理）。一条能自动检出断链的 CI，本质上就是在用机械手段守住渐进式披露赖以成立的那张"可遍历的图"。
16.5 面向 Agent 的文档 vs 面向人的文档
最后一个关键认知：为 Agent 写的文档，和为人写的文档，写法不一样。 这是第 13 章"面向 LLM 的信号设计"在文档层的延伸。二者的差异主要体现在：
- 结构 vs 叙事：人喜欢有起承转合的叙事性文档；Agent 更吃结构化、可定位的信息——清晰的标题层级、要点列表、明确的字段，便于它精准提取所需片段，而不必读完整篇。
- 显式 vs 默契：面向人的文档可以依赖读者的背景知识和"言外之意"；面向 Agent 的文档必须自包含、显式——把前提、约束、原因都写明，不留需要"悟"的空白（第 15 章第一性原理：没写的等于不存在）。
- 稳定的锚点：Agent 靠标题、路径、锚点来定位和引用。文档应有稳定、语义化的标题与结构，方便被链接和被检索。
- 意图与原因：既要写"是什么/怎么做"，也要写"为什么"。理解了原因的 Agent，更可能做出符合意图的决策，而不是机械照搬或粗暴绕过（第 13 章报错写作规范里的 Why 同理）。
- 适度而非冗长：文档不是越多越好。冗余、过时、面面俱到的文档会稀释信号、增加维护负担（第 6 章过度指导、第 18 章腐化）。写"Agent 真正需要、且代码本身说不清"的那部分（第 15 章新员工测试）。
一个好的检验标准是：把这份文档丢给一个没有任何背景的 Agent，它能不能仅凭这份文档 + 代码，正确完成相关任务？ 如果不能，说明文档还依赖着某些没写出来的隐性上下文；如果读起来啰嗦冗余、Agent 得费劲筛选，说明信噪比还不够高。
把一段"面向人"的文档改写成"面向 Agent"，差别一目了然。面向人的写法往往是："我们的鉴权模块经历了几次演进，早期用的是 Session，后来因为要支持多端登录慢慢迁到了 Token 方案，具体可以问问张三。"这段话对老员工亲切，对 Agent 却几乎无用——它不知道现在到底用哪个、也问不到张三。改成面向 Agent："鉴权一律使用 JWT（不再使用 Session）。签发逻辑在 auth/token.ts，校验中间件在 middleware/auth.ts。为什么用 JWT：需支持多端无状态登录。禁止新增任何 Session 依赖。"后者把现状、位置、原因、约束全部显式化，且不依赖任何人的记忆——这才是 Agent（和新人）真正能用的文档。
本章要点
- 三层信息架构：AGENTS.md（地图，约 100 行、进上下文、只给指针）→ ARCHITECTURE.md（图谱，领域与分层鸟瞰）→ docs/（正文，记录系统）。入口必须小而稳定。
- 可抄的 docs/ 目录（OpenAI 一手事实）：design-docs（含 index、core-beliefs、验证状态）、exec-plans（active/completed/tech-debt）、generated（自动再生成）、product-specs（带索引）、references（
-llms.txt第三方参考）、专题根文档、QUALITY_SCORE.md（分领域分层评级追踪差距）。按知识种类切分，每类有索引。 - 渐进式披露：小而稳定的入口 → 被引导去哪找 → 按需深入。本质是上下文的惰性加载，化解"知识库大 vs 上下文小"的矛盾。好入口是好地图，不是百科全书。
- 索引与交叉链接工程：每目录带 index.md、稠密交叉链接、指针优于复制、入口指向深处，让 Agent 能"导航"而非"搜刮"；交叉链接完整性被 CI 机制化强制。
- 面向 Agent 的文档不同于面向人：结构优于叙事、显式优于默契、稳定锚点、写清"为什么"、适度而非冗长。检验标准：无背景 Agent 仅凭文档+代码能否正确完成任务。
动手练习
- 给你的项目搭一个 docs/ 骨架。 参照 §16.2 的分类（设计/计划/生成/规格/参考/专题/质量），为你的项目建一套目录骨架，并为每个目录写一个
index.md。哪怕先只填一两篇，也先把"地图"立起来。 - 给 AGENTS.md 瘦身成地图。 如果你的 AGENTS.md 又长又杂，把其中的"深入内容"抽到 docs/ 对应文档里，只在 AGENTS.md 留下"要了解 X 去看 Y"的指针，让它回到约 100 行的地图形态。观察 Agent 是否更少地被无关信息干扰。
- 做一次交叉链接体检。 挑几份现有文档，检查它们之间该有的链接是否存在、有没有靠"复制内容"代替"链接"、有没有断链。修好它们，让你的知识库从"一堆孤岛"变成"一张可遍历的图"。
承上启下：本章解决了知识库的静态结构，但目录树里那个
exec-plans/还没细讲——它藏着 Agent 长任务自主性的一个关键支撑。第 17 章「计划即产物：执行计划工程」 将展开为什么"计划"应当是一等公民：它是 Agent 长任务的外部记忆与断点续传，是决策日志的载体，也是"明确意图"这一新工程师职责的落点。我们还会讲透规格（Spec）撰写工程——因为正如 OpenAI 所言，"如果人类没说清楚要什么，正确性就不在任何传感器的职权范围内"。
