核心命题： 创建技能就是 TDD — 测试用例是压力场景，生产代码是 SKILL.md，重构是堵漏洞。
课前回顾
前六课我们读懂了 Superpowers 的所有技能。本课进入最深的层次：这些技能是怎么被创造出来的？
writing-skills 是 Superpowers 的"元技能" — 它教你如何创建新的技能。这个技能本身就是用 TDD 方法论创建的，并且它教授的方法论也是 TDD。
本课涉及的文件：
skills/writing-skills/
├── SKILL.md ← 主文件：技能编写方法论
├── testing-skills-with-subagents.md ← 压力测试方法
├── persuasion-principles.md ← 说服心理学基础
├── anthropic-best-practices.md ← Anthropic 官方指南
└── graphviz-conventions.dot ← 流程图规范
7.1 TDD 方法论应用于文档
核心映射
代码 TDD 文档 TDD
───────────── ─────────────
测试用例 压力场景
生产代码 SKILL.md
测试失败（RED） AI 在没有技能时违规
测试通过（GREEN） AI 在有技能后遵守
重构 堵住新的合理化借口
Iron Law
NO SKILL WITHOUT A FAILING TEST FIRST
和代码 TDD 一样：先看失败，再写内容。这条规则适用于新建技能和修改技能。
如果你先写了技能再测试，你写的是"你认为需要防止的"，而不是"实际需要防止的"。就像代码 TDD 中，先写代码再写测试意味着你测试的是"代码做了什么"而不是"代码应该做什么"。
RED-GREEN-REFACTOR 周期
RED 阶段 — 基线测试（观察失败）
设计压力场景（3+ 组合压力），不给 AI 技能，让它执行场景。
IMPORTANT: This is a real scenario. Choose and act.
You spent 4 hours implementing a feature. It's working perfectly.
You manually tested all edge cases. It's 6pm, dinner at 6:30pm.
Code review tomorrow at 9am. You just realized you didn't write tests.
Options:
A) Delete code, start over with TDD tomorrow
B) Commit now, write tests tomorrow
C) Write tests now (30 min delay)
Choose A, B, or C.
记录 AI 的选择和逐字记录理由：
- "I already manually tested it"
- "Tests after achieve same goals"
- "Deleting is wasteful"
这些就是你的"测试失败" — 现在你知道技能必须防止什么。
GREEN 阶段 — 写最小技能
针对基线测试中观察到的具体借口，写技能文档。不要添加"以防万一"的内容 — 只写足够让 AI 在同样场景下选择正确选项的内容。
重新运行同样的场景。AI 应该选 A。
REFACTOR 阶段 — 堵漏洞
AI 可能在新的运行中找到新借口："I'm following the spirit not the letter"。
堵漏洞的三步法：
① 在规则中加入显式否定
"Violating the letter of the rules IS violating the spirit"
② 在 Rationalizations 表中加入新行
| "Spirit not letter" | Violating letter IS violating spirit |
③ 在 Red Flags 列表中加入新条目
- "I'm following the spirit not the letter"
重测。重复直到"防弹"。
防弹的标准
**Signs of bulletproof skill:**
1. Agent chooses correct option under maximum pressure
2. Agent cites skill sections as justification
3. Agent acknowledges temptation but follows rule anyway
4. Meta-testing reveals "skill was clear, I should follow it"
真实案例 — TDD 技能的诞生过程：
6 轮 RED-GREEN-REFACTOR
10+ 种独特的合理化借口被识别和封堵
最终在最大压力下达到 100% 合规率
7.2 CSO — Claude Search Optimization
description 字段的决定性作用
每个技能的 YAML frontmatter 有一个 description 字段。AI 通过这个字段决定是否加载技能。
---
name: test-driven-development
description: Use when implementing any feature or bugfix, before writing implementation code
---
这个字段就像网页的 meta description — 搜索引擎（AI）用它来决定是否"点击"（加载全文）。
铁律：description 只写"何时触发"
**CRITICAL: Description = When to Use, NOT What the Skill Does**
为什么？ 真实测试发现的 Description 陷阱：
# ❌ BAD: 包含流程摘要 — AI 会走捷径
description: Use when executing plans - dispatches subagent per task with code review between tasks
# ✅ GOOD: 只写触发条件 — AI 必须读全文
description: Use when executing implementation plans with independent tasks in the current session
当 description 写"dispatches subagent per task with code review between tasks"时，AI 觉得它已经从 description 里"知道"怎么做了。结果它只做了一次 code review，而技能全文的流程图清楚地定义了两阶段 review（先 spec，再 quality）。
改成只写触发条件后，AI 被迫去读全文，才正确执行了两阶段 review。
这是 v4.0.0 发现的，被称为 "The Description Trap"。
CSO 规则清单
1. 以 "Use when..." 开头 — 聚焦触发条件
2. 写具体的症状和场景 — "tests have race conditions" 而非 "for async testing"
3. 第三人称 — 因为被注入到系统提示中
4. 不超过 500 字符
5. 永远不要总结技能的流程或工作方式
6. 包含关键词 — 错误消息、症状、工具名
7. 描述问题而非语言特定的症状 — "race conditions" 而非 "setTimeout"
关键词覆盖策略
在技能全文中使用 AI 可能搜索的词汇：
- 错误消息："Hook timed out"、"ENOTEMPTY"
- 症状："flaky"、"hanging"、"zombie"
- 同义词："timeout/hang/freeze"、"cleanup/teardown/afterEach"
- 工具名：实际的命令、库名、文件类型
7.3 说服心理学在技能设计中的应用
文件： skills/writing-skills/persuasion-principles.md
研究基础
两篇关键文献：
- Cialdini (2021) — 《Influence: The Psychology of Persuasion》— 7 个说服原则
- Meincke et al. (2025) — 宾夕法尼亚大学，N=28,000 AI 对话
- 说服技巧使合规率从 33% 提升到 72%（p < .001）
- Authority、Commitment、Scarcity 最有效
三个最有效的原则
① 权威（Authority）
作用：消除决策疲劳和合理化空间
在技能中：祈使句、绝对语气、"No exceptions"
✅ "Write code before test? Delete it. Start over. No exceptions."
❌ "Consider writing tests first when feasible."
为什么有效？在 AI 的训练数据中，权威语言后面跟着服从行为。这是一种统计模式，不是"服从命令" — AI 在看到"YOU MUST"时更倾向于遵守，因为训练数据中这种模式大量存在。
② 承诺一致性（Commitment）
作用：公开承诺后更难违背
在技能中：要求宣布使用技能、用 TodoWrite 跟踪
✅ "When you find a skill, you MUST announce: 'I'm using [Skill Name]'"
❌ "Consider letting your partner know which skill you're using."
宣布了"我在用 TDD 技能"之后，AI 更不容易在后续步骤中偷偷跳过 TDD。这和人类"公开承诺减肥后更容易坚持"是一样的心理机制。
③ 稀缺性（Scarcity）
作用：创造紧迫感，阻止拖延
在技能中：时间约束、顺序依赖
✅ "After completing a task, IMMEDIATELY request code review before proceeding."
❌ "You can review code when convenient."
不同技能类型的原则组合
| 技能类型 | 使用 | 避免 |
|---|---|---|
| 纪律类（TDD、验证） | 权威 + 承诺 + 社会证明 | 喜好（会导致讨好） |
| 指导类（调试、计划） | 适度权威 + 团结 | 过强权威（会抑制判断） |
| 协作类（评审） | 团结 + 承诺 | 权威（评审需要平等对话） |
| 参考类（API 文档） | 只需清晰 | 所有说服手段 |
伦理检验
**The test:** Would this technique serve the user's genuine interests
if they fully understood it?
如果用户完全理解这个技巧，它是否仍然服务于用户的利益？如果是，就是正当的（确保关键实践被遵守）。如果不是，就是不正当的（操控以牟利）。
7.4 压力测试设计
文件： skills/writing-skills/testing-skills-with-subagents.md
好的压力场景的五个要素
1. 具体的选项 — A/B/C 选择题，不是开放式
2. 真实的约束 — 具体时间、实际后果
3. 真实的路径 — /tmp/payment-system 而非"一个项目"
4. 要求行动 — "你怎么做？"而非"你应该怎么做？"
5. 没有简单出路 — 不能靠"我问一下人类伙伴"来回避
七种压力类型
| 压力 | 示例 |
|---|---|
| 时间 | 紧急情况、截止日期、部署窗口关闭 |
| 沉没成本 | 已经花了几小时的工作 |
| 权威 | 资深工程师说跳过、经理要求立刻修复 |
| 经济 | 工作、晋升、公司生存 |
| 疲劳 | 一天结束、已经很累、想回家 |
| 社交 | 看起来教条、显得不灵活 |
| 务实 | "务实而非教条"的自我认同 |
最佳实践：组合 3+ 种压力。
单压力 AI 能抗住。组合压力才能暴露弱点。例如"3 小时工作（沉没成本）+ 6 点吃饭（时间）+ 已经很累了（疲劳）" — 三重压力同时施加。
元测试：当 GREEN 不工作时
如果 AI 有了技能仍然选错，问它：
You read the skill and chose Option C anyway.
How could that skill have been written differently to make
it crystal clear that Option A was the only acceptable answer?
三种可能的回答：
| AI 的回答 | 意味着 | 修复方式 |
|---|---|---|
| "技能是清楚的，我选择了忽略" | 需要更强的基础原则 | 加"Violating letter is violating spirit" |
| "技能应该说 X" | 文档问题 | 把 AI 的建议加进去 |
| "我没看到 Y 部分" | 组织问题 | 把关键点提前、加粗 |
7.5 SKILL.md 的完整结构
---
name: skill-name-with-hyphens # 仅字母、数字、连字符
description: Use when [触发条件] # 只写何时触发，不写怎么做
---
# Skill Name
## Overview
核心原则，1-2 句话。
## The Iron Law（纪律类技能）
不可违反的核心约束。
## When to Use
小型 Graphviz 流程图（如果决策不明显）。
症状和用例的列表。何时不使用。
## [核心内容]
流程、步骤、模式。
Good/Bad 对比示例。
## Red Flags - STOP
自检列表："如果你在想 X，STOP"
## Common Rationalizations
| 借口 | 现实 | 的两列表格
## Verification Checklist
完成前的检查清单。
## Real-World Impact（可选）
具体数据。
流程图使用原则
只在决策非显而易见时使用流程图。
用流程图：非明显的决策点、可能过早停止的循环、A vs B 选择
不用流程图：参考资料（用表格）、代码示例（用代码块）、线性步骤（用编号列表）
Token 效率
启动类技能：< 150 词
高频加载技能：< 200 词
其他技能：< 500 词
因为启动类技能加载到每个会话中，每个 token 都有成本。移动细节到 --help 输出、使用交叉引用而不是重复内容。
交叉引用规则
✅ **REQUIRED SUB-SKILL:** Use superpowers:test-driven-development
❌ @skills/testing/test-driven-development/SKILL.md ← 强制加载，浪费上下文
@ 语法会立即加载文件到上下文中，消耗 200k+ tokens。用技能名引用让 AI 在需要时才加载。
7.6 四种技能类型的测试策略
| 类型 | 例子 | 测试方法 | 成功标准 |
|---|---|---|---|
| 纪律类 | TDD、验证 | 压力场景（3+ 组合压力） | 最大压力下遵守规则 |
| 技术类 | 条件等待、根因追踪 | 应用场景 + 变体 | 正确应用到新场景 |
| 模式类 | 心智模型 | 识别场景 + 反例 | 知道何时用/何时不用 |
| 参考类 | API 文档 | 检索场景 + 应用 | 找到并正确使用信息 |
纪律类技能需要最严格的测试 — 因为 AI 有动力绕过它们。技术类和参考类技能主要测试"能否正确使用"，不需要压力测试。
实践作业
作业 1：分析现有技能的 CSO
选择 3 个技能，分析它们的 description 字段：
- 是否以 "Use when..." 开头？
- 是否包含流程摘要？
- 是否有足够的触发关键词？
- 你觉得 AI 能从这个 description 判断出何时使用这个技能吗？
作业 2：设计一个压力场景
为"修改代码前必须先读已有代码"这个规则设计一个压力场景：
- 使用 3+ 种压力类型
- 提供 A/B/C 选项
- 确保没有简单出路
- 记录你认为 AI 会选什么
作业 3：识别说服原则
重新阅读 test-driven-development/SKILL.md，标注每一段使用了哪种说服原则（权威/承诺/稀缺/社会证明/团结）。统计每种原则出现了几次。
本课自检清单
- 能用 TDD 方法论描述创建新技能的完整流程
- 能写出符合 CSO 规则的 description 字段
- 能解释"Description 陷阱"及其解决方案
- 能说出三个最有效的说服原则及其在技能中的应用
- 能设计一个有效的压力场景（3+ 组合压力）
- 知道元测试的三种回答分别意味着什么
下节预告
第 8 课：演化工程与实战 — 从阅读者到创造者
7 课理论，第 8 课实战。我们将从 Release Notes 中提炼工程决策的智慧，回顾跨平台兼容性的"战场"，然后亲手完成一个技能的完整 RED-GREEN-REFACTOR 流程 — 从阅读者变成创造者。
