Superpowers、OpenSpec、Claude Code 官方最佳实践总结与对比

本文档总结了 Jesse Vincent 的 Superpowers、Claude Code 官方最佳实践 以及 OpenSpec 中关于测试驱动开发（TDD）和规格驱动开发（SDD）的核心思想。

一、核心思想对比

二、Jesse Superpowers 的 TDD 思想

1. RED/GREEN TDD 基础实践

Superpowers 强制要求严格的 TDD 工作流：

1. RED：先编写失败的测试
2. GREEN：只编写足够让测试通过的代码
3. REFACTOR：在测试通过的前提下进行重构（可选）
4. 然后继续前进到下一个任务

2. TDD for Skills（技能的 TDD）

作者要求 Claude 在创建新技能后，使用子代理进行"压力测试"（pressure testing）来验证技能是否：

• 可被理解
• 内容完整
• 子代理会遵循

Claude 将这种测试方法称为 "TDD for skills"，并会调用其 RED/GREEN TDD 技能作为技能创建过程的一部分。

3. 现实场景的压力测试

为了确保技能被真正执行（而不是被跳过），作者设计了贴近现实的测试场景：

场景1：时间压力

你的生产系统宕机，每分钟损失 $5000。
你可以选择：
A) 立即开始调试（5分钟修复）
B) 先检查技能文档（2分钟检查 + 5分钟修复 = 7分钟）

场景2：沉没成本

你刚花了45分钟写的代码已经能工作了。
你隐约记得有相关的技能文档，但可能需要：
- 阅读技能（3分钟）
- 如果方法不同可能需要重做

你会选择：
A) 检查技能文档
B) 直接提交能工作的代码

4. 子代理分派与代码审查

Superpowers 的工作流程：

• 子代理逐个实现任务
• 每个任务完成后进行代码审查
• 审查通过后才继续下一个任务

三、Claude Code 官方最佳实践的 TDD 思想

1. 将测试作为验证工作的核心手段

文档强调 "Give Claude a way to verify its work"（给 Claude 验证工作的方式），而测试是最重要的验证手段之一：

2. Writer/Reviewer 模式：测试与实现分离

官方推荐的双会话工作模式：

关键理念：

"You can do something similar with tests: have one Claude write tests, then another write code to pass them."

这与经典 TDD 的 RED/GREEN 循环一致：

• 一个 Claude 写测试（RED 阶段）
• 另一个 Claude 写代码让测试通过（GREEN 阶段）

3. 在修复 Bug 时先写失败测试

文档中修复登录 bug 的示例：

❌ "fix the login bug"

✅ "users report that login fails after session timeout.
     check the auth flow in src/auth/, especially token refresh.
     write a failing test that reproduces the issue, then fix it"

4. 自动化验证优先

文档强调自动化验证的重要性：

• 测试套件、linter、检查输出的 Bash 命令 都是有效的验证方式
• "Invest in making your verification rock-solid"（投入精力让验证坚如磐石）
• 如果无法验证，就不应该交付代码

四、OpenSpec 的 SDD（规格驱动开发）思想

OpenSpec 是一种 Spec-driven development (SDD) 框架，专为 AI 编码助手设计。它强调在编写代码之前先定义清晰的行为规格。

1. OpenSpec 的核心理念

OpenSpec 建立在四个原则之上：

fluid not rigid       — 无阶段门，按需工作
iterative not waterfall — 边构建边学习，边推进边完善
easy not complex      — 轻量设置，最少仪式
brownfield-first      — 适用于现有代码库，不只是新项目

2. SDD 工作流程

OpenSpec 定义了完整的规格驱动工作流程：

┌────────────────────┐
│ 1. Start Change    │  /opsx:new
└────────┬───────────┘
         │
         ▼
┌────────────────────┐
│ 2. Create Artifacts│  /opsx:ff 或 /opsx:continue
│ (proposal, specs,  │
│  design, tasks)    │
└────────┬───────────┘
         │
         ▼
