AI 时代的文档工程

研究问题、方法与边界

本研究回答的不是"怎样写 Markdown"，而是：当技术文档的高频消费者同时包括人类、LLM、RAG Pipeline 和能读写代码/调用工具的 Agent 时，什么样的文档系统可以长期可靠地支持理解、检索、规划与执行。

研究遵循"事实 → 机制 → 实践 → 原则"的路径。事实材料优先采用公开规范、官方开发者文档、官方工程博客、官方 GitHub 仓库和学术论文；机制材料用于解释上下文、检索和长文本限制；项目案例检验这些机制是否已转化为真实工程实践。案例覆盖 OpenAI Codex、Anthropic Claude Code、GitHub Copilot、Cursor、Gemini CLI、AGENTS.md、Agent Skills、MCP、OpenAPI、GitHub Docs、Kubernetes、FastAPI 与 Docusaurus 等 13 个项目或生态。

这里必须区分三类结论。第一类是可由来源直接核验的事实，例如 Codex 的 AGENTS.md 发现顺序、OpenAPI 的 Schema 能力、或 Kubernetes 的参考文档生成链。第二类是对这些事实和研究结果的机制解释，例如为什么路径作用域会影响 Agent 的上下文污染。第三类是本报告提出的工程建议，它们以"应当""适合""在……条件下"等条件化语言表达，不能被误读为已有统一国际标准。

本研究也有边界。不同 Agent 对指令文件的发现、合并、覆盖与 token 预算有不同实现；一个工具的加载语义不能被外推为普遍规律。RAG 的检索质量还取决于语言、语料、嵌入模型、重排器、查询分布和评测集；任何单一厂商实验的提升百分比都不等于跨场景承诺。最后，prompt 或文档会影响 Agent 行为，但不能替代权限、审批、沙箱、CI 和测试等强制控制。

传统文档方法论：哪些仍然成立，哪些不足

传统技术写作并非 AI 时代的对立面。Diátaxis 将文档区分为 tutorial、how-to guide、reference 和 explanation：教程支持学习，指南支持完成目标，Reference 提供工作所需的准确事实，Explanation 提供理解背景。这套划分仍然极其重要，因为混合内容会同时损害人的阅读和机器的定位。若一个 API Reference 掺入大量设计史，检索到它的 Agent 需要在事实、意见和历史之间自行裁决；若一个 Runbook 混入教程式背景，值班者和自动化系统都会更难找到下一步动作。

Google 的工程文档实践同样没有过时：文档应与代码在同一变更中更新，陈旧、错误或冗余内容应被删除；README 的职责是为目录定向并链接到深入材料；方法行为文档在适当时应有测试验证。这是一条重要的反 AI Slop 原则：文档数量、标题数量和"AI-ready"标签都不是质量指标。比起庞大但不可靠的知识库，"少量、新鲜、准确"的材料更有价值。

但是，传统方法论主要假设读者会在页面级别主动浏览，并能从连续叙述中恢复指代、范围和例外。它对四个新问题没有充分规定：其一，文档如何被发现和选择；其二，内容在被切分、嵌入和拼接后是否仍自洽；其三，多个文件、版本和来源冲突时谁优先；其四，Agent 按文本行动时，行动是否受权限、Schema 和测试约束。传统写作原则仍是必要条件，但 AI-native 工程要求在其上增加加载、检索、权威、验证和安全层。

LLM 如何消费文档：从 Context 到 Action 的机制

3.1　文档不是被"读完"，而是被多次变换

在典型 RAG 中，语料会被切为小块，转换为向量并储存在索引中；用户查询到来后，系统选取相关块加入模型提示。Anthropic 对这一过程的说明指出，片段通常只有数百 token，向量检索擅长语义关系，但精确错误码、专有名词等词法匹配可能需要 BM25 一类机制补充。因此，文档并不以原有页面结构直接到达模型；它首先经历了切分、索引、召回、重排和上下文拼接。

这解释了一个常见但隐蔽的问题。假设某片段只写"将它设为 true"或"收入增长 3%"。对人类读者而言，前后段落也许提供了对象、版本和时间；对被独立检索的模型而言，这个片段既难以准确召回，也无法安全解释。Anthropic 以"某公司某季度收入增长"的例子说明了这种上下文丢失，并提出为每个 chunk 前置短的、面向整体文档的解释性上下文。其特定实验报告称，上下文嵌入与 BM25 组合将 top-20 检索失败率从 5.7% 降至 2.9%，加入重排后降至 1.9%。这些数字只能说明该方案在其测试条件下有效，但其机制结论更具普适性：可检索单元必须有足够的局部身份与语义闭合。

