文档正在变成API：一个被忽视的工程债务

你刚更新完文档，两周后发现AI助手还在给同事推荐过时的方案。文档是对的，AI是错的——问题出在哪？

答案很简单：你只写给人看了。

两个读者，两种读法

技术文档的读者结构已经变了。过去是工程师逐页阅读，现在 increasingly 是人机协作：人类做决策，AI负责找材料、组织步骤、辅助执行。

如果文档只有网页形态，AI得先处理HTML，再从导航栏、样式代码和无关信息里提取正文。这一步既损失精度，又拖慢响应。

这不是加不加 llms.txt 的技术细节，而是一个底层转变的征兆——同一套知识，要同时服务两种读者。

文档"技能化"：从可读变为可调用

作者提出"Document Skillification"（文档技能化）这个概念，指的是通过结构化、可调用的能力设计，让文档变得AI可消费。词典里还没有这个词，但随着AI Agent成为主流，你会越来越常听到它。

这件事可以拆成两层理解。

第一层，让文档AI可读。常见入口包括 llms.txt、llms-full.txt，以及页面级的 .md 导出。核心目标是让AI可靠获取结构化内容，而不是去猜HTML里的正文在哪。

第二层，构建技能库（Skill repository）。用 SKILL.md 把流程、约束、最佳实践写成可调用的能力，回答"在什么场景用什么规则"。

两层配合：前者提供内容入口，后者约束使用方式。

实操路径：先入口，后技能

不需要一次性重构所有文档。作者建议分两步走。

第一步，先加AI入口。创建 llms.txt，给关键页面补 .md 导出，按需提供 llms-full.txt。先确保内容可读，再逐步提升读取精度和使用稳定性。

第二步，把高频动作固化为技能。比如SQL文档的书写规范、运维排障流程、升级检查清单。这类内容复用率高，口头传递最容易出偏差。

检索层的设计原则

对于大规模、更新频繁的文档，别一次性把整个文本塞进上下文。采用"先搜索，后阅读"的策略。

可以用MCP（模型上下文协议）或数据库查询层。关键不在于具体技术选型，而在于建立分层机制：先定位相关片段，再深入读取细节。

为什么这事现在就要做

这不是预测，是已经发生的债务。你的文档可能正在被AI读取，只是读得慢、读错、或者读到了过时的版本。

优化单一读者体验的时代过去了。下一步的工程决策是：同一套知识资产，如何同时保证人类易读、AI可调。谁先解决这个，谁就能减少内部支持损耗，让AI助手真正基于最新信息行动。