superpowers 技能创建实录：从 Systematic Debugging 的 CREATION-LOG 看技能的提取、结构化与防合理化加固

Superpowers 仓库中的 CREATION-LOG.md 是官方标注的“从既有经验中提取、结构化并加固一项关键技能”的完整参考案例。本文以该创建日志为骨架，逐节还原 systematic-debugging 技能从 CLAUDE.md 经验碎片中被提取、按照技能规范重组、再用压力测试“防合理化（bulletproofing）”的全过程，并结合仓库中该技能目录下的真实文件（SKILL.md、四份测试用例、配套技术文档）印证日志中每一项决策的最终落地形态。读完本文，你能掌握一套可复制的方法：如何把一个“靠自觉才能遵守”的调试纪律，改造成 Agent 在时间压力、沉没成本、权威施压等场景下依然不会绕过的结构化技能。

一、这份创建日志的定位与来源材料

CREATION-LOG.md 开篇即说明了自己的身份：“Reference example of extracting, structuring, and bulletproofing a critical skill”——即作为提取、结构化与加固关键技能的参考范例，落款日期为 2025-10-03。它记录的不是技能本身的使用方式，而是“这项技能是如何被制造出来的”，这正是理解 Superpowers 方法论的关键：在 Superpowers 中，编写技能文档被视为测试驱动开发（TDD）在流程文档上的应用，技能的每一次修改都必须经过“看它在压力下失败”的验证。

日志首先交代了来源材料（Source Material）：调试框架被提取自 ~/.claude/CLAUDE.md，包含三类内容：

• 4 阶段系统化流程：Investigation（调查）→ Pattern Analysis（模式分析）→ Hypothesis（假设）→ Implementation（实现）；
• 核心强制要求（core mandate）：ALWAYS find root cause, NEVER fix symptoms（永远先找根因，绝不修症状）；
• 一系列专门设计用来抵抗“时间压力”和“自我合理化”的规则。

这一点值得强调：原始材料是放在个人全局指令里的经验性文字，问题在于 Agent 面对真实压力时容易把它合理化掉。创建日志的整个工程，就是把这种“散文式纪律”改造成“结构性纪律”。

二、提取决策：保留什么、丢弃什么

日志中的 Extraction Decisions 一节给出了明确的取舍清单，这是把个人经验转化为可复用技能的关键判断。

保留的内容：

• 完整的 4 阶段框架及其全部规则；
• 反捷径条款（anti-shortcuts），如 “NEVER fix symptom”（绝不修症状）、“STOP and re-analyze”（停下重新分析）；
• 抗压力语言（pressure-resistant language），如 “even if faster”（即使更快）、“even if I seem in a hurry”（即使我看起来很赶）；
• 每个阶段的具体操作步骤（concrete steps）。

丢弃的内容：

• 项目特定的上下文（project-specific context）；
• 同一规则的重复变体（repetitive variations）;
• 叙事性解释——压缩为原则性表述（narrative explanations condensed to principles）。

这个取舍标准与 Superpowers 技能写作规范的总原则一致：技能是“可复用的技术与模式”，而不是“某一次解决问题的叙事”。writing-skills 的 SKILL.md 中明确写道：“Skills are NOT: Narratives about how you solved a problem once”，并要求把超过一定体量的重型参考资料拆到独立文件。CREATION-LOG 的提取决策正是这一规范的具体执行。

三、结构化：按技能规范重组骨架

日志的 Structure 一节记录了按照技能创建规范（当时位于 skill-creation/SKILL.md，对应仓库中现有的 skills/writing-skills/SKILL.md）所做的 6 项结构决策：

1. 丰富的 when_to_use——不仅写“什么时候用”，还包含症状与反模式（symptoms and anti-patterns）；
2. 类型标记为 technique（技术型技能）——因为它是有具体步骤的流程，而非纯思维模式或 API 参考；
3. 关键词设计——“root cause”“symptom”“workaround”“debugging”“investigation”，保证技能在相关问题下能被检索与触发；
4. 流程图——针对“修复失败”这一决策点：是回去重新分析，还是继续叠加修复；
5. 逐阶段分解（phase-by-phase breakdown）——采用可快速扫读（scannable）的清单格式；
6. 反模式章节（anti-patterns section）——明确写出“不该做什么”，日志特别注明“对这项技能而言这一点至关重要”。

这些结构决策在当前仓库中的落地形态可以在 SKILL.md 中逐一对上：front matter 里的 description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes 对应第 1、3 项；“The Iron Law”一段——

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

紧随其后的“If you haven't completed Phase 1, you cannot propose fixes”对应第 4 项的强制流程门；“Red Flags - STOP and Follow Process”与“Common Rationalizations”两张清单/表格（见 SKILL.md）则对应第 6 项反模式设计。日志还给出了一张 Quick Reference 式的四阶段总览：Phase 1 读错误、复现、查变更、收集证据；Phase 2 找能工作的对照示例并比较差异；Phase 3 形成单一假设并最小化验证；Phase 4 建失败测试、单一修复、验证修复。