长上下文也没有取消这个问题。Liu 等人在多文档问答和键值检索中发现，相关信息的位置会显著影响模型表现；信息位于长输入的开头或结尾时通常更易被利用，位于中部时则可能明显退化，即使是标称长上下文模型。另一项 ICLR 研究发现，检索增强与长上下文不是非此即彼：在其评估中，短上下文加简单检索可与长上下文方案相近，而检索也能继续改善扩展上下文模型的结果。对文档工程而言，结论不是"永远不要写长文"，而是不要把关键规则只埋在长文中部，也不要因为模型窗口增长而放弃目录、摘要、局部 Reference 和索引。

3.2　七阶段消费链

该模型表明，"写得清楚"最多直接改善定位与解释的一部分；它无法单独保证发现、权威、验证或反馈。AI-native 文档工程必须对整个链条负责。

3.3　Context Efficiency 不是压缩主义

上下文效率常被误解为"把文档写短"。更准确的定义是：在特定任务中，每个进入上下文的 token 是否贡献了可验证的理解或正确行动。短但含糊的指令会迫使 Agent 反复搜索和猜测；长但只在需要时加载的 Reference 可能非常高效。Agent Skills 的渐进披露设计正体现了这个思路：启动时仅加载名称和描述，相关任务触发后加载 SKILL.md，进一步的脚本、参考资料和资产再按需读取。

因此，效率问题应被设计为"常驻什么、何时读取什么、从哪一个权威源读取"，而不是单纯删字。高频、不可从代码推断、且对每次任务都有影响的规则可常驻；罕见故障、详细 API 细节、法律或运营边界应放到有明确触发条件的资源中。若无法解释某段为何必须每次进入上下文，它通常不应占据全局规则文件。

Human 与 AI Documentation：不是两份文档，而是不同投影

人类与 AI 的根本区别不在于后者"不会阅读"，而在于两者所处的信息环境不同。人可以浏览、停顿、回忆上下文、询问同事并凭常识判断文本地位；Agent 则受文件发现机制、路径作用域、检索器、token 预算、系统提示、工具权限和任务循环约束。人类需要理解和判断，Agent 还需要选择、执行和自我校验。

正确做法不是写一份自然语言文档，再为模型复制一份"关键词版"。复制会迅速产生语义漂移。应当维护一套权威知识图谱：Schema、测试、配置和代码等可计算资产保存"是什么"；概念、架构和 ADR 解释"为什么"；Guide、Runbook 和 Skill 表达"如何做"；索引和短规则解决"从哪里开始、何时加载"。人类与 AI 只是以不同入口和粒度访问这些相互链接的层。

文档的信息架构：Index → Contract → Context → Procedure → Verification → Record

本报告提出的 AI-native 信息架构不是一个固定目录，而是六种必要关系。项目可以改变目录名，但不能省略关系本身。

这一架构把文档从平面网站提升为可控的信息系统。例如，README 不应该塞满 API 字段和生产故障细节；它应定位到 Contract、Procedure 和 Context。API Reference 不应该承载完整的商业理由；它应指向 Schema 和相关 ADR。Runbook 不应复制所有架构背景；它必须链接到必要的事实源并把诊断/恢复流程写成独立的行动单元。每层都有不同更新频率、权限、验证器和风险。

5.1　文档原子化：以语义闭合而非长度决定边界

"应写长文还是小单元"没有统一字数答案。固定按 token、字符或页面长度切分，可能破坏变量、错误码、对象层级和因果关系；反过来，把全部知识留在一篇长文中又提高发现、检索和定位成本。应以语义闭合为标准：一个文档原子脱离全文后，仍能回答它描述谁/什么、适用于何处/何时、陈述属于事实还是规则、前置条件是什么、如何验证或继续行动。

应该拆分的典型信号包括：内容面对不同路径、角色或任务；有独立 owner、版本、权限或更新频率；有独立验证方式；或能独立回答一个明确问题。反之，一个强依赖前一步状态的迁移流程，不应为追求"原子化"拆成多个无法单独执行的卡片；它应作为一个程序原子保存，并以小节锚点、检查点和状态条件组织内部结构。

