empirical-prompt-tuning

实证式提示词调优

提示词的作者无法判断其质量。作者越觉得某处表达清晰，其他 Agent 就越可能在那儿碰壁。这项技能的核心是：让一个不带偏见的执行者实际运行指令，进行双向评估并不断迭代。在改进趋于平缓之前，不要停止。

适用时机

• 创建或大幅修改技能 / 斜杠命令 / 任务提示词后立即使用
• Agent 的行为不符合预期，且你想判断原因是否在于指令存在歧义时
• 加固高重要性的指令（频繁使用的技能、自动化核心提示词）时

不适用的情况：

• 一次性、用完即弃的提示词（评估成本得不偿失）
• 目标不是提高成功率，而只是反映作者主观偏好时

工作流

0. 第 0 轮迭代 — 描述与正文一致性检查（静态检查，无需派发）
   • 阅读 frontmatter description 声明的触发条件 / 使用场景
   • 阅读正文实际涵盖的范围
   • 如果两者存在差距，在进入第 1 轮迭代前调整描述或正文，使其保持一致
   • 示例：描述写着“导航 / 表单填写 / 数据提取”，但正文只是 npx playwright test 的 CLI 参考——要发现这类差距
   • 如果跳过这一步，子 Agent 就会为了匹配描述而“重新解读”正文；这样一来，准确率看起来会很高，但该技能实际上并未满足要求（假阳性）
1. 基线准备：固定目标提示词，并准备以下两项。
   • 评估场景：2 到 3 种（1 种中位场景 + 1 到 2 种边缘场景）。这些应是合理的任务，并假设目标提示词适用于实际情境。
   • 要求清单（用于计算准确率）。对于每个场景，列出交付内容必须满足的 3 到 7 项要求。准确率 % = 已满足项数 / 总项数。提前固定清单（之后不要调整）。
2. 无偏阅读：让一名“空白状态”的执行者阅读指令。通过 Task 工具派遣一名新子 Agent。不得用自己重新阅读来代替（从结构上说，你无法客观审视自己刚写下的文本）。并行运行多个场景时，在同一条消息中发起多个 Agent 调用。环境不支持派遣时的处理方式，请参阅“环境限制”部分。
3. 执行：按照下文所述的“子 Agent 调用约定”向子 Agent 提供提示词，并让其执行场景。执行者生成实现或输出，并在末尾提交自我报告。
4. 双向评估：从返回结果中记录以下内容。
   • 执行者自我报告（从子 Agent 报告正文中提取）：不明确之处／自行决定补充之处／应用模板时卡住的地方
   • 轨迹解读：为每个不明确之处标注其所属阶段（理解／规划／执行／格式化——参见“子 Agent 调用约定”）。针对具体阶段进行修正更有效；泛泛地说“提示词不明确”并不能解决问题。一个理解阶段的歧义，往往会表现为一连串执行阶段的失败。
   • 结构化反思：每个不明确之处都必须按 问题 / 原因 / 通用修正规则 的格式返回。通用修正规则 是可以纳入“失败模式记录表”的类别级抽象；缺少它，修正就会沦为一次性的补丁，之后还会重复犯同样的错。
   • 指令侧测量指标（判定规则以本节为准；其他部分请参照本节）：
     • 成功／失败：仅当所有标记为 [critical] 的要求均为 ○ 时，才算成功（○）。其中任意一项为 × 或部分满足，都算失败（×）。标签只能是二元的 ○／×。
     • 准确率（要求清单的达成率，%）：○ = 满分，× = 0，部分满足 = 0.5；求和后除以总项数。
     • 步数（原样使用 Task 工具返回值所附使用情况元数据中的 tool_uses 字段。包括 Read／Grep，不得排除）
     • 时长（Task 工具使用情况元数据中的 duration_ms）
     • 重试次数（子 Agent 重做同一决策的次数。从其自我报告中提取；无法从指令侧测得）
     • 失败时，在展示格式的“不明确之处”部分添加一行说明“哪项 [critical] 要求未达标”（用于追踪根本原因）
   • 要求清单必须至少包含一项标记为 [critical] 的要求（若没有，成功判定就会变得毫无意义）。事后不得增删 [critical] 标记。
