superpowers 技能指引的正向指令重设计：基于实测数据判定禁令何时失效、何时有效

本文基于 superpowers 仓库中的设计规格 2026-06-10-positive-instruction-redesign-design.md，讲解一套面向 agentic 技能文档（SKILL.md 及其 prompt 模板）的措辞工程方法论：如何用微测试（micro-test）量化"禁令式指引"与"正向配方式指引"对模型产出物的真实影响，并给出一条可复用的五原则判定法则——读完你可以学会审计任何技能文档中的负面指令、按机制类别决定保留或改写，并复用文中低成本微测试 harness 的完整设计。

1. 起因：一次实测发现的"反效果"

这份设计规格的驱动来源是 2026-06-10 的一组微测试（micro-test）。测试在 opus 模型上进行，每种措辞变体采样 5 次，采用程序化打分（programmatic scoring），harness 细节见本文第 5 节。测试测量的是：技能指引的措辞方式如何改变控制器（controller）实际"撰写"出来的工件（dispatch prompt、plan、report）的内容。实测结果如下表：

用例	措辞	结果
Dispatch 组合（"don't restate the brief"）	禁令	4.4 分——规格值被重新键入，比无指引（3.6）还差
Dispatch 组合	正向配方（"your dispatch should contain: (1)…(5)"）	3.0，零方差——被采纳
Dispatch 组合	配方 + 细节从句（"quote only the fragment…"）	3.8，噪声大——细节从句稀释了配方效果
测试重跑指令（"do not ask reviewer to re-run tests"）	禁令	0/5 违规——工作良好（对照：3/5 违规）
测试重跑指令	正向配方	0/5——打平，但更长

关键点在于：同样是禁令，一个明显反效果，一个完全有效，而且两者的差异是可以预测的——这正是本文要给出的分类法则。规格状态为 Proposed，定位是 2026-06-09 SDD review-dispatch 工作（见 2026-06-09-sdd-task-scoped-review-dispatch-design.md）的后续项，遵循"一个 PR 只解决一个问题"规则单独拆出。

2. 五原则判定法则（doctrine）

规格将实测发现归纳为一条可用于分类任意负面指令的法则：

1. 触发器（tripwire）有效。 针对具体词元的短语级自检（"if the prompt you are writing contains 'do not flag' … stop"）能可靠触发。
2. 识别表（recognition table）有效。 Red-Flags / 合理化借口（rationalization）表格是在"决策时刻"读取的，而非在"组合时刻"读取的。
3. 离散指令型禁令有效。 当模型对做 Y 没有竞争性激励时，"不要要求 X 做 Y"可以稳定成立。
4. 组合型禁令会反效果，当模型对该输出有自己的议程时（例如：复述规格在模型看来像是"有用的策展"）。这类情形只有正向组合配方能移动它——而且给一个已经获胜的配方追加细节从句，只会让它更差，不会更好。
5. 平局时选更短的措辞。 规格引用实测数据：Codex 在长会话中会重读 SKILL.md 约 500 次（2026-06-10 测量），正文长度是真实成本。

从源码结构看，法则第 1、2、3 条在 superpowers 现有技能中都有对应实现：skills/subagent-driven-development/SKILL.md 中的 tripwire 原文为"If the prompt you are writing contains 'do not flag,' 'don't treat X as a defect,' 'at most Minor,' or 'the plan chose' — stop: you are pre-judging, usually to spare yourself a review loop"；而第 2 条的识别表对应 skills/writing-plans/SKILL.md 的 "No Placeholders" 禁用模式列表，它同时充当 Self-Review 阶段的扫描清单。

3. 全量审计结果：约 30 个技能 + prompt 模板

规格对仓库中约 30 个技能及所有 prompt 模板做了措辞审计，统计结果为：3 个触发器（保留）、14 个识别表（保留）、约 20 个策略门禁（policy gates，保留——如"never push without permission"属于策略而非组合塑形），以及 5 个组合型禁令（composition-prohibitions），逐个给出处置：

#	位置	处置
1	subagent-driven-development/task-reviewer-prompt.md — "Cite, don't narrate"	排入 PR #1717 批次：以正向半句领头（"Your report should point at evidence: file:line for every finding…"），删去禁令半句（死重——正向半句已存在且承担全部工作）
2	subagent-driven-development/SKILL.md — "Do not add open-ended directives"	保持原样：微测试在 15 个样本中未能诱发出该失败；两边都没有证据；更短的表述获胜
3	subagent-driven-development/SKILL.md — "Do not ask a reviewer to re-run tests"	保持原样：实测 0/5 违规；该禁令还有用——它会自我传播进各个 dispatch
4	subagent-driven-development/SKILL.md — "do not re-review on top of it"	排入 PR #1717 批次：替换为三要素检查清单（"Before re-dispatching the reviewer, confirm the fix report contains: the covering tests, the command run, and the output"）
5	writing-plans/SKILL.md — "No Placeholders" 禁用模式列表	本规格的主要对象——见下节

