做软件的人对文档有一种集体性的精神分裂：所有人都知道文档重要，所有人都不愿意写，写了也没人看，看了也不敢信。

Cyrille Martraire 在 2019 年出了一本《Living Documentation》试图系统性地解决这个问题。他的核心洞察是：文档的问题不在于”写得不够好”，而在于文档和代码之间存在一个 synchronization gap，而人工维护这个 gap 的成本随系统规模指数增长。所以解法不是”写更好的文档”，而是让文档从代码和系统行为中自动派生出来。

六年过去了，LLM 来了，AI agent 满天飞。那 living documentation 的那些老问题，现在解决了吗？

文档为什么总是烂的

先回到最基本的问题。Martraire 在书里识别了文档的几个根因：

没人写。 成本即时（此刻要花时间写），收益延迟（新人入职时才有用，但写的时候新人还不存在）。这是一个经典的”公地悲剧”。

不可信。 一旦开发者被过时文档坑过一次，就会形成一个简单的启发式：有事问人，别看文档。Luca Rossi 在他的 newsletter 里把这个叫做”同事测试”——找文档、读文档要 20 分钟集中精力，Slack 上问 Tom 只要 3 分钟。Tom 永远赢。

隐性知识不在代码里。 代码告诉你 what 和 how，但不告诉你 why。为什么选了 Kafka 不选 RabbitMQ？当时考虑过哪些替代方案？什么样的组织政治导致了这个架构？这些信息只在当事人的脑子里，代码里一个字都没有。

Martraire 给出的解法是一个核心概念：accuracy mechanism。文档必须有一个自动校准机制，否则注定漂移。BDD 是最好的范例——spec 本身就是测试，测试挂了就意味着文档失同步。没有 accuracy mechanism 的文档，不管是 Confluence wiki 还是 ADR，都活不长。

光谱：谁活了，谁死了

如果按 accuracy mechanism 的强度排列，文档有一个清晰的光谱：

最强：系统即文档。 业务中台的 workflow 可视化、数据中台的血缘可视化、Palantir 的 Ontology、k8s 的 kubectl describe。它们共同的特征是：文档是系统元数据的 view，不是人额外创作的 artifact。改了系统，图自动变。不改系统，文档就不变。accuracy 是 by construction 的。

中间：测试即文档。 BDD scenario、contract test、executable spec。有 accuracy mechanism（测试挂了就知道文档过期），但需要人写测试、维护测试。活着，但需要纪律。

最弱：人写的文档。 ADR、Confluence wiki、README。没有 accuracy mechanism，完全靠纪律。

规律很明显：越靠左，越不需要人的纪律，越容易存活。

你去找 ADR 的落地案例，会发现几乎找不到真正说”我们做了 X 年，效果如何”的一手叙事。AWS 说他们在多个项目里写了 200+ ADR——但 AWS 自己在卖 Prescriptive Guidance，属于”卖铲子的人说挖金矿好”。InfoQ 上有人直接指出 ADR 的现实困境：缺乏对”什么算架构决策”的清晰边界，要么什么都往里塞变成垃圾场，要么没人写因为不确定该不该写。

反过来，业务中台的 workflow 可视化为什么”不需要推广就活着”？因为它根本不需要人的纪律——它是流程引擎执行的副产品，不是额外创作。

Palantir 的 Ontology 也是同一个 pattern。它把组织的数据源映射成 objects、properties、links，定义语义层。一旦你在 Ontology 里定义了”Customer”是什么，就不用再争论这个词什么意思了——这直接就是 Martraire 说的 living glossary，但不是从代码 annotation 去”生成”的，glossary 本身就是 runtime 的一部分。

AI 改变了什么，没改变什么

现在 LLM 来了。对照 Martraire 的困难清单，逐项过一遍。

AI 解决的：生成成本

以前你要从代码生成架构图，需要写 annotation processor、Doclet、自定义 Gradle plugin。现在一个 prompt 就搞定。Living glossary、living diagram 这些 Martraire 花了好几章讲的东西，在 LLM 时代变成了零成本操作。

Legacy 系统的文档生成更是 AI 的甜区。让 LLM 读一个 legacy codebase 然后生成文档，比让人去做高效一个数量级。DeepWiki 把 GitHub URL 里的 “hub” 换成 “deepwiki” 就能自动生成文档，已经索引了超过 50,000 个公开 repo。