四、防合理化（Bulletproofing）：语言、结构与冗余三重防线

这是整份创建日志的技术核心。日志指出，框架的设计目标是“resist rationalization under pressure”（抵抗压力下的自我合理化），并分三层实现。

4.1 语言选择（Language Choices）

手法	示例
使用 “ALWAYS” / “NEVER” 而非 “should” / “try to”	“ALWAYS find root cause”
预设压力条件的让步从句	“even if faster”“even if I seem in a hurry”
显式的暂停指令	“STOP and re-analyze”（明确停顿点）
捕获具体行为措辞	“Don't skip past”（直接描述“跳过错误信息”这个真实动作）

从当前 SKILL.md 可以看到这些语言的成品形态：核心原则写成“Core principle: ALWAYS find root cause before attempting fixes. Symptom fixes are failure.”，并且补了一句极强的断言——“Violating the letter of this process is violating the spirit of debugging”（违反流程的字面即违反调试的精神）。这句“字面即精神”的声明，正是 testing-skills-with-subagents 中 Meta-Testing 章节总结出的结论：当 Agent 说“技能写清楚了，但我选择忽略”时，正确的对策不是改措辞，而是加入“违反字面就是违反精神”这类更基础的原则。

4.2 结构性防线（Structural Defenses）

语言只能改变语气，结构才能改变行为。日志列出 4 条结构防线：

• Phase 1 为必经阶段——从流程上无法跳过调查直接进入实现；
• 单一假设规则（single hypothesis rule）——强制一次只检验一个假设，防止“霰弹枪式修复”（shotgun fixes）；
• 显式失败模式（explicit failure mode）——“IF your first fix doesn't work”配一个强制动作（停下、重新分析），把“第一次修复失败”这个高危时刻变成了流程节点而非自由裁量时刻；
• 反模式章节——把捷径的“样子”精确写出来，让 Agent 在产生相同念头时能立刻识别它。

这些防线在 SKILL.md 中有对应的强化形态。例如 Red Flags 一节把 11 种“抓到自己正在想”的念头逐条列出（“Quick fix for now, investigate later”“It's probably X, let me fix that”“One more fix attempt (when already tried 2+)”等），并统一收束为“ALL of these mean: STOP. Return to Phase 1.”；Common Rationalizations 表格则用“借口 | 现实”两列对 8 种典型自我开脱逐一反驳，包括“Emergency, no time for process → Systematic debugging is FASTER than guess-and-check thrashing”这一条——它把“没空走流程”的借口反转成了“走流程反而更快”的论据。

4.3 冗余（Redundancy）

日志的第三层防线是刻意的重复：

• 根因强制要求在 overview、when_to_use、Phase 1、implementation rules 中各出现一次；
• 按日志记载，“NEVER fix symptom”在创建时以 4 次出现在不同上下文；
• 每个阶段都配有显式的“don't skip”指引。

这里的冗余不是写作失误，而是一种认知设计：同一个要求在“概述—适用条件—阶段清单—实施规则”四个不同的阅读时机重复出现，保证 Agent 无论从哪个入口切入技能文档，都会先撞上同一条强制要求。Superpowers 的技能写作规范对这类“纪律型技能”也持相同态度：testing-skills-with-subagents 明确指出，对每条新发现的合理化理由都要同时做四件事——在规则中加入显式否定（explicit negation）、在合理化表格里加一行、在 Red Flags 清单里加一条、在 description 里补充“即将违规的症状”。CREATION-LOG 记录的冗余策略就是这套加固循环的产物。

五、测试方案：四份测试用例与 RED-GREEN-REFACTOR

创建日志的 Testing Approach 一节声明：按照 skills/meta/testing-skills-with-subagents 的规范（该文档现位于 skills/writing-skills/testing-skills-with-subagents.md）创建了 4 份验证测试。日志给出的是结果摘要，而测试原文至今保留在技能目录中，可以逐份核对：

测试	压力维度	日志记载的结果	测试原文
Test 1: Academic Context（学术场景，无压力）	简单 bug，无时间压力	完全合规，完成完整调查	test-academic.md
Test 2: Time Pressure + Obvious Quick Fix（时间压力 + 明显的快捷修复）	用户“赶时间”，修症状看起来很容易	抵抗住捷径，走完整流程，找到真实根因	test-pressure-1.md
Test 3: Complex System + Uncertainty（复杂系统 + 不确定性）	多层故障，不确定能否找到根因	系统化调查，穿透所有层级，定位到源头	test-pressure-2.md
Test 4: Failed First Fix（第一次修复失败）	假设不成立，诱惑人继续叠加修复	停下、重新分析、形成新假设（没有霰弹枪式修复）	test-pressure-3.md