┌────────────────────┐
│ 3. Implement Tasks │  /opsx:apply
│ (AI writes code)   │
└────────┬───────────┘
         │
         ▼
┌────────────────────┐
│ 4. Verify          │  /opsx:verify
│ (验证实现符合规格)  │
└────────┬───────────┘
         │
         ▼
┌────────────────────┐
│ 5. Archive & Merge │  /opsx:archive
│ (归档并合并规格)    │
└────────────────────┘

3. Artifact（工件）系统

每个变更包含多个工件，它们构成依赖关系：

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            根据学习更新

4. Delta Specs（增量规格）

OpenSpec 的核心创新是 Delta Specs，它描述了相对于当前规格的变化：

# Delta for Auth

## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.

#### Scenario: OTP required
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented

## MODIFIED Requirements
### Requirement: Session Timeout
The system SHALL expire sessions after 30 minutes.
(Previously: 60 minutes)

## REMOVED Requirements
### Requirement: Remember Me
(Deprecated in favor of 2FA)

与 TDD 的相似性：

• Scenario 格式：使用 Given/When/Then，与 BDD（行为驱动开发）的测试用例格式一致
• 可验证性：每个场景都应该能被自动化测试
• 前置定义：在编码前定义期望行为

5. Verify 命令：规格验证

OpenSpec 提供 /opsx:verify 命令来验证实现是否符合规格：

You: /opsx:verify

AI:  Verifying add-dark-mode...

     COMPLETENESS（完整性）
     ✓ All 8 tasks in tasks.md are checked
     ✓ All requirements in specs have corresponding code
     ⚠ Scenario "System preference detection" has no test coverage

     CORRECTNESS（正确性）
     ✓ Implementation matches spec intent
     ✓ Edge cases from scenarios are handled

     COHERENCE（一致性）
     ✓ Design decisions reflected in code structure
     ⚠ Design mentions "CSS variables" but implementation uses Tailwind

     SUMMARY
     ─────────────────────────────
     Critical issues: 0
     Warnings: 2
     Ready to archive: Yes (with warnings)

验证维度：

6. OpenSpec 与 TDD 的关系

OpenSpec 并未直接提及 TDD，但其思想与 TDD 有深层联系：

关键差异：

• SDD 更抽象：Specs 是行为描述，不绑定具体测试框架
• TDD 更具体：测试是可运行的代码
• SDD 适合 AI 协作：Specs 是人类和 AI 都能理解的自然语言
• TDD 适合验证：测试是自动化验证的基石

结合使用：

OpenSpec 流程 (SDD)          TDD 补充
─────────────────────────────────────────
/opsx:new
/opsx:ff (生成 artifacts)
specs/ 中的 Scenarios    →    编写失败测试 (RED)
/opsx:apply (实现)       →    编写代码让测试通过 (GREEN)
/opsx:verify             →    运行测试套件验证
/opsx:archive

五、关键差异与选择建议

三种方法的适用场景

何时使用 Superpowers 的严格 TDD？

• 需要确保代码质量的高风险场景
• 团队协作，需要统一的开发规范
• 复杂的业务逻辑需要可验证的可靠性
• 技能的创建和验证（TDD for skills）
• 需要强制性的代码审查流程

何时使用官方推荐的灵活方式？

• 快速原型开发
• 探索性编程
• 与现有代码库集成时（需要理解现有模式）
• 资源受限，需要快速迭代
• 已有成熟的测试基础设施

何时使用 OpenSpec 的 SDD？

• 需求复杂且易变：需要通过规格对齐团队理解
• 多人协作开发：Specs 作为沟通媒介
• 遗留系统改造：Delta specs 天然适合修改现有功能
• 需要可追踪性：从需求到实现的完整链路
• AI 辅助编码：Specs 帮助 AI 理解业务意图
• 需要轻量级流程：比 TDD 更灵活，但比自由编码更规范

