北京
你刚刚接手一个遗留的微服务模块，团队里的AI助手在三秒内就拉出了全套接口说明。路径、方法、请求体、返回码，每一项都标注得工工整整，连那个诡异的“宁可返回 418，也不返回 400”的边界条件都原样列出来了。可你盯着屏幕，脑子里只有一个念头：这玩意儿当初究竟为什么非写成一条茶壶？代码和规格书都闭嘴，它们不会开口告诉你半年前那个周五下午，为什么产品经理跪求保留这个反直觉的逻辑。工程师圈子里正在蔓延一种浓烈的情绪：“文档已经死了。”这个论断听起来干净利落、黑白分明。可惜，它错得彻彻底底。
眼下最时髦的那套叙事，是站在代理驱动开发的浪潮上讲的：我们活在一个AI代理能直接啃源码、秒读OpenAPI规范的时代，何必再把人类工程师的宝贵小时，砸进注定过时的散文里？代码的翻书速度太快了，人类手写的文档，从按下提交键的那一秒起就老了。这的确是一幅迷人的图景，把所有工程的灰色地带压平成了二元选择。可严格的决定论真理之源，本来就是一个美丽的泡影。代码和规格书擅长告诉你系统是“怎样”运转的，但它们在解释它“为什么”被建成这副模样这件事上，有着结构性的无能。那个“为什么”，才是真正值钱的工程遗产。
即使你的系统完完全全是为AI代理这个下游消费者建造的，原生的API规格与运行现实之间，仍然横亘着一道巨大的鸿沟。代理们在模式匹配和语法执行上堪称天才，可一碰到架构哲学和人类意图的背景音，它们的耳朵就聋了。我们仍旧需要文字，去给那些看不见的边界画上等高线。一份规格能抽丝剥茧地定义端点、参数、载荷，这没问题；它捕捉不到的，是那种微妙的、在某个特定架构权衡面前为什么选了A而不是B的理由，或者那种沉默的、由遗留边缘案例背负的历史上下文。这些信息不会自己说话。
散文，本质上是在为非确定性系统安装护栏。即便这护栏将来主要是机器在看，不是人类在看，书写下来的文字，依然是传输意图时杠杆最高的一条路径。不要误会，这绝不是鼓吹大家回到手动维护海量静态Wiki页面的手工年代。自动化在这套新体系里分量很重——那种随代码变更动态生成文档的级联式自动化，力量大得吓人。但这里埋着一个致命的陷阱：用垃圾来描述垃圾，到头来一无是处。一旦把文档生成权彻底丢给未经校验的大语言模型，我们得到的只会是一种幻觉上下文描述着飞速位移的代码的回声室。那不是清晰，那是噪声。
关键就一点：人工监修。哪怕文档百分之百是机器人驱动的，人类工程的审视也不可谈判。生成的文本必须经由人的直觉校验，才能确保它交付的，是一份精准的、站在更高处解释全局的说明。不如把生成文档当作API自身的非确定性表亲来看——价值连城，但前提是缰绳得被紧紧攥在手里。然而，眼下这套新范式面前最大的路障，偏偏就是信任。文档领域至今缺少一套可信的“直觉检验”指标，这对于人类开发者和自主代理构成了双重瓶颈。早期开源时代，我们靠的是粗糙但见效的声誉代理：一个仓库挂着上万颗 GitHub 星标，问题追踪器活蹦乱跳，近期还有提交，你就可以大致推断这个项目连同它的文字说明是靠谱的。而我们今天，恰恰还没有找到这种新世界的信任铆钉。
特别声明：以上内容(如有图片或视频亦包括在内)为自媒体平台“网易号”用户上传并发布，本平台仅提供信息存储服务。
Notice: The content above (including the pictures and videos if any) is uploaded and posted by a user of NetEase Hao, which is a social media platform and only provides information storage services.