5.2　权威、版本与冲突：从"单一事实来源"到"可判定事实来源"

"代码是真相，文档总会过期"是一个危险的二元命题。代码确实可以是运行行为、类型和默认值的强证据，但它通常不能完整说明兼容性承诺、运维批准边界、架构取舍、服务等级、迁移窗口或用户工作流。正确目标不是消灭文档，而是为不同问题指定其 canonical source，并让冲突时的优先级可判定。

OpenAPI 清楚展示了这一点：它定义了同时供人和计算机理解 HTTP API 能力的结构化接口，且可被文档展示、客户端/服务端生成和测试工具使用。FastAPI 则把 Python 类型和模型转化为 OpenAPI/JSON Schema、交互文档和运行时校验。这些案例说明字段、请求、响应、错误码和安全模型等可结构化事实应尽量由可计算源生成或验证；但它们也不意味着架构动机、迁移策略、故障诊断和使用建议可以消失。

每个项目应维护一张 authority map：按主题声明 canonical source、派生页面、owner、适用版本、更新触发条件与冲突优先级。这样，Agent 在看到 README、Schema、ADR 和 Runbook 不完全一致时，不是猜测，而是有可查规则：执行配置和测试优先于说明文本；现行 Schema 优先于手工重述的字段表；最新 accepted ADR 优先于旧设计稿；高风险操作以批准的 Runbook、IaC 和权限策略为准。

Agent Documentation：不同文件应承担什么职责

6.1　README、AGENTS.md、Rules、SKILL.md、Runbook 的分工

6.2　为什么这些文件出现：加载算法已经成为信息架构的一部分

AGENTS.md 之所以成为一个独立生态，不是因为 README 突然"写得不够好"，而是因为 Agent 需要一个可预测、可发现、可以放置构建、测试、风格和安全上下文的入口。AGENTS.md 项目本身把它定义为"README for agents"，并建议在大型 monorepo 中使用嵌套文件。

但统一文件名并没有统一加载语义。Codex 在启动时构建指令链：先读取全局文件，再从项目根走到当前工作目录；每个目录最多选一个文件，靠近当前目录的内容在合并 prompt 中更晚出现，默认合并上限为 32 KiB。Claude Code 会加载目录树上的 CLAUDE.md/CLAUDE.local.md，并提供路径规则和自动记忆；它明确提醒这些文件是上下文而非强制配置，建议单个 CLAUDE.md 控制在约 200 行内。Cursor 使用带 frontmatter 的 Project Rules，支持全局、相关性、glob、手动与 AGENTS.md 多种装载方式，建议规则聚焦、可行动且引用 canonical 文件而不是复制内容。Gemini CLI 也支持全局、工作区和工具访问时即时发现的 GEMINI.md，并可显示实际拼接的 context。

这些差异导出一个重要原则：项目不应假定"放一个 AGENTS.md 就被所有 Agent 以同样方式理解"。应维护工具无关的 canonical instruction source，并对不同宿主建立薄适配层；适配层要说明发现路径、优先级、预算、导入/覆盖行为与核验命令。真正高风险的规则还须由 CI、Hook、权限或 Schema 强制，因为 prompt 中的"必须"不等于系统层面的"不能"。

6.3　Skill 是能力接口，而不是更长的规则文件

Agent Skills 规范要求一个 Skill 至少包含带 YAML frontmatter 的 SKILL.md，使用 name 和 description 进行发现，并鼓励将正文、脚本、参考资料和资产按照渐进披露组织：元数据启动时可见，指令在激活后加载，资源按需读取。GitHub Copilot 和 VS Code 也明确区分 custom instructions 与 Skills：前者适合几乎每项任务都相关的项目规则，后者适合可复用的专门流程、模板、脚本和资源。

因此，Skill 最好的来源不是模型凭空生成的"最佳实践"，而是实际任务中的成功步骤、失败修正、Schema、runbook、review 意见与可执行脚本。Agent Skills 的官方实践指南也强调从真实工作提取模式、执行后迭代、将高价值 gotcha、模板和验证循环编码进去。换言之，Skill 是将组织经验产品化的接口；若没有输入边界、验证器、失败处理和安全约束，它只是换了 frontmatter 的长提示词。