但 DeepWiki 做了一个聪明的 trade-off：它只做”what”和”how”，不做”why”。它的受众是外部理解者——要快速理解一个不熟悉的 repo，80% 正确就很有用。如果你是这个项目的核心维护者，DeepWiki 生成的文档对你几乎没有价值。

DeepWiki 的本质其实不是 living doc，而是 disposable doc——用完即弃，随时重来。不追求”活着”，追求的是 f(codebase) 每次调用每次生成。如果生成成本趋零，为什么还要费力让文档”活着”？每次需要的时候重跑一遍就行。你不会去”维护”一个 ls 命令的输出。

AI 没解决的：准确性

这是更深的问题。LLM 生成的文档没有内建的 accuracy mechanism。不像 Cucumber 测试失败会在 CI 里红掉，LLM 文档漂移是个静默错误——而且 LLM 的自信表述会掩盖不准确。

Martraire 自己在 2025 年底的实战验证了这一点。他在 API Days Paris 上分享了用 AI 给 SNCF（法国国铁）做 API 迁移验证的案例。最初设想全用 LLM 直接验证 API，但很快发现把巨大的 API schema 塞进 context 后质量退化严重。最终方案不是让 LLM 做裁判，而是让 LLM 生成确定性的测试代码，然后跑这些代码来验证。

他的 insight：AI 是工具，不是范式。Living doc 的核心原则——尤其是 accuracy mechanism——不会因为 AI 而消失。他的行为比他没发表的文章更有说服力。

AI 完全无能为力的：知识不存在

决策的 context、被否决的方案、当时的组织政治——这些信息不在代码里。LLM 可以从代码推断 what 和 how，但推断不出 why。你让 AI 重新生成一万次也生成不出来。这部分知识如果没人记录，就真的丢失了。

真正的变量：文档的读者变了

上面这些分析到此为止都还在 Martraire 的框架内打转。真正让我觉得有意思的，是我们之前没预见到的一个变量：文档的读者正在从人变成 AI。

GitBook 的数据显示，2025 年初 AI 系统只占文档流量的不到 10%，到年底已经超过 40%。全年 AI 读者的页面浏览量增长了 500%+。

这催生了 llms.txt 运动。llms.txt 是 robots.txt 的镜像——robots.txt 告诉爬虫不要读什么，llms.txt 告诉 AI 应该读什么、从哪开始、如何排优先级。ChatGPT 和 Claude 已经在爬取这个文件。GitBook、Mintlify、Fern 这些文档平台全都支持了原生 llms.txt，并且开始为每个文档站点自动生成 MCP server——让 AI agent 可以程序化地查询文档，而不是把整个文档塞进 context window。

这意味着什么？文档从”人读的文章”进化成了”AI 消费的结构化知识层”。优化方向从”人读起来舒服”变成”AI 能准确检索和理解”。

有人总结了一句话：文档正在从静态页面变成结构化的内容模型（API 定义、示例、流程），同时服务人和 AI 两种消费者。新的挑战不再是”怎么写更好的文档”，而是”怎么让文档足够 machine-readable、context-rich、语义一致，以驱动 AI”。

这和 Palantir Ontology 其实是同构的。Ontology 就是给 AIP agent 消费的”文档”，只不过更结构化。AIP 用的 Ontology-Aware Generation 模式——不像传统 RAG 去检索文本，而是直接接收结构化的 objects 和关系——就是这个方向的极致形态。

llms.txt + MCP 是一个轻量版的、适用于所有项目的同类方案。

图和表达形式的边界

顺着”文档给 AI 读”这个思路，一个自然的问题是：那可视化呢？AI 时代能做得更好吗？

AI 让”生成第一版图”变得几乎免费。Swark、GitDiagram 这类工具把代码文件塞进 prompt，生成 Mermaid 图，天然支持所有语言。对于”快速理解一个项目的大致结构”这个需求，已经足够好了。

但”让图持续准确”这个问题的本质没变——要么图是系统的副产品（workflow 可视化），要么绑定测试（BDD），要么靠纪律（Confluence 贴图）。AI 把最弱端的生成成本降低了，但没有把弱端变成强端。