日志的结论是：“All tests passed. No rationalizations found.”（全部通过，未发现任何合理化说辞。）

把测试原文读一遍，就能理解“压力测试”具体长什么样。以 test-pressure-1.md（紧急生产故障）为例，它构建了多压力叠加场景：生产 API 宕机、每分钟损失 15,000 美元、经理点名要求“FIX IT NOW”、而日志里恰好有一个“加 2 分钟重试就能修好”的诱人方案，同时给出 A/B/C 三个选项——A 是走完整调查流程（再损失 52.5 万美元、显得无能），B 是“先快捷修复、后查根因”，C 是“最小化调查 + 快捷修复的折中”，并特意把折中选项标注为“Being pragmatic not dogmatic”（务实而非教条）。这正是 Superpowers 压力测试方法论所要求的“3+ 压力叠加”（时间 + 经济 + 权威）和“迫使 Agent 做出具体 A/B/C 选择而非开放式回答”。testing-skills-with-subagents 总结的判断标准在这里完全适用：只有当 Agent 在最大压力下选择正确选项、引用技能章节作为依据、并承认自己曾受诱惑时，技能才算 bulletproof。

另外两份压力测试同样值得细读：test-pressure-2.md（沉没成本 + 疲劳：调试 4 小时后用 sleep(1000) 碰巧通过两次，选项是删掉全部超时代码回到 Phase 1，还是留下 5 秒超时 + TODO 工单）和 test-pressure-3.md（权威 + 社交压力：Zoom 会议中资深工程师凭经验指定修复点，tech lead 催促“别浪费时间调查”）。值得注意的是，test-pressure-2 里“加大 sleep 时长碰运气”的失败轨迹，恰好就是同目录 condition-based-waiting.md 要解决的典型反模式——用“等待真实条件发生”替代“猜测等待时长”。测试场景与配套技术文档互为镜像，这正是“压力测试暴露的失败模式会回流到技能文档”的证据。

六、迭代过程：从初始版本到 TDD 引用

日志的 Iterations 一节记录了两个关键迭代：

1. 初始版本——完整的 4 阶段框架 + 反模式章节 + “修复失败”决策流程图；
2. Enhancement 1：加入 TDD 引用——补上一个指向 skills/testing/test-driven-development 的链接（该技能现位于 skills/test-driven-development/SKILL.md），并加了一条说明：TDD 里的“simplest code”（最简代码）≠ 调试里的“root cause”（根因），防止两种方法论被混淆。

这个迭代方向很有代表性：加固一项纪律型技能，不只是加更强的禁令，还要处理它与其他技能的语义冲突。当前 SKILL.md 的 Phase 4 里，这种交叉引用仍然存在——“Create Failing Test Case”步骤要求“Use the superpowers:test-driven-development skill”，“Verify Fix”步骤要求“Use the superpowers:verification-before-completion skill before claiming success”。技能目录因此形成了一个闭环：调试 → 写失败测试（引用 TDD 技能）→ 验证修复（引用验证技能）。

七、最终成果、关键洞察与使用示例

日志的 Final Outcome 给出了一份验收清单：明确强制根因调查；抵抗时间压力下的合理化；每个阶段提供具体步骤；显式展示反模式；经过多种压力场景测试；澄清与 TDD 的关系；随时可用。

Key Insight 一节是全文最有迁移价值的判断：

Most important bulletproofing: Anti-patterns section showing exact shortcuts that feel justified in the moment. When Claude thinks "I'll just add this one quick fix", seeing that exact pattern listed as wrong creates cognitive friction.

即：最有效的加固不是更强的命令，而是把“当下感觉很合理”的那些捷径逐条写出来。 当 Agent 脑中冒出“我就顺手加这一个快速修复”的念头时，看到完全相同的模式被明确标注为错误，会制造出认知摩擦（cognitive friction），从而打断自动化捷径。这与 SKILL.md 中 Red Flags 清单的写法完全吻合——清单里每一条都是“你抓住自己在想的原话”，而不是抽象的“不要偷懒”。

日志最后给出的 Usage Example 描述了日常使用这项技能的路径：

1. 遇到 bug 时加载技能 skills/debugging/systematic-debugging（仓库中现路径为 skills/systematic-debugging/SKILL.md）；
2. 花 10 秒读一遍概述——重新唤起对强制要求的记忆；
3. 按 Phase 1 清单执行——被流程强制进入调查；
4. 一旦产生跳过冲动——看到对应的反模式，停下来；
5. 走完全部阶段——找到根因。

