10 篇博文 含有标签「documentation」

你的团队在 2024 年拒绝了微服务拆分。当时开了一个两小时的会议，Slack 上的讨论异常激烈，还有一份对比运营成本的电子表格。结论是坚定的：在平台团队交付多区域部署之前，保持单体架构不变。当时在场的每一个人都还记得这件事。

你的编码 Agent 当时并不在场。上周二，它再次提议拆分——语气自信，带着一份干净的迁移计划和一份论据充分的设计文档。再上个周二，另一个 Agent 会话建议提取计费服务。下周，第三个 Agent 会建议用你评估过并两次拒绝的消息中间件来替换你定制的任务队列。就它们所能看到的信息而言，它们都没有错。它们只是看不到决策的价值所在，因为解决这些问题的推理过程存在于已过期的 Slack 线程、未记录的会议以及两名工程师的脑海中，而其中一人已经离职了。

这是 Agent 辅助工程的一种悄然发生的失败模式：已解决的问题正以机器速度被重新审议。而解决办法是大多数团队在十年前归类为“官僚主义、有则更好”的一项实践——架构决策记录（ADR）。

在某处，此时此刻，一个 AI 助手正在向潜在客户解释你的产品。它引用的价格是你 18 个月前修改过的，推荐的集成是你上个季度停止支持的，并建议一个返回 410 Gone 的 API 端点。你永远不会看到这段对话。没有分析事件被触发。没有会话录像。潜在客户要么相信了错误答案并提交了一份困惑的支持工单，要么相信了错误答案，转而悄悄购买了模型随口提到的竞争对手的产品。

这不是一个假设的未来问题。AI 推荐已经占据了可观的流量 —— 对于某些技术和电子商务网站，这一比例高达 5–8% —— 而这些推荐背后的答案，是模型在任何时候吸收的关于你的任何信息生成的。你的营销团队花了十年时间学习如何监控品牌搜索、评论网站和社交媒体提及。几乎没有人正在监控增长最快的表面：当有人询问关于你的信息时，模型是怎么说的。

二十年来，文档一直是良好初衷的坟墓。你在第一个 Sprint 期间编写 README，那时架构整洁，你的热情高涨。但没人读它。到了第三个 Sprint，它就开始在构建命令上误导人，到了第六个 Sprint，它描述的是一个早已被删除的服务。文档是每个人都同意缴纳但实际上没人在缴的税 —— 一种没有反馈循环的道德准则。写了烂文档，什么也不会发生。不写文档，同样什么也不会发生，因为高级工程师把架构都记在脑子里。

然后我们将编程 Agent 指向我们的代码仓库，反馈循环一夜之间降临。README 现在是你拥有的杠杆率最高的文件 —— 这并不是因为有人做了关于文档规范的励志演讲，而是因为该文件的质量现在直观地决定了你的 Agent 是交付正确的代码，还是会信誓旦旦地对一个已不存在的架构产生幻觉。

这就是文档的复兴，而它与我们过去编写的文档几乎毫无关系。

一位产品经理在 Slack 上私聊你，询问当客户要求助手取消订阅时会发生什么。你开始凭记忆输入答案，然后又自我怀疑，于是打开系统提示词读了 30 秒。你粘贴回一份摘要。他们向你道谢后继续忙别的了。三小时后，支持团队问了同样的问题。到了周四，合作伙伴负责人把提示词的截图贴进了交易审查中。

这就是“提示词即文档”（prompt-as-documentation）反模式。当你第一次意识到这种情况发生时，感觉会很棒。你花了六个星期调优的制品，现在成了产品功能的权威真理来源。产品经理在读它，支持团队在读它，销售团队在读它，甚至某个角落的设计师也在读它。你的工作成了支柱，这在以前的服务层代码中从未有过。你可以通过计算有多少不相干的人能凭记忆调出这个文件来证明这一点。

Google Research 有一个令人不安的发现：当 RAG 系统检索到不足或过时的上下文时，幻觉率并不会保持不变——它会从 10.2% 飙升至 66.1%。增加一个陈旧的知识库并不会让你的 AI 帮助中心保持中立。它会让你的 AI 给出自信错误答案的可能性比你什么都不发布还要高出六倍。

大多数构建 AI 驱动的搜索和帮助中心的团队都专注于检索质量、嵌入模型和分块大小。几乎没有人建立流程来追踪语料库中的文档是否仍然准确。这种差距——文档债（documentation debt）——现在正表现为生产环境的可靠性问题，而不仅仅是内容问题。

