后文档时代的迷思

📋 概述

Dev.to 联合创始人 Ben 对「后文档时代」论调的系统性反驳。当前有一种流行观点：既然 AI Agent 可以直接阅读源码和 OpenAPI 规范，为什么还要浪费工程师时间写文档？Ben 指出这种思维完全错误——代码和规范能告诉你系统如何运作，但永远无法解释为什么这样设计。他引入「意图鸿沟（Intent Gap）」概念：API 规范可以定义端点、参数和负载，但无法捕捉架构权衡的细微考量、遗留边缘情况的隐性历史背景。更危险的是「垃圾描述垃圾」的陷阱：如果将文档生成完全交给未经审核的 LLM，会形成幻觉上下文描述快速变化代码的反馈循环——制造噪音，而非清晰。核心立场：即使文档完全由 bot 驱动，人类工程审查仍然不可协商——生成的文档应被视为 API 的非确定性表亲：非常有价值，但必须被紧密管控。