文字描述的歧义天花板在 63%，例子直达 91%

一个事实提取 agent 在同一个 100 文档数据集上测试了三轮 prompt 迭代：

v1 到 v2 的文字打磨提升了 3 个百分点。加例子直接跳了 28 个百分点。文字描述有一个更多形容词突破不了的歧义天花板。具体例子直接绕过它。

为什么文字描述不行

“用结构化格式总结发现”会产出要点列表、编号列表和 markdown 表格。三种都是”结构化”的合理解释。指令是模糊的，Claude 每次从有效选项中随机选一个。

更多细节修不了这个问题。“用简洁的要点格式，关键发现在前、支撑数据在后”仍然有解释空间——什么算”简洁”？哪些发现算”关键”？一个展示精确期望输出格式的具体例子一次性消除所有歧义。

文字规则可能创造新歧义

一个客服退货资格 agent 测试结果：

给保修退货加详细文字规则反而降了 5 个百分点。规则在边缘情况上创造了互相矛盾的解释。展示具体保修案例该怎么处理的例子把准确率从 65% 拉到 92%。

文字规则不总是叠加的。当它们和现有指令互动时，可能引入新的困惑而不是解决旧的。

好例子长什么样

输入/输出例子展示 Claude 应该执行的精确转换：

Input: "March 5, 2024"
Output: "2024-03-05"

Input: "12/31/23"
Output: "2023-12-31"

例子是：

• 具体的 — 不是”转成 ISO 8601”而是展示实际转换
• 多个 — 覆盖不同输入变体（可读格式、斜杠、缩写年份）
• 成对的 — 输入和输出作为转换一起展示

对于多格式任务，从同一输入展示多种格式。一个从提交生成发布说明和变更日志的 CI 流水线应该从同一个提交列表展示并排例子。

对于多语言任务，每种语言提供 1-2 个例子。Python、JS、Java、Go 和 Rust 的堆栈跟踪 → 用户消息转换各需自己的例子对，因为每种格式在结构上不同。

反模式：纯文字反馈

“写详细一点”不是可操作的反馈。不展示”详细”长什么样，Claude 每次解释都不同。展示你想要的详细程度的具体例子。

“用专业格式回复，带问候、解决步骤和结尾”产出不一致结果。展示 2-3 个精确期望格式的示例回复。

“用 conventional commit 格式”比什么都没有好但仍然模糊。展示精确的 diff → 提交消息转换：

Input: [添加 null 检查到 parse_record() 的 diff]
Output: "fix(parser): handle missing JSON field in parse_record()"

这一个例子同时解决了详细度、范围前缀和时态的问题。

什么时候投入做例子

例子最有价值的时候：

• 输出格式变化 — 同一指令在不同运行中产出不同结构
• 转换规则复杂 — 多种输入格式映射到一种输出格式
• 文字打磨已停滞 — 加更多形容词不再改善一致性
• 一个输入多个输出 — 同一提交生成发布说明 + 变更日志

例子不太关键的时候：

• 任务天然定义清晰 — “计算这些数字的和”没有格式歧义
• Schema 强制结构 — 带 input_schema 的 tool_use 提供例子无法改善的结构保证

迭代改进：先例子，再扩展

改进顺序应该是：

1. 从 2-3 个覆盖最常见案例的输入/输出例子开始
2. 在新输入上测试
3. 对出现的格式变体或边缘情况加例子
4. 发现新模式时更新例子

这比先写详细文字规则再加例子更有效。例子建立模式；文字可以在模式清晰后补充边缘情况引导。

一句话总结： 文字描述产出不一致时，别再加形容词了，展示 2-3 个具体的输入/输出例子——文字解决不了的格式歧义，例子一步消除。