Claude Code + OpenSpec + Superpowers：三件套到底是刚需还是过度工程？

Claude Code、OpenSpec、Superpowers 各自要解决的三个坑

如果你用过 Claude Code 或类似的 AI 编程工具，下面三个场景一定不陌生。这篇文章的核心就是把每个坑对应到真正能解决它的那个工具——并且拆穿"一个工具搞定所有坑"的常见误区。

场景一：AI 做的不是你想要的。 你说"加个用户登录功能"，AI 给你做了 Session 认证——但你要的是 JWT。你说"扫码支付"，AI 直接对接了真实支付 SDK——你只是想做个演示。每次返工都在烧 Token 和时间，而且你往往要到看完代码才发现方向错了。

场景二：AI 跳过测试直接写代码。 Claude Code 能力很强，但它的默认行为是"收到需求就动手"。不创建 Git 分支、不写测试、不做代码审查——能出活，但出了事你根本不知道哪里有问题。搞砸了还不好回滚，因为它直接改的是你的主分支。

场景三：多次迭代后，早期决策被盖掉。 为什么选了 bcrypt 而不是 argon2？为什么接口前缀是 /api 而不是 /v1？只用 Claude Code 裸跑时聊天窗口一关就没了；加上 Superpowers 能把 design doc 落到磁盘上（好一点），但下一次 brainstorming 会直接覆盖 design.md，不是版本化归档。三轮迭代以后，最初的权衡理由已经被新的设计覆盖，谁都说不清当初为什么做了那个选择。

这三个坑不是靠写更好的 prompt 能解决的——它们需要不同层面的工具来分别应对：裸用 Claude Code 扛不住场景一；Superpowers 把场景二闭环掉；只有 OpenSpec 的 Delta/Archive 机制能真正闭环场景三。这才是 Claude Code + OpenSpec + Superpowers 三件套组合的底层逻辑。