5. 应用差异：对提示词进行最小限度的修正，以消除不明确之处。每次迭代聚焦一个主题（可以同时处理多个相关修正；不相关的修正留待下次）。
   • 应用修正前，明确说明“这项修正满足要求清单／判定措辞中的哪一项”（根据轴名称推断的修正往往无法解决问题。参见下文“修正传递模式”部分。）
   • 先查阅失败模式记录表。如果结构化反思中的 通用修正规则 与已知模式相符，首先要问：“为什么现有修正没有阻止它发生？”——可能需要将修正移至提示词更靠前的位置，或重新措辞，然后再添加新的记录条目。
6. 重新评估：使用新的子 Agent（不得重复使用同一个 Agent：它已经接触过之前的改进），再次运行第 2 至 5 步。若继续迭代后改进进入平台期，则增加并行度。
7. 收敛检查：粗略规则是“连续 2 轮没有新增不明确之处，且指标提升低于以下阈值时停止”。对于重要性较高的提示词，将轮数增加到 3 轮。

评估维度

维度	如何采集	含义
成功／失败	执行器是否生成了预期交付物（二元）	最低门槛
准确度	交付物满足的要求所占百分比	部分成功的程度
步骤数	执行器使用的工具调用／决策步骤数	指示指令浪费程度
耗时	执行器的 duration_ms	认知负荷的代理指标
重试次数	重复做出同一决策的次数	指示指令歧义程度
不明确之处（自述）	执行器以项目符号列出	定性改进材料
自行补充的内容（自述）	指令未明确规定的决策	揭示隐含的规范

权重分配：定性指标（不明确之处／自行补充的内容）为主要指标，定量指标（耗时／步骤数）为辅助指标。只追求缩短耗时会让提示词过于简略。

对 tool_uses 的定性解读

只看准确度会掩盖技能方面的问题。将 tool_uses 用作不同场景间的相对值，可以揭示结构性缺陷：

• 如果某个场景的数值是其他场景的 3–5 倍或更多，说明该技能倾向于依赖决策树索引，独立自足性较低。执行器被迫层层查阅参考资料。
• 典型示例：所有场景的 tool_uses 都是 1–3，但唯独一个场景达到 15+ → 该技能本身没有提供该场景的操作指南，因此执行器会跨文档搜索参考资料。
• 应对措施：在第 2 次迭代的 SKILL.md 顶部添加“内联的最小完整示例”或“何时阅读参考资料的指引”，可显著降低 tool_uses

即使准确度达到 100%，tool_uses 的偏斜也足以触发第 2 次迭代。仅凭“准确度达标”就停止，往往会漏掉结构性缺陷。

修复影响模式（保守／超额／零命中）

修复 → 效果并非线性。预估结果可能呈现以下 3 种模式：

• 保守偏差（预估值 > 实际值）：一项修复针对多个维度，但只推动了其中一个。“试图同时针对多个维度往往会落空。”
• 超额命中（预估值 < 实际值）：一项结构性信息（例如，命令 + 配置 + 预期输出的组合）一次满足多个维度的判断措辞。“信息组合在结构上同时命中多个维度。”
• 零命中（预估值 > 0，实际值 = 0）：根据维度名称推断出的修复，没有触及任何判断措辞。“维度名称和判断措辞是两回事。”

为使结果稳定，应用差异前，让子 Agent 明确说出“这项修复满足了哪些判断措辞”。只有将对应关系落实到阈值措辞层面，才能得到准确的估算。新增评估维度时，也要将每个分值的判断标准具体化到阈值措辞层面，并细化到子 Agent 可以判断的程度，例如“全部明确”或“最小可运行配置的完整文本”——这样它才能知道什么情况算 2 分。

子 Agent 调用约定

提供给执行器的提示词采用以下结构。这是“双向评估”的输入约定。

You are an executor reading <target prompt name> with a blank slate.

## Target prompt
<Paste the full body of the target prompt, or specify a path for Read>

## Scenario
<One paragraph setting the scenario context>

## Requirements checklist (items the deliverable must satisfy)
1. [critical] <item that belongs to the minimum bar>
2. <normal item>
3. <normal item>
...
(Judgment rules are canonically defined in "Workflow 4. Two-sided evaluation / Instruction-side measurements". At least one [critical] is required.)

## Task
1. Follow the target prompt to execute the scenario and produce the deliverable.
2. On completion, respond with the report structure below.