日志给出的投入产出估算是：“Time investment: 5-10 minutes；Time saved: Hours of symptom-whack-a-mole”（投入 5–10 分钟，省下数小时的“症状打地鼠”）。

八、延伸：从日志到仓库——该技能目录的完整面貌

把 CREATION-LOG 当作“设计文档”、把技能目录当作“实现”，两者是可以互相印证的。当前 skills/systematic-debugging/ 目录包含：

• SKILL.md：主体技能，Iron Law + 4 阶段 + Red Flags + Common Rationalizations + Quick Reference，以及一节“When Process Reveals 'No Root Cause'”——允许流程走完后承认问题确实源于环境/时序/外部，但要求记录调查过程、实现合适处理（重试、超时、错误提示）并加监控，且警告“95% 的‘无根因’案例其实是调查不完整”；
• root-cause-tracing.md：Phase 1 第 5 步“Trace Data Flow”的完整展开——沿调用栈反向追踪到最初触发点再在源头修复，含 TypeScript 插桩示例和“空字符串 projectDir 导致 git init 落在源码目录”的真实案例；
• defense-in-depth.md：找到根因修复之后，在入口校验、业务逻辑、环境守卫、调试插桩四个层面各加一道验证，把“修好了 bug”升级为“让 bug 结构性不可能”；
• condition-based-waiting.md：用“等待条件成立”替代任意 sleep，附 waitFor(() => ...) 核心模式与场景速查表；
• find-polluter.sh：二分法脚本，逐条运行测试文件找出制造“环境污染”（如意外创建 .git）的测试，用法为 ./find-polluter.sh '.git' 'src/**/*.test.ts'；
• 四份测试用例 test-academic.md、test-pressure-1.md、test-pressure-2.md、test-pressure-3.md，即第五节所述的验证套件。

从源码结构看，SKILL.md 的 Phase 1 第 5 步、Phase 4 第 4/5 步分别显式指向上面的 root-cause-tracing.md 与 TDD 技能，形成“主文档负责流程门、辅助文档负责深水区技术”的分工——这正是创建日志“Structure”一节第 5 条（逐阶段可扫读分解）与 Superpowers 规范“重型参考资料拆到独立文件”原则的落地。

九、可复制的方法论：如何为下一个技能写 CREATION-LOG

CREATION-LOG 作为“参考范例”的最终价值，在于它示范了一条可复制的技能创建流水线。结合 writing-skills/SKILL.md 与 testing-skills-with-subagents.md，可以归纳为以下步骤：

1. 提取（Extract）：从个人经验、CLAUDE.md、历史会话中抽出框架；只保留通用规则与抗压力语言，丢弃项目上下文与重复变体（对照本文第二节的取舍清单）。
2. 结构化（Structure）：按技能规范给出 when_to_use（含违规症状）、类型、关键词、决策流程图、逐阶段清单、反模式章节。
3. RED——基线测试：先不给技能跑压力场景，逐字记录 Agent 的违规与说辞。Superpowers 的原话是：“If you didn't watch an agent fail without the skill, you don't know if the skill prevents the right failures.”
4. GREEN——写技能：只针对观察到的失败写最小规则，不写为假想情况预留的内容。
5. REFACTOR——补洞：对每条新说辞做四件事（显式否定 + 合理化表一行 + Red Flags 一条 + description 补症状），然后重测同一场景直到“Agent 在最大压力下仍选择正确选项”。
6. 写一份 CREATION-LOG：像 CREATION-LOG.md 这样记录来源材料、提取决策、结构决策、加固要素、测试结果与迭代历史——它既是技能的“设计文档”，也是下一个技能创建者可以直接模仿的范例。

需要说明的适用前提：这套方法的对象是纪律型技能（TDD、验证、系统化调试等“有合规成本、可能被合理化掉”的技能），而非纯参考型技能（API 文档、语法指南）；testing-skills-with-subagents 明确列出了不该做压力测试的情形。对纪律型技能，验证手段则是把带 3+ 压力叠加的 A/B/C 选项场景交给子代理执行，并核对它的选择、引用与对诱惑的承认——这正是本文第五节四份测试用例所演示的内容。

十、结语

CREATION-LOG.md 用一份创建日志完整回答了“如何让 Agent 遵守纪律”这个工程问题：答案不是把话说得更重，而是把纪律做进结构里——必经的 Phase 1 门、单一假设规则、显式的失败处理分支、把每条捷径原样写出来的反模式清单，以及“字面即精神”的基础原则；并且这一切都必须通过无技能基线、多压力叠加的 A/B/C 场景测试来验收。日志中 4 项测试全部通过、未发现任何合理化说辞的结论，加上技能目录中至今仍保留的测试原文与配套技术文档，使得这份 2025-10-03 的创建日志既是 systematic-debugging 技能的历史档案，也是 Superpowers 整个技能方法论的一份可直接执行的样板。