5 篇博文 含有标签「documentation」

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

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