Wiki 迎来了第二位租客：为什么面向 AI Agent 的文档与面向人类的文档截然不同

一家中型 SaaS 公司的资深工程师在上个季度花了整整两天时间去排查一个部署 bug，结果发现竟然是智能体的错。该智能体读取了一份最后更新于 2023 年的运行手册（Runbook），忠实地执行了第三步，并运行了一个在当前部署工具中已不再存在的命令。这份运行手册在 Wiki 中依然渲染良好——甚至截图也依然清晰可见——但它已经悄然变得对那些无法察觉环境已过时的读者充满敌意。人类作者完全没意识到，这份文档现在已经成了每个新员工的 AI 助手的关键输入。

这就是过去 18 个月里大多数工程团队中发生的悄然转变：内部 Wiki 累积了第二批受众。同样的 Confluence 页面、同样的架构图、同样的“我们如何部署”的 Gist，现在正由两个截然不同的消费者阅读——工程师本人和工程师使用的 AI 助手。这两类读者在完全不同的约束条件下消费同样的文字，并且当文档在编写时仅考虑了第一类读者时，会产生系统性的不同故障模式。

这个问题并非停留在理论层面。AI 机器人现在驱动了大约 2% 的网络流量，高于 2025 年初的 0.5%，而且对于被每个工程师的编程助手积极抓取的内部语料库，这个比例要高得多。许多团队报告称，在典型的办公日，他们的 Wiki 被智能体阅读的次数超过了人类。然而，几乎没有人问过这个基本问题：对于第二类读者来说，什么样的文档才算是好文档？

两位读者有着相反的容忍度

人类和编程智能体会对同一页面的不同部分产生误判。

人类在阅读运行手册时，能在 5 秒钟内察觉到异样。截图显示的是去年的 UI。在“出故障请联系”一行中的 Slack 账号属于一个已经离职的人。示例命令中的版本锁定落后了三个大版本。这些都没有直接写在文本里——而是在环境信息中。人类读者在还没读到具体步骤之前，就会整合关于时效性和权威性的上百个微小信号。即便文档字面上在撒谎，他们也能察觉。

智能体在阅读同一页面时，则完全没有这些辅助感知。它看不出截图已经过时，因为它不看截图。它不知道哪些 Slack 账号依然活跃。它没有模型去区分 Wiki 中哪些是“每个人都在用的权威文档”，哪些是“某人在 2022 年遗留下的半成品草稿”。它读取步骤并执行，无论该文档是团队的准则，还是一个本该被删除的实验性头脑风暴，它都持有同样的信心。这种不对称性正是痛点所在：人类能容忍智能体会解读错误的歧义，而智能体能容忍人类会跳过的密集信息。

镜像故障同样常见。工程师编写 Wiki 页面时习惯于针对人类的快速浏览进行优化——有力标题、一张图表、几个要点，以及大量隐含的“你懂我意思”的语境。智能体读到后，会根据图表本应覆盖的空白处进行自信的合成，因为智能体不知道图表才是关键部分。又或者，团队编写了一份详尽的参考文档，包含明确的范围声明、版本锁定和行内警告——这对智能体来说很完美，但对人类来说却极其令人疲惫。结果是，团队编写了一份文档，却交付了另一份存在缺陷的内容。

仅在生产环境中出现的故障模式

内部文档已成为第二个产品层面的最清晰证据，就是它们所催生的一类新型 bug。

最常见的是过时文档作为自信来源的故障。一份已被弃用的运行手册，由于两年前部署系统重写后就再没动过，无人认领地躺在 Wiki 的角落里。每个接入语料库的智能体都会检索它，将其视为权威，并自信地教新工程师一个早已行不通的流程。文档静悄悄地老去，因为再也没有人类去读它——人类早就学会了忽略它——但智能体没有这种团队隐性知识 (Tribal Knowledge)。大约 80% 的内部知识库在上线后几个月内就会过时，而且这种过时在页面元数据中是不可见的，直到有人专门去查它。

第二种是跨层级合成故障。智能体检索到了一份权威的架构文档和一份探索性的设计提案，它们在某个关键细节上互相矛盾。对人类来说，区别显而易见——一份位于 /docs/architecture/ 下并带有“已核准”标签，另一份位于 /scratch/proposals/ 下并带有草稿标签。对智能体来说，它们都是同一个 RAG 语料库中的 Markdown 文件。它会对两者取折中方案，产生一个与任何来源都不匹配的混合体，而阅读答案的工程师会得到一个看起来很合理的架构描述，但实际上没有任何团队真正构建过。

第三种是隐蔽语料库污染——无论是对抗性的还是其他的。最近的学术研究表明，在包含数百万文档的知识库中注入仅仅五篇恶意文本，就能对检索达到 90% 的攻击成功率。内部文档的版本更平庸但破坏力不减：一名不理解系统的初级工程师添加了一个页面，由于没人负责“语料库”，该页面从未被审计，现在它永久地塑造了每个开发者的智能体如何回答关于该子系统的问题。你的智能体所学习的供应链贯穿于你的 Wiki，而大多数团队对此没有任何审核机制。

