你的文档首个读者可能是AI代理：开发者体验正在被重塑

我最早的开发者文档，是为浏览器和人类读者设计的页面。多年来我一直坚持一个观点：docs-as-code（文档即代码）意味着要用对待代码的态度来对待Markdown文件。直到2024年，一个从未被设计考虑过的“读者”出现了——它是你的客户输入提示词的模型，而且它在你大多数用户之前就已经读完了你的文档。

这种转变堪称真正的“复古”。我多年来一直站在文档消费问题的另一端——先是在不同语言间维护SDK（软件开发工具包），现在在Speechify工作。从面向人类优先到面向模型优先的文档转变，是我在这个领域见过最大的开发者体验变化。以下是我曾经相信的、实际发生的，以及最终留存下来的东西。

2020年左右的docs-as-code：当时正确的方案

当时的理念很简单，而且适合那个时代：你在代码旁边写Markdown，存在同一个仓库里，像其他任何改动一样通过Pull Request（拉取请求）审查。它通过CI（持续集成）构建，像软件一样部署。文档不会“漂移”，因为它们与让它们成立的代码一起发布。

到2020年，这种方法已成为开源社区和快速迭代的API公司的标准做法。Docusaurus、MkDocs和Hugo等工具把Markdown变成了开发者真正能搜索的网站。我自己也这样工作了好几年，因为它确实有效。Markdown、Git、静态站点生成器和搜索索引，足以把答案送到开发者面前。

这个模式现在有了名字。人们称之为docs-as-code 1.0。其核心洞察是：文档和软件有相同的失败模式，所以用相同的解决方案：用版本控制应对漂移，用审查保证准确性，用CI检查死链。这些在当时是对的，现在依然正确。

唯一没人把它当作目标受众的，是语言模型。

当第一个读者不再是人类

变化悄然而至。2024年9月，Jeremy Howard提出了/llms.txt方案，目的是给语言模型一个简洁、结构化的网站版本——因为LLM（大语言模型）的阅读方式与浏览器不同。它们需要一次解析就能获得专家级信息，无法消化带导航和广告的完整HTML页面。最初的提案将其定位为帮助模型在推理时使用网站，就像编码助手在回答前拉取上下文一样。

作为一个社区提案，它的采纳速度相当快。2024年11月，Mintlify原生支持llms.txt，一夜之间成为数千个文档网站的默认配置。随后，Stripe、Anthropic、Cursor和Python instructor库也纷纷跟进。到2026年年中，生态报告显示Anthropic、Cloudflare、Vercel、Supabase和OpenAI等公司都已采纳。这不是正式标准，而是一个已经无处不在的约定——对开发者工具来说，这通常比标准认证更有用。

MCP的出现：AI代理的“文档接口”

如果说llms.txt是给模型读的“摘要页”，那么MCP（Model Context Protocol，模型上下文协议）就是给AI代理用的“API接口”。MCP让AI代理能够以结构化方式访问工具和数据源，而不是靠模型自己“猜”怎么用你的服务。这相当于为AI代理时代重新定义了“文档”的形态——不再是给人看的说明，而是给机器调用的协议。

这种变化对开发者体验的影响是深远的。过去我们优化的是“人类开发者能否快速找到答案”，现在还要回答“AI代理能否正确调用我们的API”。两者对信息组织方式的要求截然不同：人类喜欢示例和渐进式引导，模型需要精确的Schema（数据结构定义）和明确的边界条件。

哪些做法在模型优先时代依然有效

尽管读者变了，有些原则反而更加重要：

• 版本控制依然是底线——模型读到过期文档的后果，比人类读到更严重，因为模型会直接按文档执行
• 准确性成为硬指标——人类读者能容忍“大致正确”，模型不行，一个错误参数名就可能导致整个调用失败
• 结构化是新的搜索——过去我们优化站内搜索，现在要优化模型对文档的“检索效率”，llms.txt和MCP就是为此而生

docs-as-code 1.0的核心理念——文档与代码同源、同审、同发布——在模型优先的世界里不仅没有过时，反而成了基础设施。区别在于，过去我们写给人看，现在还要写给模型“看”。这不是二选一，而是叠加。

开发者体验的下一个战场

当AI代理成为你的文档的第一读者，开发者体验的竞争就从“人类开发者能否快速上手”变成了“AI代理能否零失误集成”。这意味着文档团队需要同时具备两种能力：面向人类的表达能力和面向机器的结构化能力。前者是传统强项，后者是全新挑战。

从2020年的docs-as-code到2024年的llms.txt，再到现在的MCP，这条演进路径清晰指向一个方向：文档不再只是给人看的说明书，而是AI时代的产品接口。那些率先拥抱这种变化的公司——Stripe、Anthropic、Cloudflare——正在把文档从成本中心变成竞争壁垒。

回头看我2020年坚信的那套方法论，核心没有变：文档与代码同源、同审、同发布。变的是读者。当第一个读者从人类变成模型，我们不是在放弃原来的读者，而是在为一个更挑剔的新读者重新设计体验。这可能是开发者体验领域未来几年最值得关注的变化。