Documentation Engineering：Docs as Code 在 AI 时代的进一步演化

7.1　Docs as Code 的成熟部分

Docs as Code 已经具有明确的工程含义：文档源进入版本控制，通过 Pull Request 审查，经过构建、预览、lint、链接检查与发布，并与版本和贡献流程关联。GitHub Docs 的 content linter 基于 markdownlint 与定制规则，能在 pre-commit 和 CI 中检查 Markdown/Liquid；错误会阻止提交或导致 CI 失败，还可用到期标记提醒内容复审。这说明文档可以拥有与代码相近的生命周期、质量门禁和严重性分级。

Kubernetes 提供了更完整的"代码/版本 → 文档"链：其 update-imported-docs.py 从关联源码仓库和 release 版本生成组件、kubectl 与 API Reference，再将生成结果放入 website 仓库并通过 PR 评审和发布。它表明应尽可能把可导出的事实生成出来，而将人的精力投入语义、示例、权衡、操作风险与治理。

7.2　新增部分：将"文档作为上下文"和"文档作为接口"纳入工程闭环

AI-native 阶段新增的不是把 Markdown 换成某种格式，而是四个工程对象：

1. 上下文加载图。哪个任务在什么路径、哪个 Agent、什么预算下会加载哪些规则、Skill 和参考文件，必须可观察并可调试。
2. 检索和粒度评测。文档切分、标题、摘要、metadata、错误码和引用关系应以真实问题的 recall、正确引用、行动成功率和 token 成本评估，而不是凭直觉设"最佳 chunk size"。
3. 机器可读事实投影。Schema、类型、配置、测试、生成器和 Reference 建立双向追溯，减少人工复制造成的漂移。
4. 可执行内容的安全治理。Skill、脚本、MCP tool description、运行手册和外部资源可能影响实际行动，需要来源、版本、审查、最小权限、确认与审计。

MCP 的资源、提示和工具模型为这一分层提供了有用的参照。MCP 将 Resource 定义为上下文/数据、Prompt 定义为用户选择的模板化工作流、Tool 定义为模型可调用的函数，并明确把任意数据访问和代码执行视为需要同意与安全控制的风险。Tool 可定义输入/输出 JSON Schema，Resource 可带受众、优先级和最后修改时间等标注。这并非要求所有文档迁移到 MCP，而是提醒我们：知识、流程和行动具有不同的发现、权限、验证和安全语义，不能混成一段自由文本。

案例研究：13 个项目与生态揭示了什么

下表不是产品排名，而是比较不同团队如何把"文档"变成 Agent 可消费的上下文、接口或工程资产。

这些案例可以归纳为四组。

第一组是"指令即运行时上下文"。Codex、Claude Code、Copilot、Cursor 和 Gemini CLI 都把项目说明纳入模型上下文，但以不同的文件名、作用域、优先级和加载时机实现。这意味着 information architecture 已经不是网站导航问题，而是 prompt assembly 问题。根规则应只保留全仓库不变量；局部规则靠近代码边界；加载顺序、最大预算和冲突关系必须可观察。

第二组是"能力的渐进披露"。Agent Skills、VS Code 和 Copilot 将高频规则与专门流程分离。Skill 的 description 是发现索引，SKILL.md 是流程契约，references/assets 是按需证据和资源。这种设计不是把文档拆细，而是把"需要长期驻留的约束"与"仅在特定任务下有价值的知识/程序"分离。

第三组是"可计算事实驱动的 Reference"。OpenAPI、FastAPI 和 Kubernetes 分别展示了 Schema、类型和源码/发行版本如何生成或校验 Reference。它们反驳了"Reference 必须手写"的前提，并证明 Reference 的最佳维护方式常是从事实层投影。但它们也共同留下了人类文档的空间：用户需要概念、决策、迁移、示例、排障和风险边界。

第四组是"治理与时间"。GitHub Docs 将内容纳入 lint/CI/到期管理；Docusaurus 把 current、latest、历史版本的关系显式化；MCP 通过资源/工具的能力、授权与变更通知处理上下文和行动。共同结论是：文档不是静态库存，而是有 owner、版本、权限、更新通知和质量门禁的运行资产。