边界项（borderline），与 #5 一并推迟处理：task-reviewer-prompt.md 中的"Don't flag pre-existing file sizes — focus on what this change contributed"（正向半句存在且承重；影响较小；如方便可与 #5 一起测）。

对照当前仓库源码可以验证审计结论的落地状态：task-reviewer-prompt.md 中确实是以正向表述承载报告形态约束——"Your report should point at evidence: file:line references for every finding… Every line is a verdict, a finding with file:line, or a check you ran — no preamble, no process narration, no closing summary"；而 subagent-driven-development/SKILL.md 中审计表 #2、#3 对应的两条禁令目前仍是禁令原样，与"保持原样"的处置一致。

4. writing-plans 的改动：一个"真正不确定"的案例

4.1 现状

skills/writing-plans/SKILL.md 的 "No Placeholders" 小节结构是：一句正向句子（"Every step must contain the actual content an engineer needs"）后跟一个六条 bullet 的禁用模式列表——"never write them: 'TBD', 'TODO', 'implement later', 'fill in details', 'Add appropriate error handling', 'Write tests for the above', 'Similar to Task N'…"。

4.2 为什么重要、为什么真正不确定

• 计划（plan）是工作流中最大的生成工件，且模型对输出占位符有真实的竞争性激励（在长度压力下占位符是最省力路径）——这正是"禁令实测反效果"那个用例的激励结构。
• 但被禁的条目是离散、可识别的词元——又是"禁令实测有效"那个用例的形态。
• 该列表在别处是承重的：技能中的 Self-Review 小节显式引用它（"Placeholder scan: search your plan for red flags — any of the patterns from the 'No Placeholders' section above"，见 SKILL.md 第 144 行）。这些词元同时充当审查时刻的扫描清单，而"审查时刻的识别"恰是法则中有效的类别。天真地把它换成正向检查清单会破坏这条引用，并丢弃好的触发器词元。

4.3 待测变体

• V0（现状）：组合时刻 = 正向句子 + 禁用列表；Self-Review 引用该列表。
• V1（审计员检查清单）：组合时刻只保留正向配方——"Before finalizing a step, confirm it has: the literal code to write, a runnable command with expected output, types and method names defined within this plan, error handling shown explicitly. A step is complete when an engineer could implement it without asking any follow-up questions." Self-Review 保留通用的占位符扫描。
• V2（按机制重构——预测获胜者）：组合时刻只拿到 V1 的正向配方；被点名的模式整体迁移到 Self-Review 的占位符扫描步骤，重新框定为识别语气（"when you scan, look for: 'TBD', 'TODO', 'Similar to Task N', …"）。同样的词元，从"会被 prime 的类别"迁到"负责检测的类别"。
• V3（对照）：只有一句正向句子，任何位置都没有列表。

V2 的设计思想是规格中最值得借鉴的一手：不是删除负面内容，而是把它从"撰写时刻会污染产出的位置"搬到"审查时刻负责识别的位置"——这正是法则第 1、2 条（触发器与识别表在决策时刻读取才有效）的直接应用。

4.4 微测试设计

• 任务：让 opus 从一份刻意欠规范的 spec 写一个 2–3 个 task 的实现计划（欠规范恰恰是诱发占位符的条件）。fixture spec 包含：一个规范完整的 task、一个错误处理被 spec 含糊带过的 task、一个与第一个 task 相似的 task（诱发"Similar to Task 1"）。
• 采样：每个变体 5+ 次重复，默认温度，模型 claude-opus-4-8（实际写计划的模型）。
• 程序化打分（除注明外，越低越好）：
  • 禁用词元计数：TBD|TODO|implement later|fill in details|appropriate error handling|handle edge cases|Similar to Task|Write tests for the above
  • 在改动代码的步骤中缺少围栏代码块的步数
  • 引用了计划输出中任何位置都未定义的 type / 函数
  • （越高越好）每个 task 中带预期输出的可运行命令数
• V2 的两阶段打分：还要测 Self-Review 那一半——把每个生成的计划连同该变体的 Self-Review 小节喂回去，测量扫描是否真的能抓住植入的占位符（在 fixture 计划中插入 2 个已知占位符，检测率即指标）。
• 验收条件：只有当某个变体在禁用词元计数上胜过 V0、且不损失代码块覆盖率与 self-review 检测率时才采纳。预计成本约 $6–10 总计。

4.5 PR 范围界定

单独开 PR（writing-plans 是不同的技能；它的 "No Placeholders" 列表是精调内容，贡献指南要求提供 eval 证据）。PR 必须包含：微测试 harness + 结果表、before/after 文本、以及 V2 迁移的设计理由。

5. 微测试 harness 的方法学（防丢失存档）

规格专门留了一节记录 harness 方法，指出其脚本位于 /tmp/sdd-exp/micro/run-micro.py 与 /tmp/sdd-exp/micro2/run-micro2.py（2026-06-10；计划提交至 superpowers-evals 仓库的 docs/superpowers/skills/micro-testing-prompt-guidance.md + scripts），方法要点：

