AI时代文档并未过时，它仍是核心

代码逻辑与人类意图之间的鸿沟

目前，工程领域里一个日益增长的观点认为文档是过去的遗物。这个论点通常是这样的：我们正处在 agent 驱动开发的时代。如果一个 AI agent 能够瞬间读取原始源代码或解析 OpenAPI 规范，为什么还要浪费工程师的时间去写文档呢？代码变化太快了，人工编写的文档一提交就过时了。

这是个诱人的、非黑即白的观点。但它完全错了。

在你的信息源中追求严格的确定性是痴人说梦。代码和规范可以告诉系统某个东西如何工作，但它们从根本上无法解释为什么一开始要这样构建。

Intent Gap：为什么代码还不够

即使你完全是为了让下游的 AI agent 消费而构建，在原始 API 规范和实际运行环境之间存在着巨大的结构性鸿沟。

Agent 在模式匹配和语法执行方面表现卓越，但在架构哲学和人类意图方面则显得力不从心。我们仍然需要用文字来定义边界。规范可以定义一个端点、它的参数和有效载荷。但它无法捕捉为什么要做出特定的架构权衡，或者遗留边界情况背后隐含的历史背景。

文章为非确定性系统提供了防护栏。即使最后由机器而不是人来阅读，书面文字仍然是传达意图的最高杠杆方式。

垃圾描述垃圾的风险

这并不意味着我们要回到手动维护庞大、静态 wiki 页面的年代。自动化在这里有巨大的作用。级联自动化——即文档与代码变更一起动态生成——威力无穷。

但这里有个陷阱：垃圾描述垃圾毫无用处。

如果我们完全把文档生成任务交给不受约束的 LLM，最终会陷入一个反馈循环：幻觉内容描述飞速变化的代码。这只会制造噪音，而非清晰。

关键在于监督。即使文档完全由 bot 驱动，人工工程审查也是不可谈判的。我们需要对生成的文案进行直觉检查和验证，确保它准确、高层次地阐释了更广泛的上下文。把生成的文档视为 API 的非确定性表亲——价值巨大，但前提是要严格约束。

信任危机与声誉寻求

眼下，这个新范式最大的阻碍是信任。当前缺乏一套"直觉检查"可信度指标，对人类开发者和自主 agent 来说都是巨大的瓶颈。

在过往的开源时代，我们依赖粗糙但有效的声誉代理。如果一个仓库有 10,000 个 GitHub star、有活跃的 issue 追踪、有最近的提交，你就可以合理地认为该项目（及其文档）是稳定的。

对于 AI 时代，我们还没有可靠的声誉系统。当下的绝对新颖性，加上自动化指标极易被游戏的事实，意味着一切都显得有些不确定。

开发者工具的下一次重大转变不仅仅是让 agent 更快或代码生成更干净。它将解决声誉问题——构建能够自动验证、评分和保证我们软件所依赖知识库可信度的系统。

在那之前，别删你的 markdown 文件。机器仍然需要理解言外之意。

某些评论可能只对已登录用户可见。登录查看所有评论。

有进一步的操作，你可以考虑屏蔽此人和/或举报滥用。