## Report structure
- Deliverable: <artifact or execution summary>
- Requirement achievement: ○ / × / partial (with reason) for each item
- **Trace** (tag OK / stuck / skipped for each phase, one-line reason when not OK):
  - Understanding (reading the instruction and building a mental model)
  - Planning (deciding the approach / ordering)
  - Execution (actually doing the work)
  - Formatting (shaping the deliverable to the expected form)
  - *Collapsed form allowed*: when all four phases are OK, a single line `Trace: all OK` is sufficient. Emit phase-by-phase only when any phase is stuck or skipped. (This avoids happy-path boilerplate; the trace structure only earns its cost when something actually goes wrong.)
- **Unclear points (structured)**: for each issue, three lines:
  - Issue: <what observably happened>
  - Cause: <why, diagnosed at the instruction level>
  - General Fix Rule: <a class-level rule, not a spot fix, that would prevent this class of mistake>
- Discretionary fill-ins: places not fixed by the instruction and filled in by your own judgment (bullets)
- Retries: number of times you redid the same decision and why

调用方从报告中提取自述部分，并从 Agent 工具的使用元数据中获取 tool_uses / duration_ms，以填充评估维度表。

环境限制

在无法调度新子 Agent 的环境中（例如，当前已作为子 Agent 运行、Task 工具已禁用等），不要应用此技能。

• 方案 1：请父会话的用户启动单独的 Claude Code 会话，并委派评估任务
• 方案 2：放弃评估，并明确向用户报告“经验评估已跳过：无法调度”
• 禁止：用自行重读来代替（这会引入偏见，因此不得相信评估结果）

结构审查模式：如果你只想检查技能／提示词描述的一致性和清晰度，而不是进行经验评估，请明确将其设为结构审查模式。在给子 Agent 的请求提示词中明确写出“本轮为结构审查模式：检查文本一致性，而非执行”。这样，子 Agent 就不会触发环境限制部分中的跳过行为，并且可以进行静态审查。结构审查是对经验评估的辅助，而非替代（不能用于判断是否连续达标）。

迭代停止标准

• 收敛（停止）：连续 2 轮满足以下全部条件：
  • 新的模糊点：0
  • 与上一轮相比的准确率提升：+3 分或更少（例如从 5% 提升到 8%，即为饱和）
  • 步骤数量变化：在 ±10% 以内
  • 持续时间变化：在 ±15% 以内
  • 过拟合检查：判断是否收敛时，增加 1 个此前未使用的保留场景并进行评估。如果准确率比近期平均值下降 15 分或更多，则视为过拟合。回到基线场景设计并补充边界场景。
• 发散（怀疑设计有问题）：如果连续 3 轮或更多轮中，新的模糊点没有减少，则提示词本身的设计方向可能有误。停止打补丁，重写结构。
• 资源截止：当重要性与改进成本不再相称时停止（即“以 80 分交付”）

失败模式记录表

在迭代过程中维护累积的失败模式清单。否则，每轮都会重新发现同一类错误，准确率提升也会停滞，而操作人员却意识不到同一条 General Fix Rule 只是在不同表面措辞下反复出现。

条目格式：

- **Pattern name**: short descriptive handle (not "ambiguous X"; prefer "over-eager template application when skip clause is absent")
  - Example: <representative Issue wording from some iter>
  - General Fix Rule: <the class-level rule from that iter's structured reflection>
  - Seen in: iter N, iter M, ...

规则：

• 在工作流步骤 5 中生成修复方案前，先检查记录表。如果当前的 General Fix Rule 与现有条目相符，请更新 Seen in，并调查现有修复为何未能防止问题再次出现（措辞含糊？在提示词中的位置太靠后？缺少示例？），然后再创建新条目。
• 如果某种模式在针对性修复后仍重复出现 3 次或更多，则这是结构性信号——应升级至上述“发散”标准，而不是继续打补丁。
• 记录表按目标提示词划分，不在所有经验提示词调优运行之间共享。

变体探索（可选，用于突破平台期）

当迭代接近平台期，但尚未满足收敛标准（连续 2 轮通过）时，应怀疑遇到了局部最优，并进行一轮双变体测试：

• 保守变体：当前提示词 + 下一个最佳的小幅修正
• 探索性变体：对当前提示词进行一项结构调整——调整各部分顺序、拆分密集段落、删除冗余部分，或补充缺失的脚手架（例如，完整示例）

针对相同场景并行派遣新的子 Agent（在一条消息中调用多个 Agent 工具）。保留准确率更高的变体；若打平，则优先选择不明确点更少的变体；若仍打平，则优先选择 tool_uses 更低的变体。