• 每个样本一次 API 调用：system prompt = 技能指引变体 + 贴近真实的周边上下文；user = 一个贴近真实的工作流中段场景；output = 组合出的工件（dispatch prompt、plan、report）。
• 程序化打分用 grep 找无歧义标记，但在信任任何结论前必须人工检查每一处匹配——当晚的一个"违规"其实是控制器在正确引用该禁令，自动否定检测还把另一处误标了。
• 约 $0.15–0.30/样本，每次迭代几秒，对比 $12/50 分钟的完整 eval 跑。措辞层面在这里迭代；只有当改动是结构性的时才在完整跑中确认获胜者。
• 永远包含一个无指引对照（no-guidance control）——当晚的对照同时揭示了一个反效果（复述：禁令比什么都差）和一个有效的禁令（测试重跑：对照 3/5 失败 vs 任一种措辞都 0/5）。

这条"永远带无指引对照"的经验是整个方法学中最容易被忽略、却最决定结论真伪的一步：没有它，你无法区分"指引有效"与"指引反效果"——两者的唯一判别就是那个 3.6 的基线。

6. 最终结果：实测后判定"无需改动"

规格在写完之后追加了 writing-plans 微测试的实际运行结果（2026-06-10）：

Resolved — 无需改动。

• Stage 1（3-task spec，无压力）：所有 4 个变体（含无指引对照）的全部 20 份计划中占位符为 0。
• Stage 1b（10-task spec，五条近乎相同的命令刻意诱发"Similar to Task N"，外加显式约 2,500 词的篇幅经济目标）：40/40 干净——唯一的正则命中是一处 V2 self-review 在证明"no TBD/TODO ✓"。
• 结论：当前代 opus 即使在刻意的压力下、无论有无禁用模式列表，都不会在计划中产出占位符。

处置：原样保留 No Placeholders 小节（它代价很低，而反事实不可测量）；不打开后续 PR。V2 迁移设计保留在规格中存档——如果未来某代模型出现回退，可直接启用。

这是一个"用数据关闭问题"的完整样例：规格预写了 V0–V3 全套实验设计与验收标准，实测结果反而否定了改动本身的必要性——V2 从一个"待执行的重构"降级为"存档的应急设计"，且这个决定本身就基于该规格定义的两阶段测量。

7. 明确不再提议的优化（tested-and-declared，附数据）

规格最后记录了一批"已测且被否决"的方向，并注明完整数字见 2026-06-09 SDD 设计规格的 Cost-iterations 小节（见 2026-06-09-sdd-task-scoped-review-dispatch-design.md），目的是"没有新证据就不要重新提议"：

• 控制器回合批处理 / 单条消息并行工具调用：控制器每条消息恰好发一个工具调用（所有测量跑中 0 条多工具消息，有无指引都一样）。46% 的控制器回合是不带工具调用的思考/叙述——这是一条对 prompt 免疫的地板。
• 经并行调用的流水线化 review：同一原因下判死。
• 经 run_in_background 的流水线化 review：机制在提供时被采纳（7/28 个 dispatch 使用），但在 45 分钟场景上收益低于运行间噪声地板（每个 review 只有约 30–60 秒）；还引入了双结果流协调成本。只有当计划中各个 review 单独耗时较长时才值得重审。
• 向获胜配方追加细节从句：实测会退化它（C2：3.8 有噪声 vs C：3.0 稳定一致）。正确的迭代方式是重新推导配方，而不是追加免责声明。

8. 可复用的实操结论

把这份规格抽象为可迁移到任何 agentic 技能文档工程的 checklist：

1. 审计前先分类：把你文档里每条负面指令按"触发器 / 识别表 / 策略门禁 / 离散指令禁令 / 组合型禁令"五类归档。只有最后两类需要实验，前两类和策略门禁原则上保留。
2. 组合型禁令不要凭直觉删或留：先跑无指引对照 + 禁令版 + 正向配方版的微测试，每个变体 5+ 次重复、程序化打分 + 人工复核每一处命中。
3. 改写时"搬"而不是"删"：像 V2 那样，把组合时刻会 prime 的词元整体迁移到审查时刻的识别步骤，词元不变、位置换类别。
4. 平局选短：正文长度在长会话中被数百次重读，是随会话累积的真实成本。
5. 用实测结果关闭规格：本规格最有价值的不只是"怎么改"，而是记录了"测完之后不改"的决策路径——包括验收标准、成本估算（约 $6–10）和把未采纳设计存档备用的机制。

适用前提与限制：上述实测均在 2026-06-10 的模型与场景下完成（写作侧模型为 claude-opus-4-8，dispatch 侧为 opus 微测试），结论对"当前代模型行为"成立；规格自身也明确标注 V2 设计"should a future model generation regress"时才重新启用，即这些数值结论应视为随模型代际需要复测的经验数据，而非恒定事实。