你的 AI 功能顺利发布了。文档看起来很棒：输入 schema、预期输出，以及一个经过验证的示例。三个月后，模型静默更新。输出发生了偏移。你的文档错了，但还没人发现——因为它们看起来仍然是“正确”的。

这是 AI 文档债（AI documentation debt）的核心，而且它比任何其他类型的技术债积累得都要快，因为在用户发现之前，这种失败是隐形的。

我上个季度合作的一个团队发布了一个 AI 助手，并附带了一整套完备的支撑文档：一个提醒 AI 可能会生成不准确结果的产品内工具提示（Tooltip）、一篇题为“助手如何工作”的帮助中心文章、一份处理升级问题的内部支持操作指南（Runbook），以及一份列出了底层模型、助手可调用的工具及其覆盖的数据领域的公开模型卡（Model Card）。发布过程非常顺利。六个月后，提示词（Prompt）被修改了 14 次，模型在不同层级间进行了切换，拒绝行为（Refusal Behavior）发生了微妙的变化，增加了两个新工具，一个工具被废弃但未从提示词中移除，语言设置也从仅限英语扩展到了 9 个语种。

每一份文档都出错了。并非灾难性的错误——而是那种一句话半真半假、描述的功能与模型实际表现不再匹配、记录的拒绝模式在新模型中从未触发、或者帮助文章里出现的工具名称助手根本不会调用的那种错误。这类错误会产生持续不断的令人困惑的支持工单，当 AI 做了文档说它不会做的事情时会导致客户信任倒退，并且——因为公司在受监管的垂直领域销售——还会产生一个微小但真实的合规漏洞，而 AI 团队中没有人想到要跟踪这一点。

一家中型 SaaS 公司的资深工程师在上个季度花了整整两天时间去排查一个部署 bug，结果发现竟然是智能体的错。该智能体读取了一份最后更新于 2023 年的运行手册（Runbook），忠实地执行了第三步，并运行了一个在当前部署工具中已不再存在的命令。这份运行手册在 Wiki 中依然渲染良好——甚至截图也依然清晰可见——但它已经悄然变得对那些无法察觉环境已过时的读者充满敌意。人类作者完全没意识到，这份文档现在已经成了每个新员工的 AI 助手的关键输入。

这就是过去 18 个月里大多数工程团队中发生的悄然转变：内部 Wiki 累积了第二批受众。同样的 Confluence 页面、同样的架构图、同样的“我们如何部署”的 Gist，现在正由两个截然不同的消费者阅读——工程师本人和工程师使用的 AI 助手。这两类读者在完全不同的约束条件下消费同样的文字，并且当文档在编写时仅考虑了第一类读者时，会产生系统性的不同故障模式。

当你从一位刚刚离职的工程师那里接手一个 AI 系统时，会有一种特殊的恐惧感袭来。系统提示词长达数百行，有一个叫 evals/ 的文件夹里存着 340 个测试用例却没有 README，代码中的注释写着 # 不要修改这里——找 Chen 问 而 Chen 已经联系不上了。

你不知道为什么客服机器人被禁止在星期二讨论定价，不知道哪些评估用例是为了捕捉六个月前的回归问题而写的，哪些只是随机示例，也不知道屏蔽某些产品类别的护栏究竟是法律要求、合规实验，还是某人因为某个副总裁看到了一条糟糕的输出而随手加上的。

系统还在运行。目前如此。但你无法安全地修改任何东西。

你的文档说 /summarize 端点会返回一个简明扼要的摘要。这没错。但它每次返回的摘要都不一样，有时会遗漏关键点，偶尔在你忘记在提示词（prompt）中指定格式时返回结构化的 JSON，并在你毫不知情的模型更新后发生无声的性能退化。而这些都没有出现在文档中。

传统的 API 文档记录的是契约：给定输入 X，预期输出 Y。而 AI 驱动的功能从根本上打破了这一模式。这里没有稳定的契约可供记录。同样的提示词、同样的模型、同样的参数 —— 却会产生不同的输出。然而，团队在发布这些功能时，使用的文档风格仍与编写数据库查询文档时如出一辙：一个函数签名、一个返回类型，或许还有一句关于错误代码的说明。

你的文档所描述的内容与功能的实际表现之间的鸿沟，正是开发者信任消亡的地方。