flowchart LR
    A["一句话需求"] -->|坑 1| B["做出来的不是你要的
(要 JWT 给了 Session)"]
    A -->|坑 2| C["不建分支 / 不写测试
不做 review"]
    A -->|坑 3| D["关掉聊天窗口
所有决策就没了"]

    B --> E["Token 白烧
反复返工"]
    C --> F["出活快
翻车也快"]
    D --> G["三个月后维护
谁都想不起来为啥"]

    style B fill:#c53030,color:#fff
    style C fill:#dd6b20,color:#fff
    style D fill:#805ad5,color:#fff
    style E fill:#4a5568,color:#fff
    style F fill:#4a5568,color:#fff
    style G fill:#4a5568,color:#fff

第一层：认识这三个工具

Claude Code：住在终端里的 AI 程序员

Claude Code 是 Anthropic 公司推出的命令行 AI 编程工具。和 ChatGPT 网页版或 Cursor 编辑器不同，Claude Code 工作在终端中——它能直接读取你的项目文件、理解代码结构、执行 shell 命令、写代码、跑测试、管理 Git。你可以让它自主完成"创建项目→写代码→跑测试→提交代码"的全流程，而不只是在聊天框里给你贴代码片段。

它很强，但也有上面说的那些问题：需求理解可能有偏差、不一定遵守工程纪律、决策不留痕。所以它需要搭档。

前提：需要 Claude 付费订阅（Pro / Max / Team / Enterprise 任一档都行）。具体价格会变，以 anthropic.com/pricing 为准。免费版不支持。

OpenSpec：把一句话需求变成四份标准文档

OpenSpec 是 Fission AI 团队开发的开源框架，专门解决场景一的问题。它的核心理念是"Spec-Driven Development"——在写任何代码之前，先把需求变成结构化的规范文档。

你说"我要一个用户登录功能"，OpenSpec 帮你展开成：

• proposal.md：为什么做、做什么、不做什么（Out of Scope 是最关键的部分——明确不做什么，才能防止 AI 自作主张）
• specs/：行为规格（每个功能用 GIVEN/WHEN/THEN 描述预期行为）
• design.md：技术选型和决策理由（选了什么、为什么选、放弃了什么）
• tasks.md：任务清单（拆成 2-5 分钟可完成的具体步骤）

OpenSpec 不绑定任何 AI 工具，支持 20+ 个编程助手。但和 Claude Code 配合效果最好，因为 Claude Code 的子代理能力可以按 tasks.md 并行执行任务。

Superpowers：给 AI 套上工程纪律的技能框架

Superpowers 是 Jesse Vincent 和 Prime Radiant 团队开发的开源技能框架（GitHub 14 万+ 星），专门解决场景二的问题。它不是独立工具，而是一组安装到 Claude Code 里的"技能"，让 Claude Code 自动遵循专业软件工程实践。

装上 Superpowers 后，Claude Code 会"变了个人"——不再收到需求就直接写代码。它有一组核心技能，而且关键的一点是规划类 skill 本身就会落盘持久化：brainstorming 会把设计文档保存到 docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md 并自动 commit；writing-plans 会把实施计划保存到 docs/superpowers/plans/YYYY-MM-DD-<feature>.md。所以网上常见的那句"Superpowers 关掉对话就全忘了"是错的——它真正缺的是 Delta/Archive 多迭代归档机制，不是"不持久化"。

单独使用 Superpowers 时 brainstorming 和 writing-plans 会自动触发；TDD、code-review 等编码纪律需要在 CLAUDE.md 里写明才会生效：

重要纠正：OpenSpec 和 Superpowers 是两套独立系统，不会自动串联。使用 /opsx:apply 实施任务时，Superpowers 的 TDD、code-review 等技能不会自动介入。如果你希望在 apply 过程中执行 TDD 等工程纪律，需要在项目的 CLAUDE.md 中明确写入规则，例如：使用 /opsx:apply 实施任务时，必须采用 TDD 方式：先写失败测试，再写实现代码。

两者结合使用时，规划阶段由 OpenSpec 主导，编码阶段由 Superpowers 主导，各管各的阶段：

OpenSpec 负责：              Superpowers 负责：
  想清楚做什么                  写代码时怎么做好
┌──────────┐               ┌──────────────┐
│ explore  │               │ brainstorming │ ← 同类职能，不同产物目录
│ propose  │               │ writing-plans │ ← 同类职能，不同产物目录
│ apply ───┼─────────────→ │ TDD          │ ← 需在 CLAUDE.md 中要求
│          │               │ debugging    │ ← 需在 CLAUDE.md 中要求
│          │               │ verification │ ← 需在 CLAUDE.md 中要求
│ archive  │               │ code-review  │ ← 需在 CLAUDE.md 中要求
└──────────┘               └──────────────┘

这两套规划系统职能重叠但不会自动互让——装了两个之后，你下一次发起新功能请求时 brainstorming 仍然会触发，除非你在 CLAUDE.md 里明确规定"新功能一律走 /opsx:propose，跳过 brainstorming / writing-plans"。没有这行规则，你会在一小时内同时得到 docs/superpowers/specs/ 下的一份 design doc 和 openspec/changes/<id>/ 下的一份 proposal，两边内容还会悄悄不同步。

把规划路由到 OpenSpec 之后，/opsx:apply 进入编码阶段，Superpowers 的 TDD、debugging、verification、code-review 依然不会自动介入——必须在 CLAUDE.md 里明确写：使用 /opsx:apply 实施任务时，必须采用 TDD：先写失败测试，再写实现。

如果你没用 OpenSpec，直接让 Claude Code 加功能，那 Superpowers 全程主导：brainstorming 先问清楚需求并落盘 design doc，writing-plans 拆任务并落盘 plan，然后 TDD 先写测试再写代码。

一句话总结：OpenSpec 管规划，Superpowers 管编码纪律，Claude Code 负责执行。两个装在同一个项目里完全不冲突，各管各的阶段。

第二层：装起来，让三件套能跑

认识完了，我们把它们装好。四步搞定，每步都有验证方法。

第 1 步：安装 Claude Code

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# 验证
claude --version
# 应该输出版本号，比如 2.1.41

第 2 步：安装 OpenSpec

需要 Node.js 20.19.0+（运行 node --version 检查）。

# 全局安装
npm install -g @fission-ai/openspec@latest

# 进入你的项目目录，初始化（会提示选择 AI 工具，选 Claude Code）
cd your-project
openspec init

初始化后项目多出一个 openspec/ 目录：

your-project/
├── openspec/
│   ├── specs/           # 当前系统规范
│   ├── changes/         # 进行中的变更
│   │   └── archive/     # 已完成的变更归档
│   └── AGENTS.md        # AI 自动读取的指令
└── ...（你的代码）

第 3 步：安装 Superpowers

Superpowers 装在 Claude Code 内部：

# 启动 Claude Code
claude

# 在交互界面中执行
> /plugin install superpowers@claude-plugins-official

下次启动看到 You have Superpowers 就说明装好了。

第 4 步：配置三者协同

在项目的 .claude/settings.json 中添加：

{
  "mcpServers": {
    "openspec": {
      "command": "npx",
      "args": ["-y", "@fission-ai/openspec-mcp"]
    }
  },
  "permissions": {
    "allow": [
      "Bash:openspec:*",
      "Bash:npm:*",
      "Bash:git:*"
    ]
  }
}

验证：启动 Claude Code，输入"帮我看看 OpenSpec 和 Superpowers 是否安装好了"。两个都正常的话，Claude Code 会告诉你它检测到了 OpenSpec 目录和 Superpowers 技能。

第三层：先跑一遍，感受全流程

装好了，先别急着理解原理——先让它跑起来，在体感中理解每个工具在干什么。我们做一个用户认证 API（Express + MongoDB + JWT），跟着命令走就行。

3.1 用 OpenSpec 把需求变成规范

claude
> /opsx:propose 用户认证 API，技术栈 Express + MongoDB + JWT。
> 功能：用户注册（用户名+邮箱+密码）、用户登录（返回 JWT Token）、
> 获取当前用户信息（需要鉴权）。
> 安全要求：密码 bcrypt 加密，私有接口 JWT 鉴权。

OpenSpec 会在 openspec/changes/user-auth/ 下生成四份文档。你要做的事：打开 proposal.md，看看 Out of Scope 部分——确认 AI 没有自作主张加"第三方登录"、“密码找回"等你没要的功能。

如果需要补充细节（比如密码长度限制），直接编辑 proposal.md / specs/ / design.md 这几个生成出来的 markdown 文件即可——core profile 里没有 refine/validate 这类独立命令，文件就是单一真相源，改完下次 /opsx:apply 会按新版本走。

这一步你获得了什么：一份结构化的、所有人都能看懂的开发蓝图。AI 后续的所有工作都基于这份蓝图，而不是基于你的一句话描述。

flowchart LR
    Req["一句话需求：
Express + MongoDB + JWT
做个用户认证 API"]
    Req --> Propose["/opsx:propose"]
    Propose --> P["proposal.md
为什么 · 做什么
不做什么"]
    Propose --> S["specs/
GIVEN / WHEN / THEN
行为规格"]
    Propose --> D["design.md
bcrypt vs argon2
JWT 过期时间 · ORM 选型"]
    Propose --> T["tasks.md
每个任务 2–5 分钟"]

    style Req fill:#2d3748,color:#fff
    style Propose fill:#018472,color:#fff
    style P fill:#1e4e8c,color:#fff
    style S fill:#1e4e8c,color:#fff
    style D fill:#1e4e8c,color:#fff
    style T fill:#1e4e8c,color:#fff

3.2 规划阶段已完成，进入编码纪律

还记得前面说的分工吗？规划阶段 OpenSpec 主导，编码阶段 Superpowers 主导。

上一步的 /opsx:propose 已经把需求探索和设计决策都做完了——密码用什么算法、JWT 过期时间、数据库 ORM 选择等等，都记录在了 design.md 里。这相当于 Superpowers 的 brainstorming 和 writing-plans 已经被 OpenSpec 覆盖了。

所以接下来进入 /opsx:apply 时，如果你在 CLAUDE.md 中配置了 TDD 等要求，Superpowers 的工程纪律就会在编码过程中生效：TDD（先写测试再写代码）、debugging（遇到问题系统化排查）、verification（完成前验证）、code-review（提交前审查代码质量）。注意：这些不是自动触发的，需要你在 CLAUDE.md 中明确要求。

这一步你获得了什么：所有设计决策都记录在 design.md 里，而且每次 change 完成后会归档到 openspec/changes/<change-id>/archive/。三轮迭代之后你还能看到"为什么 v1 选了 bcrypt、v2 改成了 argon2”——这是 Superpowers 单独使用做不到的（它只有最新版 design doc）。OpenSpec 的 Delta/Archive 机制才是真正闭环场景三的那个环节。

3.3 确认计划、让 AI 自动执行

Brainstorming 完成后，Superpowers 自动生成任务计划（tasks.md），类似这样：

## 任务 1：项目初始化（2 分钟）
- [ ] npm init，安装 express, mongoose, jsonwebtoken, bcryptjs, dotenv

## 任务 2：数据库连接（3 分钟）
- [ ] 创建 src/config/db.js，实现 MongoDB 连接

## 任务 3：用户模型（5 分钟）
- [ ] 创建 src/models/User.js，定义字段约束，实现密码加密钩子
- [ ] 编写单元测试

## 任务 4：鉴权中间件（3 分钟）
- [ ] 创建 src/middleware/auth.js，实现 JWT 验证

## 任务 5：API 路由（10 分钟）
- [ ] POST /api/register、POST /api/login、GET /api/user
- [ ] 编写集成测试

## 任务 6：项目入口（2 分钟）
- [ ] 创建 src/app.js，配置中间件、挂载路由、启动服务

花 5 分钟通读一遍，检查顺序是否合理、有没有遗漏。确认后输入：

> Plan 确认，开始执行

如果你在 CLAUDE.md 中要求了 TDD，Superpowers 会进入 subagent-driven-development 模式——为每个任务启动子代理，每个子代理都走 TDD 流程（先写测试，测试失败，再写实现，测试通过，做 Code Review）。你可以看到实时进度：

[Task 1/6] 项目初始化 ✓
[Task 2/6] 数据库连接
  ├─ 写测试 → 失败（RED）✓
  ├─ 写实现 → 通过（GREEN）✓
  ├─ Code Review → 通过 ✓
  └─ Git 提交 ✓
[Task 3/6] 用户模型 ...

这一步你获得了什么：AI 在隔离的 worktree 上（注意——worktree 来自 Superpowers 的 using-git-worktrees skill，不是 OpenSpec 自带；/opsx:apply 默认不会主动开 worktree，除非你在 CLAUDE.md 里要求）、按规范、走 TDD 在干活。搞砸了直接丢弃 worktree，主代码零污染。场景二的问题也解决了。

stateDiagram-v2
    [*] --> RED
    RED: 🔴 RED
先写一个会失败的测试
(此时还没有实现代码)
    GREEN: 🟢 GREEN
写刚好够让测试通过
的实现代码
    REFACTOR: 🔵 REFACTOR
测试保持绿，清理代码
    REVIEW: ✅ Code Review
Superpowers 自动审查

    RED --> GREEN: 测试运行并失败
    GREEN --> REFACTOR: 测试通过
    REFACTOR --> REVIEW: 没有回归
    REVIEW --> RED: 下一个任务
    REVIEW --> [*]: 任务列表完成

    note right of RED
      如果测试之前就有实现代码，
      Superpowers 会直接删掉
      —— 不是警告，是删除。
    end note

3.4 验证 + 归档

# 验证实现是否符合规范
> /opsx:verify
# 输出：所有任务完成，无 CRITICAL 问题

# 归档变更——千万别忘了这一步
> /opsx:archive

归档会把变更的规范合并到主规范中。忘了这一步，下次开发新功能时 AI 读取的还是旧规范，可能重复实现已有功能。

3.5 启动项目，验证成果

npm install
node src/app.js
# 输出：服务运行在端口 5000

# 测试注册
curl -X POST http://localhost:5000/api/register \
  -H "Content-Type: application/json" \
  -d '{"username":"testuser","email":"[email protected]","password":"123456"}'
# 返回：{"success":true,"data":{"id":"...","username":"testuser","email":"[email protected]"}}

到这里，从一句话需求到可运行的 API，全流程跑完了。你的工作是：确认需求 → 回答设计问题 → Review 计划 → 验证结果。核心代码由 AI 按规范生成。

flowchart LR
    U["你：
一句话
需求"] --> Propose
    subgraph OpenSpec
        Propose["/opsx:propose"] --> Artifacts["proposal / specs
design / tasks"]
    end
    subgraph Superpowers
        Artifacts --> Plan["tasks.md
复核"]
        Plan --> TDD["TDD 循环
(RED→GREEN→REVIEW)"]
    end
    subgraph ClaudeCode["Claude Code"]
        TDD --> Exec["改文件 · 跑测试 · git"]
    end
    Exec --> Archive["/opsx:archive
spec delta 合并"]
    Archive --> U

    style OpenSpec fill:#018472,color:#fff
    style Superpowers fill:#2b6cb0,color:#fff
    style ClaudeCode fill:#4a5568,color:#fff
    style U fill:#1a202c,color:#fff
    style Archive fill:#c05621,color:#fff

第四层：为什么 Claude Code + OpenSpec + Superpowers 互相独占，缺一个就断链

跑通了一遍，你可能会想：真有必要这么麻烦吗？不能只用 Claude Code？或者只用其中两个？

可以，但你会掉回前面说的那些坑里。先看一张表，搞清楚 OpenSpec 和 Superpowers 到底哪里重叠、哪里互补：

网上流传的"Superpowers 不持久化"是错的 —— 两套系统都落盘。真正的差异是 OpenSpec 独占两点：一是 Delta/Archive 多轮归档（每次 change 都是独立版本化目录，不会被下一次覆盖），二是自动作为 spec-of-truth 注入新会话（新开 Claude 时会自动读 openspec/AGENTS.md，不用你手动指路）。Superpowers 的 design doc 是 last-write-wins，而且必须你手动让 Claude 再读一次。这两条差异对"同一个功能反复迭代 3-4 次的团队场景"非常重要，对"一次性构建"则体感很弱。

理解了这张表，再看每种组合缺什么就很清楚了。

quadrantChart
    title 四种组合分别落在哪个象限
    x-axis "纪律弱" --> "纪律强"
    y-axis "记忆短" --> "记忆持久"
    quadrant-1 "三件套 ✅"
    quadrant-2 "OpenSpec + Claude Code"
    quadrant-3 "只有 Claude Code"
    quadrant-4 "Superpowers + Claude Code"
    "只用 Claude Code": [0.18, 0.15]
    "加 Superpowers": [0.78, 0.22]
    "加 OpenSpec": [0.22, 0.80]
    "三件套": [0.82, 0.86]

只用 Claude Code：快但乱

开发速度最快，但没有规范约束。一位开发者的实际经历是：团队里不同人用 Claude Code 生成的代码，有的接口返回 {code: 200, data: ...}，有的返回 {success: true, result: ...}——前端对接时每个接口都要单独适配，痛苦至极。更严重的是，有人忘了给密码加密、有人忘了给私有接口加鉴权，这些安全问题要到测试甚至上线后才暴露。

OpenSpec + Claude Code（缺 Superpowers）：有蓝图但没工头

你的规范写得再好，Claude Code 在执行过程中可能"自由发挥"偏离规范。没有在 CLAUDE.md 中要求 TDD、没有要求 Code Review、没有 Worktree 隔离——规范和实现之间缺少一个"执法者"。相当于画了完美的建筑图纸，但施工队不按图施工，你又没有监理。

Superpowers + Claude Code（缺 OpenSpec）：有纪律但记忆短

TDD 和 Code Review 保证质量，而且设计文档和任务计划确实会落盘（docs/superpowers/specs/ 和 docs/superpowers/plans/）。真正缺的是 Delta/Archive 这一层——下一次 brainstorming 会直接覆盖上一次的 design doc，不是版本化归档。三轮迭代之后，你已经无法重建"最初那版设计为什么做了那个权衡"。一次性交付的个人项目不是问题；同一个功能要迭代三四轮的团队项目就会咬人。

三者组合：蓝图 + 监理 + 施工队

OpenSpec（需求层）→ Superpowers（纪律层）→ Claude Code（执行层）
   │                    │                      │
   ├─ proposal.md       ├─ Brainstorming       ├─ 写代码
   ├─ specs/            ├─ TDD 强制            ├─ 跑测试
   ├─ design.md         ├─ Code Review         ├─ Git 操作
   └─ tasks.md          └─ Subagent 并行       └─ 安装依赖

OpenSpec 把需求锚定成可追溯的文档 → Superpowers 确保 AI 按文档执行且有质量保障 → Claude Code 高效落地代码。形成"规范 → 执行 → 验证 → 归档"的闭环。三个工具各管一层，任何一层缺失，这个闭环就断了。

这里有个很多人忽略的关键设计：OpenSpec 刻意把每份 spec 文件控制在 200-300 行（比对标工具 Spec Kit 明显更轻）。这不是功能缺失——是刻意控制长度。规范太长没人会读，AI 也会在里面丢失上下文。正确的 Spec 描述行为，不描述实现：

# 正确：描述行为
需求：用户登录
- GIVEN 有效凭证
- WHEN 提交登录表单
- THEN 返回 JWT Token

# 错误：描述实现
实现 login 函数：
1. 导入 bcrypt
2. 调用 bcrypt.compare
3. 如果成功，调用 jwt.sign

Spec 管的是"要什么结果"，不管"怎么写代码"。后者是 Superpowers + Claude Code 的事。

另一个反直觉的设计在 Superpowers 这边：它的 TDD 技能会删除在测试之前写的代码。不是警告你，是直接删掉。这看起来激进，但解决了一个真实问题——AI 总是先写实现再补测试，补出来的测试只是在"验证代码确实是这么写的"而不是"验证代码确实做了该做的事"。

第五层：更大的案例——看三件套的上限在哪

前面的用户认证 API 是"新手体验版"，下面看两个更大的案例，展示三件套在复杂项目中的真实表现。

案例一：一天内搭完一个博客系统

需求：用 Next.js + PostgreSQL 搭一个技术博客，要有认证、文章 CRUD、Markdown 渲染、评论功能。目标一天完成。

工作流分成四个独立的 OpenSpec 变更并行推进：

9:00-11:35   用户认证（6 个任务）→ archive
11:35-13:30  文章管理（8 个任务）→ archive
14:30-16:00  Markdown 渲染（4 个任务）→ archive
16:00-18:00  评论功能（7 个任务）→ archive

最终产出：约 2500 行代码、87% 测试覆盖率、23 个 Git 提交、上线后一周零 Bug。

时间分配值得关注：需求对齐占 19%，设计规划占 13%，代码执行占 56%，验证修复占 12%。 三分之一的时间花在"写代码之前"——但正是这三分之一，让剩下三分之二的执行时间几乎没有返工。这是很多人不理解的地方：前期花时间对齐需求和设计，不是在浪费时间，而是在提前消灭返工。

案例二：支付收银台——审查发现 11 个问题

一位开发者用三件套从零构建一个支付收银台演示项目（React + FastAPI + MySQL），这个案例最能体现规范审查的价值。

他用 /opsx:propose 一条指令生成了全套规范文档，然后用 Superpowers 的 Brainstorming 从架构师、测试工程师、开发工程师三个视角审查。结果在一行代码都没写之前，就发现了 11 个问题：

• 高优先级：缺少按订单号查询的接口（前端没法查订单）、API 缺少参数验证（任何人都能注入非法数据）
• 中优先级：依赖列表不完整、数据库缺索引（查询会很慢）
• 低优先级：未明确单用户演示模式、缺少测试数据准备步骤

如果这些问题是在代码写完后才发现，修复成本至少是现在的 5-10 倍。通过一轮审查 + 自动修复，任务从 50+ 个扩展到 74 个，覆盖了所有遗漏。最终核心功能 100% 可用，13 个任务组、74 个具体任务，只剩部署工作没做。

这个案例的关键启示：三件套的价值不仅在于"帮你写代码"，更在于"帮你在写代码之前发现你自己都没想到的问题"。这是纯用 Claude Code 做不到的——因为 Claude Code 收到需求就开始写了，它不会停下来三个视角审查你的需求是否完整。

第六层：什么时候不该上 Claude Code + OpenSpec + Superpowers 全套

flowchart TD
    Start["新任务来了"] --> Dur{"预估工时？"}
    Dur -->|< 2h 原型| Solo["只用 Claude Code
不写 spec 不跑 TDD"]
    Dur -->|2–8h 个人| Pair["Claude Code +
Superpowers
TDD + worktree"]
    Dur -->|4–16h 团队| Team{"团队协作 /
长期维护？"}
    Dur -->|大型 / 多特性并行| Full["三件套 +
并行 worktree"]

    Team -->|是| Full
    Team -->|否| Pair

    Solo --> Risk1{"要上生产？"}
    Risk1 -->|是| Pair
    Risk1 -->|否，一次性脚本| Solo

    style Solo fill:#4a5568,color:#fff
    style Pair fill:#2b6cb0,color:#fff
    style Full fill:#018472,color:#fff
    style Start fill:#1a202c,color:#fff

到这里，你可能已经对三件套很有好感了。但我必须泼一盆冷水：不是所有项目都适合上全套。过度工程化和工程化不足一样有害。

我的建议是从 Claude Code + Superpowers 两件套开始，不要一上来就三件套全上。Superpowers 的 TDD 和 Code Review 对任何项目都有价值，而 OpenSpec 只在"需要团队协作或长期维护"的场景下才能体现优势。先用两件套养成工程纪律的习惯，等你觉得"决策追溯"成了真实瓶颈时再加 OpenSpec——那时候你会自然理解它的价值。

容易踩的 5 个坑

坑 1：Spec 写成了伪代码。 Spec 描述行为（GIVEN/WHEN/THEN），不描述实现（导入什么模块、调用什么函数）。写太细会限制 AI 的实现选择空间，更新成本极高。

坑 2：完成后忘了 archive。 这是我自己踩过的坑。做完功能兴奋地开始下一个，忘了 /opsx:archive。下次开新会话，AI 读取的还是旧规范，把已经实现的功能又做了一遍。养成习惯：每个功能完成后，archive 是最后一个动作。

坑 3：跳过 Brainstorming。 Superpowers 的 Brainstorming 不是闲聊——它在帮你和 AI 对齐技术决策。跳过这步，AI 会基于自己的猜测选技术方案，你到 Review 代码时才发现方向不对，修改成本已经很高了。

坑 4：不看 Plan 就确认执行。 花 5 分钟通读 tasks.md。检查任务顺序是否合理（JWT 工具函数应该在登录 API 之前）、有没有遗漏、验收标准是否清晰。这 5 分钟能省 1-2 小时返工。

坑 5：30 分钟的需求上全套流程。 propose→brainstorm→plan→execute→verify→archive 全走完可能要 2 小时。工具服务于目标，不是目标服务于工具。

速查参考

命令速查表

Core Profile（默认）：

最简流程：propose → apply → archive。explore 按需使用。

注意：网上一些文章提到的 /opsx:refine、/opsx:validate、/opsx:ff 等命令不在默认的 core profile 中。如需使用 verify、sync、continue 等扩展命令，需要通过 openspec config profile 切换到 expanded profile，再运行 openspec update 安装额外的 skill 文件。对大多数场景，core 的四个命令就够了。如果想修改已生成的 proposal.md、design.md、tasks.md，直接编辑文件即可，不需要专门的 refine 命令。

新手上手路线图

第 1 周：只用 Claude Code
  → 熟悉终端中与 AI 协作的感觉

第 2 周：加上 Superpowers
  → 体验 TDD、Code Review、Worktree 的价值
  → 感受"有纪律的 AI"和"没纪律的 AI"的区别

第 3 周起：按需加入 OpenSpec
  → 当你发现"每次都要重复解释需求"或"团队里其他人看不懂我的代码逻辑"
  → 就是引入 OpenSpec 的时机

最终判断

这套组合的本质，是把人类工程师的最佳实践（需求对齐、TDD、Code Review、决策记录）编码成 AI 必须遵守的规则。不是让 AI 自由发挥，而是让 AI 在约束下创造。

但请记住三点：

1. 从小开始。Claude Code → 加 Superpowers → 按需加 OpenSpec。不要第一天就全套上。
2. 工具不能替代判断。AI 生成的代码你必须能读懂、能 Review、能识别问题。工具提升的是效率，不是能力。
3. 不要让流程成为枷锁。30 分钟的任务不需要全套流程，快速原型不需要写 Spec。灵活选择合适的组合，才是真正的工程成熟度。

三者协同的终极目标不是"让 AI 帮你写更多代码"，而是让 AI 写的代码像人类工程师写的一样可靠、可维护、可追溯。这个目标是否值得额外的工具投入，取决于你的项目规模和团队需求——现在你有了做判断的框架，也有了上手实操的路径。

Related Reading:

• Superpowers 深度解析：让 Claude Code 变身高级工程师的技能框架
• CLAUDE.md 终极指南：把 AI 助手训练成你的理想同事
• Harness Engineering：不换模型，只改 Harness 就能大幅提升 AI Agent 效果
• Claude Code 完全指南：从入门到精通