成对比较的注意事项：

• 不要让子 Agent 直接评定“A 与 B”。LLM 的位置偏差和自我偏好偏差会使小样本下的判断不可靠。
• 只比较客观指标（准确率、步骤数、不明确点数量、各阶段的薄弱项数量）。这些指标可复现；“哪个提示词感觉更好”则不行。
• 如果确实需要定性比较，应平衡顺序：分别按（A，B）和（B，A）的顺序进行测试，只有两种顺序得出一致结论时才接受该结论。

成本：变体探索会使每轮迭代的派遣次数翻倍。应在怀疑遇到平台期时使用，而非常规使用。

展示格式

在每轮迭代中，使用以下格式记录并呈现给用户：

## Iteration N

### Changes (diff from previous)
- <one-line fix content>
- Pattern applied: <pattern name from ledger, or "(new)">

### Execution results (per scenario)
| Scenario | Success/Failure | Accuracy | steps | duration | retries | Weak phase |
|---|---|---|---|---|---|---|
| A | ○ | 90% | 4 | 20s | 0 | — |
| B | × | 60% | 9 | 41s | 2 | Execution |

### Structured reflection (newly surfaced this time)
- <Scenario B>: [critical] item N is × — <one-line reason for drop>
  - Issue: <what observably happened>
  - Cause: <why, at the instruction level>
  - General Fix Rule: <class-level abstraction>
- <Scenario A>: (nothing new)

### Discretionary fill-ins (newly surfaced this time)
- <Scenario B>: <fill-in content>

### Ledger updates
- Added: <pattern name> (from Scenario B)
- Re-seen: <pattern name> (originally iter K) — existing fix did not prevent recurrence because <reason>

### Next fix proposal
- <one-line minimum fix>

(Convergence check: X consecutive clears / Y rounds remaining to stop condition)

危险信号（谨防自我合理化）

出现的自我合理化	实际情况
“我自己重读一遍也有同样的效果”	你无法“客观地”看待自己刚写的文本。务必派遣新的子 Agent。
“一个场景就够了”	一个场景会导致过拟合。至少 2 个，最好 3 个。
“有一次不明确点为零，就说明完成了”	这可能只是巧合。连续 2 轮通过后再定稿。
“我们一次性解决多个不明确点吧”	这样就无法追踪哪些做法有效。每轮只围绕一个主题。
“把每个相关的微小修正都严格拆成单独一轮”	这是另一个极端的陷阱。“一个主题”是一个语义单元。可以将 2～3 项相关微小修正合并到 1 轮中。拆得太细会大幅增加迭代次数。
“指标不错，所以可以忽略定性反馈”	时间缩短也可能意味着内容过于简略。定性反馈仍应优先。
“从头重写更快”	如果连续 3 轮以上不明确点都没有减少，这样做是合理的。在此之前，这只是在逃避。
“我们重复使用同一个子 Agent 吧”	它已经学到了之前的改进。务必派遣新的子 Agent。

常见失败

• 场景太简单／太难：两者都无法提供有效信号。一个应处于真实使用场景的中位水平，另一个则应是边缘场景。
• 只看指标：只追求缩短时间会删掉重要解释，使结果变得脆弱。
• 每轮改动太多：你将无法追踪“之前到底是哪项修正起了作用”。每轮只做一项修正。
• 调整场景以迎合修正：为了让不明确点看似消失而降低场景难度 → 本末倒置。

相关内容

• superpowers:writing-skills — 创建技能时采用的 TDD 方法。本质上与本技能的“基线 → 修复 → 使用子 Agent 重新运行”相同
• retrospective-codify — 在任务结束后固化经验。本技能用于提示词开发期间，retrospective-codify 用于任务结束后；两者用途不同
• superpowers:dispatching-parallel-agents — 并行运行多个场景的约定
• waxa-eval — waxa CLI 的操作手册。该 CLI 会将评估 / 迭代循环自动化为外部流程，使用 YAML 场景格式和持久化账本。本技能（empirical-prompt-tuning）涵盖方法论和会话内的 Task 工具子 Agent 流程；waxa-eval 涵盖CLI 操作和 YAML 编写。两者互为补充——使用 empirical 进行 Iter 0 静态检查、[critical] 标记的检查清单，以及基于 tool_uses 的技能诊断（这些都无法由 CLI 进程完成）；需要持久化、CI 可重复性或外部采用门槛时，使用 waxa-eval。