Anti-patterns：AI 时代更危险的文档失效方式

"少写"并不是解药，"多写"也不是解药。解药是让每段信息有明确职责、来源、范围、时间状态和验证方式；没有这些属性的冗余文字应删除，有这些属性却不易发现的关键事实则应被更好地索引和路由。

AI-Native Documentation Standard：可执行基线

本报告将前述分析收束为十条原则：权威事实可定位、检索单元可独立解释、上下文按需加载、知识/流程/行动分离、行动可验证且受控、时间与版本显式、权威可判定、变更与证据闭环、最小特权与来源治理、以及人类可读优先。完整的规范性措辞、质量门禁和模板见配套标准文件。

对于项目落地，最有价值的不是立刻重写全库文档，而是按风险和频率建立四个最小闭环：

1. 建立入口与权威图。用 README 和 docs index 指出构建/测试、接口、运维、规则和架构的 canonical source；建立 owner 与冲突优先级。
2. 把关键事实接到可计算资产。公共 API、配置、错误码和兼容性尽量由 Schema/类型/测试生成或校验；为高风险 Reference 添加 source_of_truth 与版本。
3. 把 Agent 上下文变成可审计配置。让 AGENTS.md/适配层短、可行动、可显示实际加载内容；将局部规则按路径作用域放置；把深度流程移入 Skill/Runbook。
4. 让变更经过文档质量门禁。至少检查 Markdown/链接、Schema、示例、版本/到期、代码变更影响和 Skill 脚本安全；把 incident、review 和重复性错误回写为测试、规则或流程。

这种路线比"让 AI 为所有页面生成摘要"更能降低长期风险。生成摘要可能提高表面可读性，却不会自动确立事实来源、版本、权限或验证闭环。

Future：事实、趋势与合理推测

已存在的事实

截至研究时点，主流 Coding Agent 已经将项目指令、路径规则、任务能力包和记忆文件纳入工作流；Agent Skills 已有开放格式与跨工具实现；OpenAPI、JSON Schema、类型系统和生成工具已将机器可读契约与人类 Reference 连接；文档 lint、CI、版本化和自动生成在大型项目中已有成熟实践。

正在形成的趋势

一是渐进披露和上下文预算从 prompt 工程细节变为文档架构问题：哪些内容在启动时发现、哪些在任务激活后加载、哪些由子 Agent 隔离执行，正逐渐被工具做成显式能力。二是文档供应链治理正在扩大：Skill 和工具资源可以携带脚本，GitHub 与 MCP 的官方材料都提示了未审查资源、描述和代码执行的风险。三是可观测的有效上下文会成为常规调试对象，因为层级规则越多，维护者越需要知道某个 Agent 实际看到了什么。

合理推测（非既成事实）

未来 2–5 年，更成熟的项目可能把文档质量度量从页面访问量扩展到任务层指标：特定任务的检索召回、事实引用正确率、Agent 首次执行成功率、上下文 token 成本、文档—代码变更遗漏率、Runbook 演练通过率和高风险行动的审批覆盖率。文档系统也可能更像"编译器"：从 Schema、代码、测试、ADR、Issue 和运行 telemetry 构建多种视图，并在不一致时给出可审查的诊断。

但这种演化不必导向"所有知识都结构化"或"所有编辑都自动化"。越是涉及目标、价值、取舍、法律边界、生产风险和组织责任，越需要清楚的人的判断和可追溯批准。AI-native 的价值不在于移除人，而在于把人的判断、事实证据和系统约束放到 Agent 能正确发现、理解、执行和验证的位置。

结论

AI 改变文档工程的底层范式，不是因为 Markdown 变得不够现代，而是因为文档从静态阅读材料进入了自动化系统的运行时。它既是人的学习与协作媒介，也是模型的检索语料、Agent 的上下文、工具的接口说明、测试的行为契约和组织记忆的载体。

因此，真正意义上的好文档应同时满足两件事：对人而言，它能够说明什么、为什么、如何做和何时例外；对 AI 而言，它能够被正确发现、局部解释、按范围加载、与权威事实对齐、转化为受控行动并通过证据校验。实现这一目标不需要神秘的新文体，而需要把既有技术写作的长处，与 Schema、Git、测试、CI、版本、权限、Agent 规则、Skills 和可观测上下文结合为一个完整工程体系。

参考资料