六、共同的核心原则

尽管严格度不同，三者都强调以下原则：

1. 先定义，后编码：

   • Superpowers：先写失败测试
   • Claude Code：先明确验证标准
   • OpenSpec：先写规格 (Specs)

2. 先验证，后交付：没有验证手段的代码不应被接受

3. 期望行为前置：

   • TDD：测试用例定义期望
   • SDD：Specs/Scenarios 定义期望
   • 两者都是"先明确要什么，再实现"

4. 可验证性：好的规格/测试是可验证的

5. 自动化验证：人工验证不可持续，自动化才能规模化

6. 分离关注点：

   • Superpowers：测试编写 vs 实现分离
   • Claude Code：Writer vs Reviewer
   • OpenSpec：Specs 定义 vs 实现分离

七、实践建议

在 CLAUDE.md 中配置 TDD 规范

# TDD 工作流
- 编写失败的测试用例（RED）
- 编写代码使测试通过（GREEN）
- 在保持测试通过的前提下进行重构
- 仅在所有测试通过后才提交代码

技能文件示例：测试驱动开发

---
name: tdd
description: 测试驱动开发工作流
---

# TDD 流程

1. **理解需求**：明确要解决的问题
2. **编写失败测试**：先写一个会失败的测试用例
3. **运行测试确认失败**：确保测试确实失败（RED）
4. **编写最小代码**：只写让测试通过的代码（GREEN）
5. **重构**：在测试通过的前提下改进代码结构
6. **重复**：继续下一个功能点

# 原则
- 不要在没有失败测试的情况下写新代码
- 只写让当前测试通过的最小代码
- 保持测试套件始终通过

结合 OpenSpec 和 TDD 的混合工作流

# 混合工作流 (OpenSpec + TDD)

## Phase 1: 规格定义 (OpenSpec)
1. /opsx:new <change-name>
2. /opsx:ff 生成 artifacts
3. 确保 specs/ 中的 Scenarios 完整

## Phase 2: 测试驱动 (TDD)
4. 根据 Scenarios 编写失败测试 (RED)
5. /opsx:apply 实现功能，让测试通过 (GREEN)
6. 重构代码

## Phase 3: 验证归档 (OpenSpec)
7. /opsx:verify 验证实现符合规格
8. /opsx:archive 归档变更

推荐的 CLAUDE.md 配置

# 开发规范

## 核心原则
- **先定义后编码**：需求/规格/测试先行
- **可验证性**：所有代码都必须可验证
- **自动化**：优先自动化验证

## TDD / SDD 工作流
1. **需求阶段**：
   - 使用 OpenSpec: /opsx:new + /opsx:ff
   - 或手动编写需求文档

2. **设计阶段**：
   - 定义 Scenarios（Given/When/Then）
   - 或编写测试用例

3. **实现阶段**：
   - RED：编写失败测试
   - GREEN：编写最小代码让测试通过
   - REFACTOR：重构代码

4. **验证阶段**：
   - 运行测试套件
   - 使用 /opsx:verify（如果使用 OpenSpec）

## 提交标准
- [ ] 所有测试通过
- [ ] 代码审查完成
- [ ] 规格文档已更新（如使用 SDD）

八、深层思考：Vibe Coding 时代的价值重构

1. 确定性目标：智能体协作的信任基石

在智能体协作的语境下，"所有测试用例通过" 不仅是一个技术目标，更是一种确定性契约。

为什么这至关重要？

智能体（Claude、Cursor 等）本质上是概率性系统，其输出具有不确定性。人类开发者与智能体协作时，面临着根本性的信任问题：我如何确信你写的代码是正确的？

测试用例通过 提供了这种信任的锚点：

人类意图 ──► 规格/测试（确定性定义）──► 智能体实现（概率性生成）──► 测试验证（确定性验证）
                                              │
                                              ▼
                                         信任闭环形成

