本文说明如何在 Claude Code 中同时使用 Superpowers（代理工作流与技能体系）与 OpenSpec（结构化规范与变更管理），形成「规范驱动 + 纪律执行 + 可追溯归档」的闭环。
一、Superpowers 简介
Superpowers 是一套面向编码代理的完整软件开发工作流：基于可组合的「技能（Skills）」与初始指令，让代理在动手写代码前先理解目标、产出可审阅的设计与可执行的计划，并在实现阶段强制执行测试驱动、代码审查等工程纪律。
1.1 核心理念
- 不急于写代码：一旦识别到你在「做东西」，代理会先厘清真实意图，再从对话中提炼出规格。
- 分块确认设计：将规格拆成足够短的段落供你阅读与消化，确认后再进入实现。
- 计划可交给他人执行：在你说「开始」后，生成足够清晰的实现计划，强调真正的红 / 绿 TDD、YAGNI、DRY。
- 子代理驱动开发：可启动 subagent-driven-development，按工程任务推进、检查与评审，在既定计划下长时间自主工作而不跑偏。
- 技能自动触发：安装插件后，相关技能会在合适时机被调用，无需你记忆每条规则。
1.2 功能概览
| 能力 | 说明 |
|---|---|
| 设计前置 | 通过对话把想法变成经你签字的设计，再写代码。 |
| 实现计划 | 将设计拆成带路径、步骤、验证方式的任务。 |
| 子代理 / 分批执行 | 多任务并行或分批执行，带审查与检查点。 |
| TDD 与审查 | 测试先行、系统性调试、完成前验证。 |
| 分支收尾 | 工作区隔离（worktree）、合并 /PR 决策与清理。 |
1.3 安装
- 官方插件市场：
/plugin install superpowers@claude-plugins-official - 自定义市场：先
/plugin marketplace add obra/superpowers-marketplace，再/plugin install superpowers@superpowers-marketplace - 更新：
/plugin update superpowers - 验证：新会话中提出会触发技能的需求（例如「帮我规划这个功能」），代理应自动调用对应 Superpowers 技能。
1.4 基本工作流
- brainstorming — 写代码前激活；用问答澄清想法、对比方案、分节呈现设计并保存设计文档。
- using-git-worktrees — 设计批准后；在新分支上创建隔离工作区、跑项目初始化、确认干净测试基线。
- writing-plans — 有已批准设计后；拆成小块任务（约 2–5 分钟级），含明确文件路径、代码要点、验证步骤。
- subagent-driven-development / executing-plans — 有计划后；每任务派生子代理，两阶段审查（符合规格 → 代码质量），或分批执行与人机检查点。
- test-driven-development — 实现中；红 - 绿 - 重构，先写失败测试、见红、写最小实现、见绿、提交；禁止测试前写实现代码。
- requesting-code-review — 任务间；对照计划审查，按严重程度报告问题，严重问题阻塞继续。
- finishing-a-development-branch — 任务完成后；跑测试、给出合并 /PR/ 保留 / 丢弃等选项并清理 worktree。
说明 ：代理在执行任务前会检查相关技能；这些流程是 强制性工作流，不是可选建议。
1.5 Superpowers Skills 详解
测试
- test-driven-development：红 - 绿 - 重构循环（含测试反模式参考）。
调试
- systematic-debugging：四阶段根因分析（含根因追踪、纵深防御、基于条件的等待等）。
- verification-before-completion：在宣称完成前验证确实修好了。
协作
- brainstorming：苏格拉底式设计澄清。
- writing-plans：详细实现计划。
- executing-plans：带检查点的分批执行。
- dispatching-parallel-agents：并发子代理工作流。
- requesting-code-review：评审前检查清单。
- receiving-code-review：处理评审意见（先核实再改）。
- using-git-worktrees：并行开发分支隔离。
- finishing-a-development-branch：合并与收尾决策。
- subagent-driven-development：快速迭代 + 两阶段审查。
元能力
- writing-skills：按规范编写与测试新技能。
- using-superpowers：技能体系入门。
1.6 哲学与使用场景
哲学
- 测试驱动开发：先写测试。
- 系统性优于随意：流程优于猜。
- 降低复杂度：简单优先。
- 证据优于断言：宣称成功前先验证。
典型使用场景
- 新功能从 0 到 1：先设计、再计划、再 TDD 实现。
- 复杂缺陷：用 systematic-debugging 与 verification-before-completion。
- 多人 / 多代理协作：worktree + subagent-driven-development + code review。
- 长期可维护：计划与审查强制对齐规格与质量。
延伸阅读：Superpowers for Claude Code。
二、OpenSpec 简介
OpenSpec 帮助你和 AI 在 写任何代码之前 就对「要构建什么」达成一致，并把约定落在仓库里的结构化工件（artifacts）中。
2.1 功能概览
| 维度 | 说明 |
|---|---|
| 规范即事实 | openspec/specs/ 描述系统 当前 行为，按领域组织（如 auth/）。 |
| 变更隔离 | openspec/changes/<change-name>/ 承载单次变更的 proposal、delta specs、design、tasks。 |
| Delta 规格 | 用 ADDED/MODIFIED/REMOVED 等区块表达相对主规格的增量，归档时再合并进主规格。 |
| 动作非阶段 | OPSX 强调可执行的命令（propose、apply、archive 等），而非锁死的线性阶段。 |
2.2 初始化后目录结构（openspec init 之后）
1 | openspec/ |
2.3 工件（Artifacts）说明
| 工件 | 作用 |
|---|---|
proposal.md |
为什么做、做什么、范围与思路。 |
specs/（delta） |
相对主规格的增删改需求与场景。 |
design.md |
怎么做：技术与架构决策。 |
tasks.md |
可勾选的实现清单。 |
依赖关系可概括为：proposal → specs → design → tasks → implement，实现过程中可回头修订上游工件。
2.4 两种路径：默认（core）与扩展
默认 core 配置（全局 profile 常为 core）：
1 | /opsx:propose ──► /opsx:apply ──► /opsx:archive |
另含 /opsx:explore（先探索再立项）。
扩展工作流（需 openspec config profile 选择工作流后执行 openspec update）：
1 | /opsx:new ──► /opsx:ff 或 /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive |
并可使用 /opsx:sync、/opsx:bulk-archive、/opsx:onboard 等。
2.5 slash 命令速览（Claude Code 内）
core
| 命令 | 作用 |
|---|---|
/opsx:propose |
创建变更并一次性生成规划工件，直到可 /opsx:apply。 |
/opsx:explore |
在承诺变更前探索想法、调研代码、对比方案。 |
/opsx:apply |
按 tasks.md 实现并勾选任务。 |
/opsx:archive |
归档完成项，合并 delta 到主规格（并提示 sync）。 |
扩展（节选）
| 命令 | 作用 |
|---|---|
/opsx:new |
新建变更脚手架，再等 continue 或 ff。 |
/opsx:continue |
按依赖链每次生成下一个工件。 |
/opsx:ff |
快进生成全部规划工件。 |
/opsx:verify |
从完整性、正确性、一致性三方面对照工件检查实现。 |
/opsx:sync |
将 delta 合并进主规格（不归档；归档时也会提示）。 |
/opsx:bulk-archive |
批量归档多个变更并处理规格冲突。 |
/opsx:onboard |
引导式走完一轮真实工作流。 |
工具差异：Claude Code 常用 /opsx:propose 形式；部分 IDE 使用 /opsx-propose 等变体，语义一致（见 commands.md）。
2.6 CLI 要点
与聊天命令互补，常用于人类与脚本 / 代理：
| 类别 | 命令 | 用途 |
|---|---|---|
| 安装 | openspec init |
初始化目录与工具集成（可加 --tools claude 等）。 |
| 更新 | openspec update |
升级 CLI 后重生成 AI 侧配置。 |
| 浏览 | openspec list、openspec show、openspec view |
列出 / 查看变更与规格。 |
| 校验 | openspec validate |
校验工件结构（可 --all --json 供 CI）。 |
| 工作流 | openspec status、openspec instructions |
查看工件进度与下一步指令（支持 --json）。 |
| 归档 | openspec archive |
命令行归档（可 --yes、--skip-specs 等）。 |
| 配置 | openspec config profile |
调整全局 profile 与工作流，再 openspec update 同步到项目。 |
2.7 典型使用场景
- 快速功能：已知需求 →
propose（或new+ff）→apply→verify（扩展）→archive。 - 需求不清：先
/opsx:explore，再propose/new。 - 并行变更：多个
changes并行；完成后bulk-archive处理多变更与规格合并顺序。 - 归档前自检：
/opsx:verify检查任务是否完成、需求是否落地、设计是否与代码一致。
三、Superpowers 与 OpenSpec 协同工作流闭环
两者分工可概括为：
| 角色 | 承担者 | 含义 |
|---|---|---|
| 定方向 | OpenSpec | 把需求变成结构化规范（proposal、delta specs、design、tasks），openspec/specs/ 作为仓库内 唯一事实源 的长期载体；变更期以 openspec/changes/... 为当前迭代的真相。 |
| 保执行 | Superpowers | 严格按已写明的规格与任务落地；通过 brainstorming → writing-plans → TDD → code review → verification-before-completion 等技能 强制执行工程纪律。 |
| 管结果 | OpenSpec | 实现完成后 archive（及可选 verify、sync），把 delta 合并进主规格，变更目录进入 archive/，形成 可追溯、可审计 的迭代闭环。 |
闭环示意
1 | [OpenSpec 定方向] |
实践要点
- 单一事实源：实现时以 OpenSpec 工件的「需求与场景」为准；Superpowers 的计划应引用或对应
tasks.md与规格中的 Scenario。 - 先规格后红绿：OpenSpec 把「做什么」说清；Superpowers TDD 把「怎么证明做对」落实。
- 漂移即修文档：若实现中发现规格不合理，先改
proposal/specs/design/tasks，再改代码，保持闭环一致。 - 完成定义：除代码与测试外，包含「已 archive、主规格已反映行为」才算迭代完成。
四、案例：登录功能 — Superpowers + OpenSpec 协同
以下按 时间顺序 走通「邮箱 + 密码登录」端到端案例。假设为常见 Web 应用（Node/Express、Next.js、Rails 等均可类比）。Claude Code 使用 /opsx:...；终端 命令为 CLI。
变更名 ：add-email-password-login
变更目录：openspec/changes/add-email-password-login/（下文简称「变更目录」）。
4.0 前置条件
| 检查项 | 建议做法 | 作用 |
|---|---|---|
| Superpowers 已装 | /plugin install superpowers@claude-plugins-official（或你环境里的市场路径） |
否则 brainstorming / TDD / review 等纪律不会稳定触发。 |
| OpenSpec CLI 可用 | 终端：openspec --version |
无 CLI 则无法 init、校验、归档。 |
| 仓库状态清晰 | git status 无意外未提交改动，或先提交 / 暂存 |
using-git-worktrees 与合并时减少干扰。 |
| 需求粗范围已定 | 若「是否 OAuth / 2FA / 仅 API 无 UI」完全未决 | 先做 4.1.3 的 explore，避免反复改 delta specs。 |
4.1 阶段一：仓库接入 OpenSpec
4.1.1 初始化
| 步骤 | 命令 / 操作 | 作用 |
|---|---|---|
| 1 | 在项目根目录终端：openspec init |
生成 openspec/specs/、openspec/changes/、可选 openspec/config.yaml；按提示勾选 Claude 时写入 .claude/skills/ 等，聊天里才能稳定识别 /opsx:*。 |
| 2 | （可选）非交互：openspec init --tools claude --force |
脚本 /CI 初始化；--force 会处理遗留文件，用前确认无重要未备份改动。 |
| 3 | openspec list |
确认 CLI 与路径正确（通常尚无活动变更）。 |
4.1.2（可选）启用扩展工作流
需要 /opsx:new、/opsx:ff、/opsx:verify、/opsx:sync 时：
| 步骤 | 命令 | 作用 |
|---|---|---|
| 1 | openspec config profile |
交互式勾选扩展工作流；默认 core 仅有 propose / explore / apply / archive。 |
| 2 | openspec update |
把全局 profile 同步到 当前项目 的 AI 指令与命令文件。 |
| 3 | 新开或重启 Claude Code 会话 | 确保新 slash 命令被加载。 |
4.1.3（可选）需求不清时先探索
| 步骤 | 命令 | 作用 |
|---|---|---|
| 1 | /opsx:explore |
不创建变更工件；代理可读代码、对比 Session vs JWT、登录错误是否防枚举、速率限制放哪一层等。 |
| 2 | 对话收敛后，再进入 4.2 | 减少 proposal / specs 的大幅返工。 |
4.2 阶段二：OpenSpec 定方向
4.2.1 路径 A — core：一条命令生成全套规划工件
| 步骤 | 命令 | 作用 |
|---|---|---|
| 1 | /opsx:propose add-email-password-login |
创建变更目录，并生成 proposal.md、delta specs/**/spec.md、design.md、tasks.md。 |
| 2 | openspec status --change add-email-password-login |
查看 proposal / specs / design / tasks 是否齐全；加 --json 便于代理解析。 |
4.2.2 路径 B — 扩展：脚手架后分步或快进
| 步骤 | 命令 | 作用 |
|---|---|---|
| 1 | /opsx:new add-email-password-login |
只建变更目录与元数据（如 .openspec.yaml），工件未一次性填满。 |
| 2a | 多次 /opsx:continue（可带变更名） |
每次 只生成下一个 工件：通常 proposal → specs → design → tasks；每步可手改文件再继续。 |
| 2b | /opsx:ff add-email-password-login |
快进 生成与 propose 等价的全部规划工件，适合范围已非常清晰时。 |
4.2.3 生成后目录
1 | openspec/changes/add-email-password-login/ |
4.2.4 人工审阅清单（通过后再写代码）
对 proposal.md：
- Intent：为何需要邮箱密码登录（新用户入口、与现有 IdP 关系）。
- Scope：是否包含注册、忘记密码、邮件验证；明确 Out of scope（如本变更不做 OAuth、不做 2FA）。
对 delta specs（如 specs/auth/spec.md）：
- 每条 Requirement 下是否有可验收的 Scenario（Given / When / Then）。
- 至少覆盖：成功登录；密码错误；邮箱不存在（若产品要求与密码错误「同文案」防枚举，必须在 scenario 写死）。
- 若规格包含：速率限制、账户锁定、「记住我」、会话时长，各对应 scenario。
对 design.md：
- 路由与方法（如
POST /api/auth/login）、请求 / 响应 JSON 形状、成功与失败 HTTP 状态码。 - 密码哈希（如 bcrypt 与 cost）、会话（cookie 名、HttpOnly、Secure、SameSite）、CSRF（若用 cookie 会话）。
- 与现有用户表 / 迁移的关系；环境变量（如
SESSION_SECRET）。
对 tasks.md：
- 任务顺序是否合理（先后端契约 / 集成测试再 UI 等）。
- 编号是否稳定，便于 writing-plans 逐步引用。
4.2.5 示例：delta 规格片段（形态参考；以代理生成为准）
1 | ## ADDED Requirements |
4.2.6 校验
| 命令 | 作用 |
|---|---|
openspec validate add-email-password-login |
检查工件结构与 delta 格式。 |
openspec show add-email-password-login |
人类通读摘要；测试管线可加 --json。 |
审阅中若修改了 specs 或 tasks，应再次 validate 直至无阻塞问题。
4.3 阶段三：Superpowers 保执行（与 OpenSpec 对齐）
本阶段 不替代 /opsx:apply，而是把工程纪律钉在仓库里的工件上。
4.3.1 建议顺序与对话示例
| 顺序 | 技能 | 你可以在聊天里这样说（示例） | 作用 |
|---|---|---|---|
| 1 | brainstorming | 「请对照 openspec/changes/add-email-password-login/proposal.md 和 delta specs，用 brainstorming 流程列出遗漏场景；先不要写代码。」 |
口头需求与仓库 唯一事实源 对齐。 |
| 2 | using-git-worktrees | 「为本变更建 worktree，分支名 feat/email-password-login，并确认测试基线通过。」 |
隔离开发，便于 finishing-a-development-branch 收尾。 |
| 3 | writing-plans | 「OpenSpec 已有 tasks.md（路径如上）。请生成与任务编号一一对应的实现计划，每条写明文件路径与要跑的测试命令。」 |
计划与 tasks.md 勾选粒度一致，便于审计。 |
| 4 | test-driven-development + 后续 apply | 见 4.4 | 红 - 绿 - 重构；/opsx:apply 负责按清单推进并勾选。 |
| 5 | requesting-code-review | 「对照 delta specs 的每个 Scenario 和 design.md 做 review；严重问题先修再继续下一组任务。」 |
防止实现偏离规格。 |
| 6 | verification-before-completion | 「宣称完成前：跑全量相关测试，并列出每个 Scenario 对应的测试或手动检查步骤。」 | 有证据再交付。 |
4.3.2 建议粘贴给代理的约束
1 | 实现范围仅限 openspec/changes/add-email-password-login/ 下的 proposal、delta specs、design、tasks。 |
4.3.3 tasks.md 拆分示例（理解 TDD 如何逐项落地）
1 | # Tasks |
每个 checkbox 建议遵循：写测（红）→ 最小实现（绿）→ 重构 → 勾任务。
4.4 阶段四：实现与勾选（/opsx:apply + TDD）
4.4.1 启动与续跑
| 步骤 | 命令 | 作用 |
|---|---|---|
| 1 | /opsx:apply add-email-password-login |
读 tasks.md，逐项实现并勾选；会话中断后可 再次 带同名变更执行以续跑。 |
| 2 | openspec instructions apply --change add-email-password-login |
终端输出「下一步实现」的增强指令（含依赖工件），可粘贴进对话。 |
4.4.2 单个 checkbox 的微观步骤（建议每个任务重复）
- 在 delta specs 中定位对应 Scenario，确定断言（状态码、Set-Cookie、
Set-Cookie属性、JSON 字段）。 - 编写自动化测试（项目惯例：单元、集成或 E2E）；运行，确认 失败 且失败原因符合预期（真红）。
- 写最少生产代码使测试通过；避免先写大量实现再补测（违反 Superpowers TDD）。
- 跑相关测试与 lint；通过后把
tasks.md该项改为[x]。 - 每完成一组相关任务，可再触发 requesting-code-review。
4.4.3 实现中发现规格与代码不一致时
| 情况 | 操作 |
|---|---|
| 仅实现细节（文件名、拆分模块） | 直接改代码。 |
| 行为与 delta specs 或 design 冲突 | 先 改 specs/**/spec.md、design.md 或 tasks.md，执行 openspec validate，再改代码并固定测试。 |
4.5 阶段五：OpenSpec 管结果（verify、sync、archive）
4.5.1（扩展 profile）归档前验证
| 步骤 | 命令 | 作用 |
|---|---|---|
| 1 | /opsx:verify add-email-password-login |
完整性 ：tasks 是否全勾、需求是否像都已落地； 正确性 ：scenario 与行为； 一致性：design 中的模块 / 命名是否在代码中体现。 |
| 2 | 处理报告中的 CRITICAL；WARNING 可当场修或记债。 | verify 不阻止 archive，但应避免带着已知严重偏差关闭变更。 |
4.5.2（可选）提前合并 delta 到主规格
| 命令 | 何时用 | 作用 |
|---|---|---|
/opsx:sync add-email-password-login |
长周期变更、或并行变更需要他人基于 已更新 主 specs 开发 | 合并 ADDED/MODIFIED/REMOVED 到 openspec/specs/，变更目录 仍在，未归档。 |
小功能多数可直接在 archive 时合并，无需单独 sync。
4.5.3 归档
| 步骤 | 命令 | 作用 |
|---|---|---|
| 1 | /opsx:archive add-email-password-login |
检查工件与任务；提示是否 sync；确认后将变更移到 openspec/changes/archive/YYYY-MM-DD-add-email-password-login/。 |
| 2 | openspec archive add-email-password-login |
CLI 归档；脚本可加 --yes；纯工具变更才考虑 --skip-specs（登录功能一般 不要 skip）。 |
4.5.4 归档后自检
| 命令 | 作用 |
|---|---|
openspec list |
活动变更中不应再出现本变更名。 |
打开 openspec/specs/auth/spec.md（或你的领域路径） |
确认 ADDED 内容已并入主规格。 |
openspec validate --all |
全仓库规格与变更结构仍合法。 |
4.6 阶段六：Superpowers 收尾（合并与清理）
| 步骤 | 技能 / 动作 | 作用 |
|---|---|---|
| 1 | finishing-a-development-branch | 在 worktree 上跑全量测试，选择 merge 或开 PR，清理 worktree。 |
| 2 | verification-before-completion | 合并前最后一次对照关键 scenario（CI + 必要时手动登录）。 |
4.7 完整命令与时间线速查
1 | # --- 一次性（仓库接入）--- |
4.8 常见问题
| 现象 | 可能原因 | 建议 |
|---|---|---|
/opsx:apply 找不到变更 |
当前目录不是项目根或未 init | cd 到根目录；openspec list 核对名称。 |
| 实现与 specs 不一致 | 代理未以变更目录为准 | 粘贴 4.3.2 约束语；评审时逐条对照 Scenario。 |
| tasks 全勾但 verify 警告未测场景 | 测试未映射到需求 | 在测试中注释 requirement/scenario id，或补测。 |
| 多人改同一领域 spec | 并行变更冲突 | 不同 change-name；完成后用 bulk-archive 按提示顺序合并。 |
五、结语
- OpenSpec 解决「我们约定了什么、变更如何进主规格、如何追溯」。
- Superpowers 解决「如何不跳步、如何测试先行、如何审查与验证再交付」。
- 二者叠加时：规格在仓库里 ， 纪律在技能链上 ， 结果在 archive 与主 specs 里——适合在 Claude Code 中长期、可审计地迭代功能（如登录、权限、支付等）。