能熬过模型更新的提示词模式，都是那些携带了模型自身无法推断的信息的模式：设定受众的角色、模型没有的背景、带有决策规则的任务，以及在提示词之外强制执行的输出契约。其他的一切不过是有保质期的口耳相传。
在 JSON 上最能看清这条分界线。礼貌地要求模型返回 JSON，大约有 5-10% 的输出会格式错误；开启 JSON 模式后有效率提升至约 95-99%；而经过 Schema 约束的解码几乎能达到 100%（Ashvara）。相同的意图，三层执行机制，发布当天的失败率却天差地别。
本手册涵盖四种在 Claude、GPT 和 Gemini 上都持续有效的模式、值得从库中删除的脆弱技巧，以及一套能将下次模型发布变成对比差异而非事故响应的小型评估套件。
为什么提示词会失效：没有人做版本控制的故障模式
提示词的衰退不是随机的。它沿着一条可预测的接缝衰退：依赖特定模型行为方式的部分，会被下一个检查点废弃；而表达你需要什么的部分，则得以存活。
两类提示词：描述意图的 vs 利用模型怪癖的
意图型提示词说明输出必须是什么、谁来阅读、什么算作错误。怪癖型提示词说的是上周二碰巧管用的那些东西。全大写的 ONLY RETURN JSON。同一条指令重复三遍，因为两遍不够用。从论坛帖子复制来的神奇开场白。这些技巧都是针对某一个检查点的解码行为调整出来的，其中没有任何内容能告诉未来的模型你究竟需要什么。
朴素的「请返回 JSON」提示词仍然会产生约 5-10% 的格式错误输出（Ashvara），而这个数字是模型的属性，与你的提示词无关。换个模型，这个数字就会变动。你从未写下契约，所以对新模型也就没有任何约束力。
发布当天真正会崩溃的是什么
崩溃通常并不明显。你的解析器开始因为末尾多余的逗号而抛出异常（一项分析显示约 40% 的 JSON 错误正是由此引起，Flying Fish Space），或者模型变得更健谈，在干净的输出外面包了一句前言。与此同时，新模型发布的速度意味着你调优时用的那个检查点，下个季度未必还在提供服务。
相比之下，经过 Schema 约束的调用限定了生成范围，语法有效率本质上达到 100%（Ashvara）。执行机制存在于提示词文本之外。一次模型更新可以改变语气、详略程度和推理深度，却动不了它。
持久性测试：这条提示词对更聪明的模型还有意义吗？
对你拥有的每条提示词问同一个问题：如果模型一夜之间能力翻倍，这条指令还在做有用的工作吗？
"返回一个包含 id、status 和 confidence 键的对象，其中 status 是三个字面值之一"——这条通过测试。RFC 8259 已经固定了你所借用的词汇表：四种原始类型、两种结构化类型，以及恰好三个小写字面名称（RFC 8259）。这条指令对任何模型、无论现在还是将来都是清晰可读的。"深呼吸，一步一步来思考"——这条不通过，因为它是在弥补下个版本可能已经修复的弱点。删掉补偿，保留契约。
可迁移的提示词工程模式：角色、背景、任务、格式
把每一条临时提示词重构为四个槽位，每个槽位只放模型无法自行推断的信息。角色、背景、任务、格式。这个框架能经受住模型更新，因为每个槽位承载的是你的问题的事实，而不是关于上个季度检查点如何响应奉承的传言。
四个槽位各自放什么
角色是输出面向谁、答案假设了什么层级的专业知识。「你是世界级专家「只是定了一种氛围，不携带任何信息。「你在为一位已经知道幂等键是什么的支付工程师写作「，这才告诉了模型哪些解释可以略过。
背景是模型无从得知的一切：Schema、上游系统、你在生产环境中已经踩过的边界情况、你的解析器拒绝 UTF-8 BOM 这一事实。任务是单一的动词加宾语。格式是输出契约，且应具体到可以机械验证。
格式槽位写「返回 JSON「是一种愿望。格式槽位写明键名、各键的类型、某个值未知时应如何处理，才是一份可供测试的契约。JSON 提供了四种原始类型（string、number、boolean、null）和两种结构化类型——对象和数组（RFC 8259），所以这里有一套有限的词汇可以精确表达。写 null 而不是「留空「，因为字面名称 true、false 和 null 必须是小写，其他写法都不合法（RFC 8259）。
为什么这个框架能跨 Claude、GPT 和 Gemini 迁移
四个槽位中没有任何内容依赖于分词器、系统提示词的怪癖或服务商的功能开关。每个模型都需要被告知你想要哪些字段、你的下游代码用它们做什么，所以同一个框架可以不经改写直接用于 Claude、GPT 和 Gemini。这种可移植性也正是它可升级的原因：当新检查点发布时，背景槽位仍然为真，格式槽位仍然是你的验证器所执行的契约。你换掉模型，重跑评估，差异为空。
我们目录中以模板形式封装了这套结构的 212 个提示词工程工具，本质上都是在把这些槽位卖给你。你用一个 heredoc 加四条注释就能得到同样的效果。
把约束写成事实，而不是咒语
判断一行文字是否属于你提示词的标准：一个称职的承包商能否无需追问就按此行事？「要详尽「不通过。「属性名使用双引号，最后一个元素后不加尾随逗号「通过，而且它对应着真实的失败模式——仅尾随逗号一项就占一项分析中 JSON 错误的约 40%（Flying Fish Space）。
咒语从不大声失败地消耗着 token，而明确陈述的事实则在你指向它的每一个检查点上保持其含义。
改写前后对比示例
| 改写前（临时写法） | 改写后（四槽位写法） |
|---|---|
| "你是一位专业数据分析师。请仔细提取发票详情并返回 JSON。要准确！" | 角色： 输出由 Python 的 json.loads 调用消费，无人阅读。背景： 发票来自 OCR 扫描的 PDF；供应商名称常被截断；金额可能带有货币符号。任务： 提取 vendor、invoice_number、total_cents、issued_date。格式： 一个 JSON 对象，键名严格按上述列出，total_cents 为无前导零的整数，未知值用 null，输出前后不带任何说明文字。 |
改写后的版本对模型的个性只字未提，却将你的数据说清楚了。注意 null 和 {} 都是合法的 JSON，但含义不同（Jsonic），所以选定一种并写进契约。JSON 数字中也不允许前导零（MDN），这正是格式槽位明确写出整数规则而不是信任模型记住语法的原因。
为迁移而设计的少样本示例脚手架
选择示例要以它们能解决的歧义为准。一组展示了四个人类会犹豫不决的场景的少样本示例块，能教会下一个模型它仍然需要的东西。展示四个简单场景的示例块只是在教风格，而风格恰恰是每个检查点越来越擅长自己猜测的东西。
教决策边界，而不是词汇
粘贴一个示例之前，先问：如果删掉它，会有什么变化？如果答案是「输出听起来稍微不那么像我们的风格「，就删掉它。如果答案是「模型会把含部分发货的退款归类为退货而非争议「，就保留它，因为这个判断无法从任务描述中推导出来。
同样的测试也适用于输出形状。一个将空结果表示为 [] 而非 null 的示例，比五个有内容的结果示例更有价值——因为空数组和 null 都是合法的 JSON，但含义不同（Jsonic）。模型对此有不同的猜测，而一个示例就能一劳永逸地确定下来。
边界情况和负例值得花费 token
你的两到三个样本应该是你在生产环境中出过错的案例。缺失字段的情况。输入已经是目标格式的情况。正确答案是「数据不足「、但乐于助人的模型会编造一个值的那条记录。
负例有效的前提是将其与纠正结果并排展示，而不是仅仅声明一条禁令。将格式错误的输出和修复后的输出并排陈列，边界就变得具体了。单独写「不要使用单引号「这类指令会随时间失效，而单引号正是 JSON 格式错误的惯犯之一，和尾随逗号一起，后者在一项分析中占错误总量的约 40%（Flying Fish Space）。
用几个样本合适，以及何时减少到零
从零开始。只有当某个评估用例失败时才添加样本，且只添加能修复该用例的最小示例。大多数分类和抽取提示词在三到六个样本之间趋于稳定；超过八个，通常是在弥补你从未好好写过的任务描述。
只要 Schema 能胜任工作，就减到零个样本。对提供的 Schema 进行约束解码，能让语法有效性达到本质上的 100%（Ashvara），所以格式示例在那里是多余的负担。把样本留给判断，把 Schema 用于结构。
过拟合的信号：下一个模型会照抄的示例
留意那些表面特征是偶然的样本。如果每个示例输入都在 40 字左右，更强的模型可能会把长度当作信号。如果所有四个示例都落在同一个标签上，你就偏置了先验概率。如果你的示例用了 Acme Corp 这类占位名称，迟早会在真实输出中看到它们出现。
新检查点发布后的当周，把你的少样本集对新版本重跑一次，对那些示例未覆盖到的用例做输出对比。那里才是模仿泄漏的地方。发布真实部署案例的团队往往正是因为这个原因将示例集纳入版本控制：无法做 diff 的示例，也就是无法退役的示例。
经得住模型更新的输出契约
把执行机制推到栈的更深处，直到格式不再依赖某个检查点某天碰巧的心情。礼貌地请求 JSON 是最弱的一级，也恰恰是大多数生产代码还在运行的那一级。
可靠性的三个层级：散文请求、JSON 模式、约束解码
| 层级 | 你如何请求 | 返回什么 |
|---|---|---|
| 1 | 在提示词文本中写「请返回 JSON「 | 估计 5-10% 的输出格式错误（Ashvara） |
| 2 | 开启服务商 JSON 模式 | 生产观察中约 95-99% 语法有效（Ashvara） |
| 3 | 将生成约束到提供的 Schema | 本质上 100% 语法有效（Ashvara） |
只要你的服务商支持，就使用第 3 层级。有效性来自解码器而非模型权重，因此换模型也无法使其退步。同时保留提示词层面的契约，因为约束解码只保证形状，对值是否正确只字不提。如果不想自己写配套代码，我们目录中封装了 Schema 执行功能的框架工具共有 128 个条目。
一份契约在「返回 JSON「之外必须说明什么
写明键名、每个键背后的类型，以及模型没有内容可填时的处理方式。
- 每个键名严格按你的解析器期望的方式拼写，类型取自 JSON 六种类型之一：四种原始类型（string、number、boolean、null）和两种结构化类型——对象和数组（RFC 8259）。
- 仅使用小写字面量。语法只允许三个：false、null、true（RFC 8259）。
- 每个对象内的键名唯一，RFC 8259 建议如此，以确保每个解析器对同一名称-值映射达成一致。
- 可选键是省略还是以 null 值输出，以及你期望的任何枚举值，以字面字符串形式写出。
值得在契约中明确的失败模式：尾随逗号、单引号、未转义字符串
一项分析显示，尾随逗号约占所有 JSON 错误的 40%，其余大部分由单引号、字符串内未转义的引号、缺失逗号和隐藏 UTF-8 BOM 字符构成（Flying Fish Space）。在格式槽位中明确禁止这五种失败模式，大约只需 25 个 token，而这条禁令对你今后指向的每个模型都同样有效。同时在你这边加一个先验证再格式化的步骤，而不是信任原始字符串（QuickTinyData）。
空对象、空数组、null：三种不同的答案
这是契约在不同模型版本之间悄无声息泄漏的地方。空对象和空数组都是合法的 JSON，与 null 的含义也各不相同（Jsonic）。一个检查点对无匹配结果返回 []，下一个返回 null，而你的下游代码把其中一种视为错误。
选定一种表示方式，在契约中说明，并验证它。你的解析器还需要能够处理顶层的裸值，因为任何单个 JSON 值都构成一份完整的文档，包括独立的字符串或数字 42（Jsonic）。
随每次发布而失效的脆弱技巧
打开你的提示词库，搜索这四种模式。每一个匹配都是删除的候选，因为它们都在弥补某种已经被修复或已经移位的模型弱点。
作为附加项的通用「一步一步思考「
在提示词末尾附加「一步一步思考「，在模型倾向于直接给出答案的时候是有意义的。当前的推理模型默认就会分解步骤，所以这个短语只是在增加 token，有时还会把一个简短的分类任务拖成三段你还需要剥离的叙述文字。
推理指令只在任务特定时保留：「在选择其中一条之前，先列出相互冲突的条款「——这才告诉了模型要推理什么。持久的替代方案是角色-背景-任务-格式框架中的任务槽位，明确写出你想要的中间产物。通用咒语，扔进垃圾桶。
威胁、贿赂和角色扮演施压
"你搞错了就会被解雇。""我会给你小费 $200。""你是世界上最伟大的分析师。"这些技巧依赖于特定 RLHF 检查点的怪癖，而怪癖无法在重新训练后存活。更糟的是，它们无法证伪：你写不出一个测试来证明是小费修复了你的输出，所以这行文字永远留在提示词里，无人质疑。
用约束替代施压。让模型自我评分的评分标准，或者明确列出什么算作失败，能达到同样的效果，并在检查点更换时继续有效。
与分词器对抗的格式技巧
用全大写要求、三重感叹号或大段分隔符如 ##### 来填充提示词，只是传言。分隔符那部分倒有一定道理（清晰的段落边界有帮助），但升级叠加并没有用。两个换行加一个类 XML 标签，胜过四十个井号。
同理，「不要代码围栏，不要前言，不要解释，只输出 JSON「叠加三遍也没用。在格式槽位说一遍，然后把保证放在保证真正有效的地方：将生成约束到提供的 Schema，才能让语法有效率达到本质上的 100%（Ashvara），任何数量的提示词层面禁令都无法接近这个数字。
用提示词恳求代替解析器
失败模式枯燥而结构性：最后一项后的尾随逗号、未加引号的键、无效引号字符、缺失逗号、花括号不匹配（QuickTinyData）。仅尾随逗号一项就占一个错误数据集中 JSON 错误的约 40%（Flying Fish Space），而它们被格式规范本身所禁止（MDN）。再多的恳请也无法弥合这个差距。
删掉恳请。在那里放一个 Schema 和一个验证器，让提示词去说明字段的含义。
评估循环：把提示词当作有版本的产物
在构建任何复杂内容之前，先构建二十个测试用例。一条没有评估集的提示词是无法升级的提示词，因为你没有办法判断新模型是让它变好了，还是在不告知你的情况下破坏了那个对你最重要客户最关键的用例。
二十不是妥协的数字。它足以覆盖你已知的失败类别，小到你可以在一个下午写完，便宜到可以在每次检查点更新时重跑，而不必考虑费用。
最小可行评估：20 个用例，每个一条断言
每个用例一条断言，且让它是布尔值：输出是否能解析，是否包含必填字段，在应该拒绝时是否拒绝了。等布尔值通过之后，评分标准、裁判模型和相似度评分再来。带三条断言的用例会变成你无法调试的用例——运行失败时，你根本不知道是哪条断掉了。
从真实流量中挑选你的二十个，偏向棘手的那端。五个正常路径，五个模糊输入，五个对抗性或空输入，五个曾经在生产中出过问题的。把它们和提示词放在同一个仓库里、同一次提交里。如果提示词改了但用例没改，那就是一条 code review 意见。
先验证，再格式化：借鉴 JSON 调试工作流
JSON 领域多年前已经解决了这个争论。QuickTinyData 的排错指南建议先验证再格式化，因为对一个已损坏的文档做美化输出会掩盖你正在追查的确切结构错误：尾随逗号、未加引号的键、错误的引号字符、缺失逗号、花括号不匹配（QuickTinyData）。
以同样的方式运行评估。在断言质量之前先断言有效性。无法通过 json.loads 的模型输出不应该进入语义检查，也不应该得到部分分数。你的评估套件需要两列：解析率和通过率，第二列只统计第一列成功的行。
了解错误分布能告诉你该断言什么。一项分析显示尾随逗号约占 JSON 错误的 40%，其余大部分由单引号、字符串内未转义的引号、缺失逗号和隐藏 UTF-8 BOM 字符构成（Flying Fish Space）。那个 BOM 值得专门写一条断言，因为它在你用来检查输出的每个编辑器中都是不可见的。
在发布当天运行回归测试
新检查点发布。你跑那二十个用例，得到差异，做出决定。这就是全部流程，如果你的套件构建得当，大约需要四分钟。
- 固定旧模型，重跑套件，确认你的基线仍然可复现。如果不能，问题在测试配置，而不是这次发布。
- 对新检查点运行套件，分别记录解析率和通过率。
- 逐条阅读每个翻转的用例，双向都要看。开始通过的用例可能是运气，值得与回归同等关注。
- 上线、回滚或修复提示词。然后将新的基线数据与提示词文件一起提交到仓库。
这在一次错误解析会级联传播的智能体栈中最为关键，因为失败会在三次工具调用之后以一个看起来完全不像格式错误的问题浮现出来。
固定版本，以及无法固定时该怎么做
在任何可能的地方固定到有日期的模型 ID，把别名当作你选择不锁定的浮动依赖来对待。有些服务商不提供固定版本，或者会在短暂通知后废弃你正在用的版本。遇到这种情况，你的评估套件就是站在静默行为变化与无法复现的支持工单之间的唯一屏障。
定期对未固定的端点运行套件。每周一次就够了。你会在用户通过 bug 报告向你复述之前，先发现漂移。
将一条提示词移植到 Claude、GPT 和 Gemini
构建良好的提示词大约有 80% 可以不经改动移植。其余的是一层适配器，每个服务商写一次，之后基本不用管。如果你在为每个供应商全部重写，说明你的提示词携带了它本不需要携带的服务商特定行为。
保持不变的部分：框架、示例、契约
四槽位框架无需任何修改即可跨供应商使用。角色、背景、任务、格式描述的是工作本身，而工作不会因为换了检查点而改变。你的少样本示例块同理：能解决领域内真实歧义的示例，对每个模型教的是同一件事，因为歧义存在于你的数据中，而不在解码器里。
你的输出契约同样保持不变，而且必须如此。无论服务商返回什么，都必须满足同一个解析器的要求：属性名使用双引号，无尾随逗号，不含 NaN 或 Infinity，只有四种合法的空白字符（空格、制表符、换行符、回车符）（MDN）。Schema 写一次，用同一个验证器验证三家的输出，对失败做 diff。
同时保持评估集的供应商中立。在 Claude 上通过但在 Gemini 上失败的二十个用例，能告诉你有用的信息。专门针对 Claude 怪癖写的二十个用例，什么都说明不了。
每个服务商需要重新调整的部分：系统消息权重、分隔符、执行 API
三件事需要适配器。你的指令有多少放在系统消息里、多少放在用户轮次里，因为不同服务商对两者的权重处理不同。你用什么来围住代码块，类 XML 标签还是 Markdown 标题。以及你调用的是哪个执行 API。
最后一点是最繁琐的部分。任何风格的 JSON 模式都只保证语法，仅此而已：生产观察中有效率约为 95-99%，而将生成约束到提供的 Schema 则本质上是 100%（Ashvara）。两个层级都没有说明你请求的键是否存在，所以无论用哪家服务商，Schema 校验都要保留在你的代码里。如果你在选择目标，值得先去对比模型本身再做决定，我们目录中的多服务商平台会帮你承担一部分适配器工作。
发布前的可移植性检查清单
- 删除每一句提到模型名称、版本或某模型已知行为的语句。这些是最先断掉的行。
- 对三家服务商运行同一套评估集，逐用例记录通过率，而不只是平均值。
- 确认无论服务商是否声称支持约束解码，Schema 验证器都对每条响应运行。
- 接线适配器时重新阅读每家服务商的执行文档，将它要求的措辞或开关保留在适配器内，而不是放在共享提示词里。
- 记录哪个适配器被触发。当新检查点发布、质量发生变化时，你需要知道是提示词还是适配器在你不知情的情况下变了。
如果一条提示词只在某一家服务商上未通过此检查清单，问题几乎总是出在适配器上，而不是框架本身。
常见问题
每次新模型发布，我都需要重写提示词吗？
不需要，如果你确实在重写，你的提示词可能携带了针对特定模型的技巧而非通用指令。能经受住更新的部分，是那些与模型之外的东西挂钩的部分：任务描述、输入数据，以及像 JSON Schema 这样的输出契约。对提供的 Schema 进行约束解码，无论背后是哪个模型，都能产生本质上 100% 语法有效的 JSON，因为约束存在于解码器中。模型更换时你应该重写的是零。你应该重跑的是你的评估集。
「一步一步思考「在当前模型上还有效吗？
基本上已经是多余的负担了。那个短语是针对那些会直接跳出答案的模型的变通方案，而当前模型在没有被告知的情况下已经会分解多步工作。更糟的是，把它附加到要求严格 JSON 输出的提示词上，会引导模型在对象外面输出推理说明文字，这正是让朴素提示词达到约 5-10% 格式错误 JSON 率的那类失败。如果你需要推理过程，在 Schema 中给它一个具名字段，让解析器把它与有效载荷分开保管。
JSON 模式够用吗，还是我需要 Schema？
用 Schema。JSON 模式能让你达到约 95-99% 语法有效输出，听起来还好，但当你每天运行一万次调用、承受上百次失败时就不够了。Schema 约束解码将语法有效性提升至本质上 100%，同时也固定了你的键名——这很重要，因为 RFC 8259 将 JSON 对象视为无序的名称-值对集合，只是建议键名唯一。语法有效性不等于语义正确性，所以无论如何都要继续根据你自己的规则验证解析后的对象。
持久的提示词应该包含多少少样本示例？
两到四个，选择时以边界覆盖为标准，而非数量。反复展示同一种正常路径的示例，不能教会模型任何它还不会的东西；锁定棘手情况的示例，才是能在不同模型间迁移的那些。对于结构化输出，至少用一个示例来区分空容器和缺失值的区别——因为[空对象 {} 和空数组 [] 都是合法 JSON，但与 null 语义不同](https://jsonic.io/guides/json-examples)。如果你的示例包含严格解析器会拒绝的格式，你就在教导失败：仅尾随逗号一项就占一项分析中约 40% 的 JSON 错误。
提示词评估集需要多大才有用？
三十到五十个标注用例能捕捉大多数回归，而二十个也好过大多数团队跑的那个零。数量不如构成重要：让评估集偏向你在生产中实际见过的失败模式，例如未加引号的键、单引号、字符串内未转义的引号、缺失逗号和隐藏 UTF-8 BOM 字符，这些都出现在有据可查的 JSON 错误分类中。先验证再格式化，这样你能捕捉到结构性破坏而不是掩盖它，这也是 QuickTinyData 推荐的工作流。将评估集与提示词一起做版本管理，新模型发布当天重跑。
同一条提示词真的能在 Claude、GPT 和 Gemini 上不经修改就运行吗？
指令主体可以干净移植。输出执行层则不行，因为 JSON 模式和 Schema 约束解码在各服务商的配置方式不同，所以计划好一条提示词加三个薄适配器。使用每家服务商都认可的格式来写契约有助于此：RFC 8259 与语言无关，定义了四种原始类型加对象和数组，小写的 true、false 和 null 是唯一的字面名称。如果你在寻找跨服务商管理提示词的工具，我们目录中有 212 个提示词工程工具，以及 AI 模型类别下的 324 个条目。