7 篇博文 含有标签「documentation」

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

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