而且，图有它自身的表达边界。比如一个平台的按钮展示逻辑——用户角色 × 订单状态 × 审批流进度 × feature flag × A/B 实验分组 × 时间窗口——画成流程图可能是一棵巨大的决策树，分支多到人眼追踪不了，还不如直接看一段 if-else 或一张 decision table。

UML 当年试过用 activity diagram 和 state machine diagram 来覆盖这些，结果大家都知道。

不同类型的知识需要不同的载体： 结构和关系用图（ontology、C4），流程和流转用 workflow 图（BPMN），行为和场景用 executable spec（BDD scenario），条件逻辑用 decision table，不变量用 property assertion。强行把所有知识塞进同一种形式——不管是图、文档还是代码——都会在某些维度上失败。

Tailwind 问题

这里有一个意想不到的副作用。Tailwind CSS 因为 AI 训练了其文档内容，用户不再需要访问文档网站了，导致流量和收入下降，不得不裁员。

当文档的主要消费者变成 AI，文档创作者怎么获得回报？这不是一个理论问题，Tailwind 已经撞上了。

可能的方向：保持文档的 freshness 优势——训练数据有延迟，官方文档总是最新的；或者把文档变成 API/MCP service，按调用收费；或者提供 AI 无法替代的交互体验（playground、实时预览）。

这个问题的存在反过来也说明：文档确实正在成为 AI 的 context source，而不是人类的阅读材料。趋势是实打实的。

“Why”层：最后的空白

回到最开始的问题。ADR 试图解决”为什么这样设计”的记录问题，但因为处在 accuracy 光谱的最弱端（纯靠纪律），落地困难。AI 能帮忙吗？

直接让 AI 写 ADR？代码里根本没有 decision context，AI 写不出来。

但有一个更有意思的方向：当 AI agent 自己参与架构决策时，它的 reasoning trace 天然就是 ADR 的原材料。

想一下这个场景：你用 Claude Code 或 Cursor 做架构决策，agent 分析了几个方案的优劣，最终推荐方案 B。这个分析过程——考虑了哪些选项、每个选项的 trade-off、为什么排除了方案 A——本身就是一份质量相当好的 ADR，而且是工作流的自然产出，不是额外写作任务。

这和 workflow 可视化是同一个 pattern：不需要人额外写文档，文档是系统行为的副产品。只不过这里的”系统”是 AI agent 的推理过程。

当然，目前还没有工具把 agent 的 reasoning trace 自动结构化成 ADR 格式——这确实是一个值得做的方向。

五条原则

最后总结一下 AI 时代文档的原则。

一、文档是给 AI 读的，人通过 AI 间接消费。 llms.txt、MCP server、结构化 Markdown——优化目标已经变了。

二、能从系统派生的，就不要人写。 Workflow 可视化、数据血缘、Ontology 是最可靠的 living doc。AI 在这一层帮不了太多，核心是 instrumentation 覆盖率。

三、生成成本趋零，accuracy mechanism 才是稀缺品。 AI 让”写文档”变便宜了，但”写对文档”没变便宜。Martraire 的核心原则没有过时：任何不绑定自动验证的文档都不可信。

四、不同类型的知识需要不同的载体。 不要试图用一种形式覆盖所有知识。结构用 ontology/spec，行为用 executable spec，条件逻辑用 decision table。

五、”Why”层是最后的人类领地——但可能通过 agent trace 被自动化。 让 agent 的决策过程成为 structured log，是目前唯一看到的让”why”类知识不依赖纪律的路径。

文档没死。但它正在从”人写给人看的文章”变成”系统生成、AI 消费、人通过 AI 间接获取的结构化知识层”。Martraire 六年前的框架没有过时——accuracy mechanism 的重要性甚至更高了——但文档的形态和受众都在发生根本性的变化。

参考资料

• Cyrille Martraire, Living Documentation: Continuous Knowledge Sharing by Design, Addison-Wesley, 2019
• GitBook, “AI docs readership increased over 500% in 2025”
• Dachary Carey, “Llms vs. agents as docs consumers”
• Luca Rossi, “How AI is Changing Engineering Docs”, Refactoring Newsletter
• Cyrille Martraire & Thomas Nansot, “AI and APIs: Ensuring Platform Migration Reliability with AI”, API Days Paris 2025
• Palantir, Ontology Overview & AIP Documentation
• llms.txt proposal by Jeremy Howard, Answer.AI