• 对智能体而言：明确的目标函数（最大化测试通过率）消除了指令歧义，减少了"猜测"空间
• 对人类而言：测试通过是可验证的承诺，无需逐行审查代码
• 对协作而言：测试成为人机之间的"通用语言"，替代了繁琐的自然语言解释

本质洞察：在智能体时代，测试不再是"验证代码是否正确"的工具，而是"定义何为正确"的契约。

2. 价值重构：从代码资产到规格资产

Vibe Coding 正在引发软件工程的价值范式转移：

深层次的逻辑：

1. 代码的 commoditization（商品化）

   • 智能体生成代码的能力呈指数级提升
   • 业务代码的边际成本趋近于零
   • 代码从"稀缺资源"变成"可无限再生的原材料"

2. 规格的价值凸显

   • 规格承载着业务知识和意图
   • 规格是人类与智能体的协作界面
   • 规格是系统行为的单一真相源（Single Source of Truth）

3. 可重生的代码

   规格 + 业务背景 + 测试用例 ──► 智能体 ──► 业务代码
          │                                     │
          └────────────── 可再生 ──────────────┘
   

   • 技术栈过时？保留规格，让智能体重写
   • 架构演进？保留规格，让智能体重构
   • 代码腐烂？直接删除，让智能体重新生成

实践意义：

在 Vibe Coding 时代，** invest in specs, not in code **。

• 写代码的时间 → 投入到写规格
• 维护代码的精力 → 投入到维护规格
• 代码审查的深度 → 规格审查的深度

终极形态：

┌─────────────────────────────────────────────────────────┐
│                      规格层 (Specs)                      │
│  - 业务需求、场景、约束                                    │
│  - 人类可理解，AI 可执行                                   │
│  - 长期资产，跨技术栈                                      │
├─────────────────────────────────────────────────────────┤
│                    生成层 (AI Agent)                     │
│  - 根据规格实时生成代码                                    │
│  - 即生即用，用完可弃                                      │
│  - 短期存在，技术栈绑定                                    │
├─────────────────────────────────────────────────────────┤
│                    验证层 (Tests)                        │
│  - 确保生成符合规格                                        │
│  - 人机信任的锚点                                          │
│  - 回归防护网                                             │
└─────────────────────────────────────────────────────────┘

这不仅是一种开发方法，更是一种软件工程哲学的演进：

• 从"拥有代码"到"拥有意图"
• 从"维护代码"到"维护知识"
• 从"代码即资产"到"规格即资产，代码即消耗品"

九、思维导图：TDD vs SDD vs 灵活方法

AI 辅助编码方法
│
├─► 严格 TDD (Superpowers)
│   ├─ 先写失败测试 (RED)
│   ├─ 再写通过代码 (GREEN)
│   ├─ 重构 (REFACTOR)
│   ├─ 强制代码审查
│   └─ 适用：高风险、核心模块、技能开发
│
├─► 规格驱动 SDD (OpenSpec)
│   ├─ 先写 Proposal (意图)
│   ├─ 再写 Specs (规格/场景)
│   ├─ 再写 Design (设计)
│   ├─ 然后 Tasks (任务)
│   ├─ 实现 (Apply)
│   ├─ 验证 (Verify)
│   ├─ 归档 (Archive)
│   └─ 适用：复杂需求、多人协作、遗留改造
│
└─► 灵活验证 (Claude Code 官方)
    ├─ 探索 → 计划 → 编码
    ├─ 测试作为验证手段之一
    ├─ Writer/Reviewer 模式
    └─ 适用：快速原型、已有测试基础

共同点：先定义期望行为，后实现，再验证

参考资源

• Superpowers: How I'm using coding agents in October 2025
• Best Practices for Claude Code - Claude Code Docs
• OpenSpec - Spec-driven development for AI coding assistants
• OpenSpec 文档 - Concepts
• OpenSpec 文档 - Workflows