提示词工程内部文档化：骨架、正文写法、示例库与回归排查

1. 为什么内部文档这件事在提示词上格外容易失败1.1 提示词散落在聊天记录里的真实代价我在几个不同的团队里都见过同一种场景模型调用跑通了效果也不错然后这条提示就被复制粘贴进了某个聊天窗口、某个临时脚本、某个人的本地笔记。三个月后产品要加一个相近的功能新接手的人第一反应不是去翻文档而是重新写一条。写出来的东西跟原来那条有七成相似但在几个关键约束上完全不同于是线上出现了两种不一致的行为排查的时候谁都说我这边测是好的。这件事的根源不在于大家懒而在于提示词这种资产的形态太轻了。它不像一段服务代码有文件路径、有提交记录、有依赖声明它就是一段自然语言随手就能复制随手就能改改完还不留痕。当一个东西的复制成本接近于零的时候它的沉淀成本也会被无限推高——因为没有人觉得有必要沉淀。内部文档这个词听起来很重好像要建一个知识库、搞一套流程、拉一次评审会。实际上一份能用的提示文档核心内容可能只有两屏。真正难的从来不是写而是决定记什么、不记什么。记多了没人看记少了等于没记。我见过最典型的一种失败文档里只有一段提示原文没有适用场景、没有输入假设、没有失败案例。后来的人拿到这段提示完全不知道该在什么条件下用它只能凭感觉试试错了就认为这个文档过期了。所以这篇东西讲的是三件事一份内部文档该怎么搭建骨架一条提示该怎么写成别人能接手的形态以及示例该怎么组织才有复用价值。这三件事是连着的缺一环文档就会退化成一段没人维护的文本。1.2 一段能跑通的提示和一份能被复用的提示文档是两件事这是我最想先说清楚的一个区分。能跑通的提示评价标准是在我手上的这几个输入上输出符合我的预期。它是一个点上的成功依赖大量隐含上下文我知道我的数据长什么样、我知道我要什么格式、我知道哪些边界情况不会出现。这些隐含上下文全在我脑子里不在提示里。能被复用的提示文档评价标准换成了换一个人、换一批输入、隔半年之后还能得到稳定可预期的结果。这时候那些隐含上下文必须被显式写出来否则接手的人就是在盲猜。举个具体的例子。假设有一条用于从工单文本里抽取问题分类的提示原文可能就一句话请判断下面这段工单属于哪一类问题只输出类别名。这句话对写它的人来说毫无歧义因为他知道类别一共只有五类、他知道类别名必须精确匹配枚举值、他知道工单可能是中英混排、他知道空工单要返回未知。但这些信息一个字都没进提示也没进文档。接手的人拿到这条提示跑出来一堆网络问题账号相关其他问题这种自由发挥的答案然后回来问为什么输出不稳定答案不在模型身上在文档缺失上。我把这个区分总结成一条判断标准如果一条提示文档删掉提示原文之后剩下的信息还能让人重新写出八成相近的提示这份文档才算合格。如果剩下的只有一句用于工单分类那它只是一个标签不是文档。1.3 我踩过的第一个坑把提示词当代码存最早我尝试的做法是给每条提示建一个文件按目录分好文件名用功能名提交到代码仓库里。想法很朴素代码怎么管提示就怎么管。跑了两个月问题出来了。第一改动的粒度对不上。代码改动通常有明确的 diff提示改动经常是把请改成必须这种一词之差但效果差异可能很大。这种改动在 diff 里看起来微不足道评审的人扫一眼就过了可它恰恰是最需要被讨论的那类改动。第二没有测试就没有底气。代码有单元测试兜底改完跑一下就知道有没有破。提示改完你得手动找几个输入试试完心里还是没底因为你不确定自己试的那几个输入有没有覆盖到关键路径。第三版本和模型强耦合。同一条提示在某个模型版本上表现良好换一个版本可能就退化了。如果文档只记录提示文本不记录这条提示是在什么模型、什么参数下验证过的那这份记录的价值会随时间快速衰减。后来我的做法调整了提示文件还是放在仓库里但每条提示强制配一个同名的说明块和一个极简的用例集。说明块记录场景、约束、验证环境用例集就是十到二十条输入 期望输出特征的配对不追求覆盖率追求的是改完之后能在五分钟内跑一遍确认没有明显退化。这个调整听起来像是加了负担实际上省了大量时间。因为过去每次改动我都要重新构造测试输入现在直接跑现成的过去我不敢改现在我敢改因为改坏了能立刻发现。2. 文档骨架一条提示到底该记录哪些字段2.1 元信息区让半年后的自己知道它为什么存在元信息是整份文档里最容易被省略、也最容易被低估的部分。它回答的不是这条提示怎么写而是这条提示为什么存在、什么时候该被删掉。我固定记录的字段有这么几个字段记录内容省略之后的后果用途一句话用一句不超过三十字的话说明它解决什么问题后人无法判断新需求能不能复用它上游输入来源输入数据来自哪个环节、由谁产生、大致形态输入一变就全盘失效但没人知道是输入变了下游消费方输出给谁用、是给人看还是给程序解析输出格式被随意改动导致下游解析崩溃验证环境验证时的模型标识、关键参数、验证日期模型换代后效果退化无法定位是提示问题还是模型问题已知失效场景明确记录哪些输入下它表现不好后人重复踩同一个坑还以为是自己写法有问题维护责任人一个人名或角色不需要是真实姓名写清谁负责出问题时没人认领最后变成历史遗留这张表里我最看重的是上游输入来源和下游消费方这两行。原因很实际提示出问题十次里有六七次不是提示本身写错了而是输入形态变了或者下游要求变了。如果文档里把这两端写清楚排查的时候第一时间就能对上去如果没写就只能靠猜。已知失效场景这一行也值得单说。大多数人写文档只写成功经验不写失败边界。但恰恰是失败边界决定了这条提示能不能被放心使用。我习惯的写法是具体到输入特征比如当输入文本超过模型上下文窗口的八成时抽取结果会开始丢字段而不是笼统的长文本效果不佳。前者能让人做出判断后者只是一句免责声明。2.2 约束区输入边界、输出格式、失败兜底约束区是文档里信息密度最高的部分也是新手最容易写空的地方。我把它拆成三块来写。输入边界要回答的是什么样的输入是这条提示的责任范围。这里不要写任意文本那等于没写。要写具体的输入的语言有哪几种、长度大致在什么区间、是否可能为空、是否可能包含结构化标记、是否可能包含需要脱敏的内容。这些条件直接决定了提示里要不要加预处理说明。输出格式要回答的是输出的形状是什么以及形状被破坏时怎么办。如果下游是程序解析那输出必须给出精确的格式定义最好直接给一个完整的输出样例让模型照着抄。如果下游是人阅读也要说清楚长度期望和结构期望否则同一条提示有时输出三行、有时输出三百字人读起来会很难受。失败兜底是最容易被忽略的一块。它要回答的是当输入超出边界、或者模型无法给出可靠答案时应该输出什么。一个统一的兜底输出比如一个固定的占位值或一个明确的无法判断标记比让模型自由发挥要好得多因为下游能识别它、能统计它的比例。兜底比例本身还是一个很好的监控指标——当兜底比例突然从百分之二涨到百分之二十说明上游数据出问题了。注意兜底输出必须是下游能够明确识别的值不要用暂无不清楚这类自然语言。这类词模型自己也会生成导致你无法区分模型的正常回答和触发了兜底。2.3 一份可以直接抄的文档模板把上面这些拼起来我常用的文档骨架长这样。这不是什么规范只是一个跑过很多次、改动成本比较低的形态## 提示名称 用途一句话不超过三十字 责任人角色名 最近验证日期 / 模型标识 / 关键参数 ## 适用场景 - 输入来自上游环节 - 输入形态语言、长度区间、是否可为空、已知特殊格式 - 输出给谁人 / 程序解析 - 明确不适用哪些情况不要用这条提示 ## 提示正文 完整提示文本包含系统部分和用户部分的划分 ## 输出约定 - 格式精确到字段名与类型 - 兜底值一个确定的占位值 - 长度期望上限与下限 ## 已知失效场景 - 具体输入特征 → 具体表现 ## 用例集 输入 / 期望输出特征 / 备注十条起步这份模板里我特意没有放提示设计思路这一栏。早期我加过后来发现没人写写了也没人看。设计思路这种信息更适合放在版本提交说明里而不是放在文档正文里反复维护。模板本身不用追求完备能让人在五分钟内判断这条提示我能不能用就够了。真正决定文档质量的是提示正文本身写得够不够扎实这就要说到下一层了。3. 提示正文的写法从我想要到可执行3.1 角色、任务、约束、输出这四段不是必须的市面上流传的提示模板大多是你是一个资深某某专家请完成某某任务这种开头。我不否认角色设定有时候有用但把它当成必填项是个误解。角色设定的实际作用是收窄输出空间。当你希望输出带有特定领域的术语习惯、特定的严谨程度、特定的表达风格时给一个角色是有帮助的。但如果任务本身很明确比如从这段文本里抽取日期输出 YYYY-MM-DD 格式加一句你是一位资深数据工程师除了浪费 token 没有任何作用。我的做法是按需要取舍通常保留的是这几段任务段一句话说清楚要做什么动词要具体。分析、处理、优化这类词太模糊换成抽取、分类、改写为、判断是否。输入说明段告诉模型输入长什么样、边界在哪里。这一段在文档里往往和适用场景重合但在提示正文里要再明确一次。约束段禁止项和必须项这一段的每条都要能判定真假。输出段格式定义加一个完整样例。角色段我会在需要控制语气或者术语密度的时候加不需要就不加。这不是什么原则问题纯粹看任务。真正需要警惕的是另一种情况模板化开头会诱导人写模板化提示。当你每次都从你是一个……开始写你的注意力会放在怎么把角色描述得更唬人而不是放在任务定义得更精确。我见过不少提示角色描述写了五行任务描述只有半句话效果自然好不了。3.2 把模糊形容词换成可判定的条件这是我认为提升提示质量最有效的一个动作没有之一。模糊形容词的典型代表简洁、专业、友好、详细、自然。这些词在人际沟通里靠默契传达在提示里几乎是噪声因为每个人包括模型对它们的理解都不同。替换的方法是把它变成一个可以被检查的条件。模糊说法可判定的替换输出要简洁输出不超过三句话每句不超过四十字语言要专业使用行业通用术语不使用口语化缩写不使用感叹号要详细说明每个结论后跟至少一条来自原文的依据依据需引用原文片段语气要友好开头不使用命令式动词不使用你必须这类表述格式要清晰使用三级标题组织每节不超过五个要点这个替换的过程本身还有个副作用它会逼你想清楚自己到底要什么。很多时候写完输出要简洁被要求给出具体字数上限时才发现自己其实没想过要多简洁只是笼统地觉得别太长。还有一个更隐蔽的模糊点指代不明。比如根据上文内容进行处理上文指的是系统提示里的内容、还是用户输入里的内容、还是前几轮对话这类歧义在单轮调用里可能不出问题一旦进了多轮或者拼接了多段上下文就会开始出错。写提示的时候养成一个习惯凡是出现上述、该、这部分这类指代词回头确认一下它有没有唯一指向。3.3 结构化输出为什么必须给样例而不是给描述如果输出要给程序解析那格式定义的写法就得非常小心。我的经验是描述加样例样例的分量要比描述重。原因在于用自然语言描述一个结构很容易漏掉边界情况。比如你写输出一个 JSON包含 name 和 score 两个字段这句话没说清楚 score 是数字还是字符串、没说清楚 name 为空时是给空字符串还是给 null、没说清楚外层要不要包数组。模型会自己选一种而且不同批次可能选得不一样。给一个完整样例就能解决大部分问题请按以下格式输出不要添加任何额外文字 {name: 示例名称, score: 85, tags: [标签一, 标签二]} 字段说明 - name字符串若原文未提及则填空字符串 - score整数范围 0 到 100若无法判断则填 -1 - tags字符串数组最多三个若无线索则填空数组注意这里样例用的是具体值而不是占位符。用{name: 名称, score: 分数}这种占位符写法模型有时会把尖括号一起抄进去或者把类型搞错。给一个真实感的具体值模型照抄结构的准确率会高不少。还有一个细节明确说不要添加任何额外文字。这句话看起来多余实际上非常必要。模型有很强的补充解释倾向尤其在它觉得结果不确定的时候会加一句根据文本内容判断……。对程序解析来说这就是灾难。如果模型仍然会加可以在提示末尾再重复一次或者在解析侧做容错但提示侧先说清楚成本最低。3.4 少样本示例的数量与排序给示例是提升效果最直接的手段但示例不是越多越好。我的一般做法是两到四个超过五个之后边际收益下降得很快而 token 成本和维护成本是线性上升的。排序上有个细节值得注意示例的顺序会影响输出的倾向。如果最后一个示例是一个很长的、结构复杂的输出模型倾向于也输出偏长的结果。如果最后一个示例是简短的输出也会偏短。所以当输出长度不稳定时一个有效的调整手段是把最符合期望形态的那个示例放在最后。选择哪几个示例我的判断标准是覆盖差异而不是覆盖数量。具体来说优先选这几类一个最典型的常规输入让模型知道标准答案长什么样一个输入很短、信息量很少的让模型知道信息不足时该怎么处理一个格式上有特殊之处的比如包含嵌套结构或者特殊字符如果存在容易混淆的类别加一个易混淆的对比示例这四类覆盖下来通常三到四个示例就够了。剩下那些边边角角的情况靠约束段的文字说明来兜不必都做成示例。4. 示例库正例、反例和看起来对但错的边界例4.1 只放正例的示例库价值有限团队里建示例库最初的冲动往往是把跑得好的案例存下来。存了三十条正例看起来资料很丰富实际使用时发现帮助不大——因为真实数据里出问题的从来不是那些典型输入而是各种奇形怪状的边界情况。正例告诉模型该怎么做对但没告诉它哪些做法是错的。反例的价值在于划清边界。特别是那种看起来很像对的输出如果不明确指出它错在哪模型会反复生成它。举个具体的。假设任务是从一段描述里判断事件紧急程度分三级。有一种错误输出很典型把提到了紧急这个词但实际不紧急的文本判成最高级。这个错误的特征是依据表面关键词而不是实际语义。如果把这条做成反例写成输入文中出现紧急字样但描述的是已完成的历史事件错误输出最高级错误原因仅依据关键词判断忽略了时态模型对这类输入的判断准确率通常会有明显改善。我把示例库里的条目分成三类各自的作用不同类型作用数量建议正例锚定标准输出形态三到五条覆盖典型输入反例明确禁止的输出模式两到三条针对高频错误边界例定义模糊地带的处理方式按需通常比正例更重要4.2 边界例是怎么攒出来的边界例不可能靠拍脑袋想只能靠攒。我的做法是给每次调用加一个轻量的记录输入、输出、是否被人工修正。修正过的那些就是边界例的候选。这里有个效率上的技巧不要逐条看先看修正率的分组。把输入按某个维度粗分组比如按长度、按来源渠道、按是否包含特定字段看哪一组的修正率明显偏高。偏高那一组里抽几条看看基本就能定位到边界在哪。这比随机抽样翻记录快得多因为随机抽样大部分看到的是正常案例。攒到边界例之后处理方式有两种要分清楚如果是提示能解决的就写进提示的约束段或者做成示例如果是提示解决不了的就写进文档的已知失效场景同时在调用侧加规则拦截区分这两种很重要。我见过不少团队试图用不断加长的提示去解决所有问题结果提示膨胀到几千字效果反而下降因为关键约束被淹没了。有些问题比如输入本身有歧义、比如需要外部知识本质上是提示解决不了的硬塞进去只会让提示变得更难维护。4.3 示例和提示正文的耦合度要控制住示例放在哪里有一个权衡。放进提示正文模型每次都能看到效果最直接。代价是 token 成本固定支出而且改示例就要改提示两者绑死。放在外部检索根据输入动态挑选最相关的几个示例拼进提示。灵活成本可控但需要一套挑选逻辑挑错了反而干扰。我的取舍标准是看场景的稳定性。如果任务范围很窄、输入形态稳定直接写进提示正文最省事不用搞检索那套复杂度。如果任务覆盖多种差异很大的输入类型那动态挑选更合适因为把所有类型的示例都塞进一条提示会互相干扰——模型可能把 A 类型示例的输出格式套用到 B 类型的输入上。不管哪种方式有一条原则要守住示例的格式必须和提示正文里的输出约定完全一致。我遇到过最麻烦的一类 bug就是提示正文说输出三字段示例里是四字段模型随机选一种导致下游解析时好时坏。这种问题排查起来特别费劲因为两次调用看起来输入差不多输出结构却不一样。5. 版本、评审与失效处理5.1 模型换代带来的静默失效提示文档最容易出问题的时间点不是写的时候而是模型更新之后。这种失效是静默的没有报错没有异常日志接口照常返回只是返回的内容质量悄悄下降了。可能是格式开始偶尔跑偏可能是某个类别的判断准确率掉了几个点也可能是输出长度变长了。如果没有基线对比你根本发现不了。应对这个问题的办法不复杂但需要提前埋好在文档的验证环境那一栏记录验证时的模型标识和关键参数同时保留一份基线结果。基线不用很复杂就是那十到二十条用例跑出来的输出存一份。模型更新后重跑一遍逐条对比差异重点看格式是否仍然符合约定、兜底触发比例有没有变化。我习惯的做法是每次重跑后记录三个数字格式合规率、兜底触发率、人工修正率。这三个数字的变化比逐条看输出更能说明问题。格式合规率下降说明输出约定需要重新强调兜底触发率上升往往不是提示问题而是上游数据变了人工修正率上升才是真正的质量退化信号。注意不同模型对同一条提示的敏感度不同。在某个模型上调好的措辞换一个模型可能完全不起作用。所以这条提示效果很好这个结论必须带上模型标识才有意义脱离环境的评价没有参考价值。5.2 一个轻量的评审流程提示的评审不需要搞得很重但完全不评审也不行。我的经验是抓住三个点就够。第一看改动前后用例集的结果差异。这是硬指标改完必须跑跑完把差异贴出来。如果差异是正向的说明改动有效如果有正有负就要讨论这个取舍能不能接受。第二看约束段有没有被削弱。提示改动里最常见的问题是越改越松。原本有必须只输出 JSON的约束改着改着变成了尽量输出 JSON 格式。这种改动往往是为了解决某几个失败案例但代价是把整体约束力降低了。评审时专门盯一下约束段有没有删减能挡住不少这类退化。第三看有没有引入新的隐含假设。比如提示里新加了一句根据上一轮对话的内容继续这就引入了一个假设调用时一定有上一轮对话。如果这个假设不成立提示就会出错。这类假设在写的人脑子里是显然的在别人眼里是隐藏的评审的价值就在这里。评审规模上两三个人看十分钟通常就够了。真正需要拉长讨论的只有一种情况改动会影响下游解析格式。这种改动要拉上下游一起看因为它不是提示层面的变化而是接口层面的变化。5.3 回归用例集的最小可行方案用例集这件事我的观点很明确宁少勿滥能跑起来比覆盖全更重要。我见过太多团队想做一套完整的评测集规划了几百条用例做了两周最后因为维护成本太高而废弃。反而是那种一开始只做十五条、每周往里加两条的小集合能活很久。最小可行的用例集我的定义是这样的八到十二条常规用例覆盖主要输入类型期望输出只写特征不写全文避免模型措辞微调就判定失败三到五条边界用例来自实际修正过的记录一到两条兜底用例输入明显超出范围期望输出是兜底值每条用例标注这条用例是为哪个问题加的方便后续判断能不能删判定方式上不必追求自动比对。格式合规的可以用程序判断语义正确的人工扫一眼就行。十五条用例人工看也就几分钟追求全自动反而会引入误判比如语义正确但措辞不同被判成失败然后你要花时间去调判定逻辑得不偿失。6. 排查手册提示效果突然变差的定位顺序6.1 先分清是输入变了、模型变了还是提示变了效果变差的时候人的第一反应往往是提示写得不好改提示。这个反应在很多时候是错的因为你还没确认变量是哪个。我的排查顺序固定是三步。第一步查输入。拿最近出问题的几条输入和用例集里的输入对比形态。长度分布变了吗出现了以前没见过的字段吗语言变了吗有没有空值这一步能解决掉大部分问题因为上游数据的变化远比提示本身的变化频繁。第二步查模型侧。模型标识有没有变参数有没有被其他人调整过上下文长度是不是触顶了导致截断这几项在对账的时候经常能发现问题尤其是参数被临时调过又忘了改回来这种情况。第三步才是查提示和示例。提示有没有人改过示例有没有被替换改动的提交说明写的是什么这个顺序的意义在于避免无效修改。如果问题出在输入上你把提示改十遍也不会有改善反而可能引入新问题。6.2 分层定位的具体动作确认是提示侧的问题之后我一般按下面的顺序往下走每一步都有明确的判断依据。现象优先怀疑具体动作输出格式偶尔跑偏输出约定不够强或示例格式不一致检查示例与约定是否完全对齐在提示末尾重复一次格式要求某类输入集中出错该类输入未在示例中覆盖从出错记录里选两条做成示例加入同时写进边界说明输出变长、变啰嗦末位示例形态影响或缺少长度约束把简短形态的示例放到最后补一条明确的长度上限兜底触发率上升上游输入变化或输入边界描述过窄对比近期输入与用例输入放宽边界描述结果时好时坏重复调用不一致提示中存在歧义指代或未定义的自由度逐句找指代词和开放式描述逐个收紧关键约束被忽略约束段太长重点被淹没拆出最关键的约束放在提示开头或结尾单独强调这张表里我想特别说结果时好时坏这一行因为它最难排查。重复调用结果不一致通常不是模型随机性的问题虽然随机性会放大它而是提示里存在未定义的自由度。比如提示说如果有必要可以补充说明有必要就是自由度模型每次判断不同输出就不同。又比如根据内容选择合适的分类如果分类之间的边界没有说清模型每次选的可能不一样。排查方法是逐句过凡是出现可以、适当、根据情况、必要时这类词的问自己一句这句话能不能换成一个可以判定的条件能换就换不能换就删掉。提示里的自由度不是坏事但每个自由度都应该是你有意留的而不是无意留下的。6.3 一个容易被忽略的坑上下文位置最后说一个很细节、但影响不小的点。同样一段信息放在提示的开头、中间、结尾模型的利用程度是不同的。经验上开头和结尾的信息权重更高中间部分容易被稀释。所以关键约束尽量放在这两个位置不要埋在中间段落里。这个现象在长提示里尤其明显。当提示超过一定长度之后中间的约束会开始失效而开头的任务定义和结尾的格式要求还算稳定。这也是我不建议把提示写得过长的原因之一提示越长中间那部分越接近于无效而维护成本是实打实的。如果确实有很多约束要写我的处理方式是分组最关键的几条放开头格式和兜底放结尾中间的约束按逻辑归类每类加一个小标题。加了小标题之后模型对分组的识别会好一些中间部分的有效性会有所改善。7. 我个人的几个使用习惯写到这里说说几个我一直在用、但不太容易从别处看到的习惯。习惯一给每条提示留一个反悔区。就是在提示末尾单独留一段写如果无法确定输出兜底值不要猜测。这一句话我几乎每条结构化输出的提示都会加。它牺牲了一点召回率换来的是输出的可解释性——你能明确知道哪些是模型不确定的而不是把猜测当结论用。习惯二文档里的用例宁可写得土一点。很多人写用例喜欢用干净的、格式规整的输入实际数据里根本不会是那个样子。我写用例时会故意保留原始数据里的换行、多余空格、错别字因为模型在这些地方最容易出问题。用例太干净跑起来全绿上线就崩。习惯三改提示之前先写下预期。动手改之前先写一句我预期这次改动会让 X 情况改善让 Y 情况可能变差。改完跑一遍对照这句预期看。这个习惯的价值在于它会让你意识到每次改动都是有代价的而不是改了应该会更好。有时候预期写下来才发现这次改动可能得不偿失那就干脆不改。习惯四定期删。提示文档最容易的失败方式不是写不好而是越来越臃肿。每隔一段时间我会过一遍把那些已经不适用的提示整个删掉把提示里已经不起作用的约束删掉把用例里长期不失败的条目删掉。留下来的东西越少维护起来越轻松也越容易被真正使用。这套东西跑下来最大的感受是内部文档的价值不在于写得多完整而在于它能不能让人少问一句这个为什么这么写。凡是能省掉一次来回确认的记录就是有价值的记录凡是写完自己都不想再打开的内容删掉反而更清爽。