第四种是范围坍缩故障。智能体检索到一份文档，上面用人类特有的充满语境的方式写着：“我们所有的服务都使用 Postgres”。这份文档是由平台团队编写的，关于平台团队的系统，隐含的“我们”指代的是他们的团队。智能体将这句话推广到了整个公司，包括运行在 Snowflake 上的分析平台和运行在 Cassandra 上的实时服务。文档中没有任何内容告知智能体其范围比字面上更窄，而人类作者也从未想过要明确说明，因为没有任何人类读者会犯这种错误。

“为两种受众写作”究竟意味着什么

听到这个说法，直觉反应可能是发布一个单独的 AI 语料库 —— llms.txt、AGENTS.md，或者一套并行的仅供智能体使用的文档 —— 然后就觉得万事大吉了。这充其量只是部分答案。内部 wiki 不会消失，无论你是否准许，智能体都会继续阅读它。而一个与人类阅读版本脱节的并行语料库会引入一种特有的失效模式：两者会在无声无息中产生分歧。更严苛的准则应该是编写能够同时服务于这两类读者的主文档。

一些已经在认真对待这一问题的组织正在形成几种模式。

第一种是为每一份重要文档添加明确的范围和时效性元数据。这不只是风格上的点缀 —— 而是页面顶部的一个结构化区块，标明了文档涵盖的内容、不涵盖的内容、最后一次根据实际情况核实的时间，以及负责人。人类读者会略过这些标题，而智能体则会以此为前提进行处理。对人类读者来说，其成本只是一行视觉噪音；而对于智能体来说，缺乏这些信息的代价就是前文提到的跨层级综合失败。

第二种是两层分类法，将“权威文档”（canonical docs）与“探索性文档”（exploratory ones）区分开来。权威文档是团队在事故回顾中会极力维护的文档 —— 如部署操作手册（runbook）、值班流程（on-call procedure）、记录在案的架构（architecture-of-record）。探索性文档则是其他所有内容 —— 设计提案、头脑风暴、某人从未完成的半成品事后分析。两者对人类都有用，但只有前者应该进入智能体的高信任检索路径。一些团队通过划分不同的语料库来强制执行这一点；另一些则在 frontmatter 中使用 canonical: true 标签，由检索层进行识别。两种方式都可行，不可行的是让智能体将两者等同对待。

第三种是为文档中的关键断言提供机器可解析的权威陈述。如果人类版本说“我们主要使用 Postgres，但实时路径使用 Cassandra，数据仓库使用 Snowflake”，那么智能体可读的版本则应显式地固定这些映射，最好靠近顶部，且最好采用检索层可以索引的格式。当工程师询问“服务 X 使用什么数据库”时，智能体将向其引用这一部分，其格式应使其难以被误读。

第四种是维护节奏，即标记陈旧文档而不是任其腐烂。一些团队现在每周运行一次任务，将文档元数据与活跃的代码路径进行对比，并在最近发布过变更的模块中标记出早于 90 天的文档。该标记不会自动删除，而是向文档负责人呈现一个候选列表。这种准则与成熟团队处理不稳定性测试（flaky tests）的方法一致：陈旧的文档是墓碑（tombstones），而不是基础设施，将其视为后者便会导致失效。

第五种，也是大多数团队重视不足的一点，是明确的废弃标记（tombstoning）。当一份文档被弃用时，它不仅会得到一个人类会略过的 “DEPRECATED” 横幅，还会获得一个结构化标记，让智能体的检索层知道该降低权重或完全排除，并提供指向替代文档的跳转指针。让一份旧的操作手册处于可被检索的状态，其代价是智能体将会一直遵循它。永远如此。直到你删除它，或者切断它的检索信号。

内部文档现在是多租户的产品界面

能给大多数工程团队带来帮助的观念转变是：停止将内部文档视为“我们记录事情的地方”，而是将其视为具有两类消费者 —— 工程师及其智能体 —— 的多租户产品界面，并采用同时兼顾两者的编辑标准。

对于一个 Confluence 站点来说，这听起来可能有点宏大，但事实并非如此。这种转变主要是流程性的：必须有人像管理公共 API 一样管理这些语料库，制定明确的准入标准、弃用路径和审核节奏。门槛不必很高，但必须存在。拥有这种机制的组织能在陈旧操作手册引发的事故影响到生产环境之前就将其拦截。而没有这种机制的组织，则是变相资助他们的 AI 助手去缓慢地、以极高的自信、在没有明显反馈回路的情况下，教给每一位新员工错误的东西。

最终能打动领导层的成本视角是：意识到未经整理的文档会变成一种负债，并随着每一次新的智能体集成而产生复利。每增加一个新工具 —— 代码助手、值班总结工具、挖掘内部 Slack 信息的客户支持智能体 —— 都会放大坏文档的影响面。在 2023 年可能只会浪费一名工程师一个下午的页面，现在每周会通过智能体中介浪费数百分钟，这些浪费分布在如此多细小的错误引导中，以至于没有人能将成本追溯到该页面本身。

在未来一年中胜出的团队，将像成熟团队对待公共 API 一样对待内部 wiki：拥有明确的负责人、准入标准、弃用路径，以及对每一页文档下游受众的明确感知。无论团队是否承认，第二位租户已经出现了。那些承认这一点的团队正在为两种受众编写更好的文档；而那些尚未承认的团队，则在悄无声息地向两者交付更糟糕的体验。