Superpowers 实战教程：单体服务 vs 微服务多仓库
Superpowers（obra / Jesse Vincent）不是又一个 slash command 工具，而是一套 强制工程纪律的 Skills 方法论 。
Agent 不再「想到哪写到哪」，而是自动走：先设计 → 写计划 → TDD 实施 → 两阶段 Review → 证据验证 。
本文是可照着做的详细教程，区分 单体服务（单仓库） 与 微服务多仓库 两种落地形态。
目录
- [Superpowers 是什么](#Superpowers 是什么)
- [核心概念：Skills 与工作流](#核心概念：Skills 与工作流)
- [安装与验证（以 Cursor 为主）](#安装与验证（以 Cursor 为主）)
- 场景一：单体服务（单仓库）
- 场景二：微服务多仓库
- 两种场景对比与选型
- [与 OpenSpec / Spec Kit / AGENTS.md 的配合](#与 OpenSpec / Spec Kit / AGENTS.md 的配合)
- [Skills 速查表](#Skills 速查表)
- 常见问题
- 参考链接
1. Superpowers 是什么
Superpowers 是一套 agentic skills framework + 软件开发方法论 。核心载体是 SKILL.md 文件：Agent 在会话中 自动检测上下文并强制遵循，不是可选建议。
解决什么问题
| 痛点 | Superpowers 的做法 |
|---|---|
| Agent 一听需求就写代码 | brainstorming 硬门禁：先设计、等你 approve |
| 不写测试、先写实现 | test-driven-development：RED-GREEN-REFACTOR 铁律 |
| 猜一下改一下的调试 | systematic-debugging：四阶段根因分析 |
| 长任务跑偏、上下文污染 | subagent-driven-development：每 task 新 subagent + 两阶段 review |
| 「应该好了」式虚假完成 | verification-before-completion：先跑命令、再看输出、再宣称完成 |
| 在 main 上乱改 | using-git-worktrees：隔离 worktree + 测试基线 |
与 OpenSpec / Spec Kit 的定位差异
| OpenSpec / Spec Kit | Superpowers | |
|---|---|---|
| 核心问题 | 做什么（规范、计划工件） | 怎么做（过程纪律） |
| 交互 | Slash commands | 自动触发 Skills |
| 活文档 | 强（specs 库） | 弱（docs/plans/ 设计/计划） |
| TDD | 不强制 | 硬门禁 |
| 子 Agent | 不内置 | subagent-driven-development |
| 多仓库 | Store / platform-docs | 每环境独立安装，人工编排 |
三者可组合：OpenSpec/Spec Kit 管「对齐与工件」，Superpowers 管「实施纪律」。
四大原则
- Test-Driven Development --- 先写失败测试
- Systematic over ad-hoc --- 流程优于猜测
- Complexity reduction --- YAGNI，简单优先
- Evidence over claims --- 验证优于宣称
2. 核心概念：Skills 与工作流
2.1 Skills 如何工作
using-superpowers 是根基技能，会话启动时加载，规定：
只要有 1% 可能适用某个 skill，就必须加载并遵循------不是建议，是强制。
Agent 应宣布：Using [skill] to [purpose]。
技能优先级：
- 过程类 （brainstorming、systematic-debugging）--- 决定 HOW
- 实施类 （TDD、domain skills）--- 指导 DO
2.2 完整开发工作流
text
用户提出需求
│
▼
brainstorming ──► 苏格拉底式追问、分段展示设计、用户 approve
│ 产出：docs/plans/YYYY-MM-DD-<topic>-design.md
▼
writing-plans ──► 微任务计划（2--5 分钟一步，含路径、命令、预期输出）
│ 产出：docs/plans/YYYY-MM-DD-<topic>.md
▼
using-git-worktrees（可选）──► 隔离 worktree，跑测试基线
│
├─► subagent-driven-development（同会话、推荐）
│ 每 task：implementer subagent → spec review → code review
│
└─► executing-plans（新会话、分批 checkpoint）
默认每批 3 个 task，等人反馈再继续
│
▼
每个 implement 步骤内：test-driven-development（RED-GREEN-REFACTOR）
│
▼
verification-before-completion（宣称完成前必须跑验证命令）
│
▼
finishing-a-development-branch（测通 → 四选一：merge/PR/保留/丢弃）2.3 两种执行模式对比
| subagent-driven-development | executing-plans | |
|---|---|---|
| 会话 | 当前会话 | 新会话（或当前会话分批） |
| 粒度 | 每 task 一个 fresh subagent | 每批 3 task（可调） |
| Review | 每 task 两阶段（spec → quality） | 每批结束后人工 checkpoint |
| 适合 | task 较独立、要自治数小时 | task 紧耦合、要连续上下文 |
| 平台 | Claude Code 最完整；Cursor 支持 Task/subagent | 全平台 |
2.4 核心 Skills 一览
| Skill | 触发场景 | 刚性 |
|---|---|---|
using-superpowers |
会话开始 | 刚性 |
brainstorming |
新功能、改行为、建组件 | 刚性（硬门禁：无 approve 不写代码） |
writing-plans |
设计已 approve | 流程 |
using-git-worktrees |
实施前隔离分支 | 流程 |
subagent-driven-development |
有计划、task 独立 | 流程 |
executing-plans |
有计划、要 checkpoint | 流程 |
test-driven-development |
写/改代码 | 刚性 |
systematic-debugging |
bug、测试失败、异常行为 | 刚性 |
verification-before-completion |
宣称完成前 | 刚性 |
finishing-a-development-branch |
全部 task 完成 | 流程 |
dispatching-parallel-agents |
多个独立失败域 | 流程 |
requesting-code-review / receiving-code-review |
PR 前后 | 流程 |
2.5 产物落在哪里
| 产物 | 路径 | 说明 |
|---|---|---|
| 设计文档 | docs/plans/YYYY-MM-DD-<topic>-design.md |
brainstorming 产出 |
| 实施计划 | docs/plans/YYYY-MM-DD-<topic>.md |
writing-plans 产出 |
| 隔离工作区 | .worktrees/<branch> 或全局 worktree 目录 |
git worktree |
| Skills 本身 | 插件/shim 管理，非业务仓库 | 各 Agent 环境独立 |
注意 ：Superpowers 不维护 OpenSpec 式的系统级 specs 库；过程管得严，「系统应该怎样」需靠 design/plan 或外接 OpenSpec/Spec Kit。
3. 安装与验证（以 Cursor 为主）
3.1 前置条件
- Cursor IDE（Agent 聊天，非仅 Composer）
- 网络（插件市场）
- 各仓库有 Git（worktree、finishing 流程需要）
- 测试可运行（TDD 与 verification 依赖真实 test 命令）
3.2 Cursor 安装
- 打开 Agent 聊天：
Cmd+L（Mac）/Ctrl+L（Windows/Linux） - 安装插件：
text
/plugin-add superpowers部分版本文档也写 /add-plugin superpowers，以 Cursor 当前提示为准。
- 新开 Agent 会话 验证：
text
Do you have superpowers?Agent 应能列出 skills 并说明工作流。
- 更新：
text
/plugin-update superpowers3.3 其他平台（简要）
| 平台 | 安装方式 |
|---|---|
| Claude Code | /plugin marketplace add obra/superpowers-marketplace → /plugin install superpowers@superpowers-marketplace |
| Gemini CLI | gemini extensions install https://github.com/obra/superpowers |
| Codex CLI | /plugins 搜索 superpowers |
| OpenCode / Pi 等 | 见 GitHub README 手动链接 skills |
3.4 重要：跨环境不共享
在 Claude Code 安装 不会 自动装到 Cursor。每个 harness 各自安装。Skills 是 Markdown，但激活机制因平台而异。
3.5 手动安装（插件失败时）
bash
git clone https://github.com/obra/superpowers.git ~/.superpowers
# 按 Cursor 文档将 skills 目录链到项目或用户 skills 路径具体路径见仓库 docs/ 与各平台 installation 页。
3.6 验证 Skill 自动触发
| 你说的话 | 应触发的 Skill |
|---|---|
| 「设计一个新用户资料功能」 | brainstorming |
| 「实现认证中间件」 | writing-plans → TDD |
| 「这个 API 随机 500」 | systematic-debugging |
若无触发，显式说：use the brainstorming skill。
4. 场景一：单体服务（单仓库）
4.1 适用条件
- 一个 Git 仓库 = 一个可部署单元
- Agent 在 该仓库 内完成设计到交付
- 有可运行的测试套件（JUnit、pytest、jest 等）
4.2 推荐仓库布局
text
my-monolith/
├── docs/
│ └── plans/ # Superpowers 设计 & 计划（进 Git）
│ ├── 2026-08-14-remember-me-design.md
│ └── 2026-08-14-remember-me.md
├── .worktrees/ # 可选，须在 .gitignore
├── src/
├── tests/
├── AGENTS.md # 静态上下文（启动、分层、规范）
└── .cursor/ # 插件注入的 superpowers在 AGENTS.md 中可写：
markdown
实施前遵循 Superpowers：brainstorming → writing-plans → TDD。
测试命令：`./mvnw test` 或 `npm test`。
Worktree 目录：`.worktrees/`（已 gitignore）。4.3 完整教程：登录「记住我」
Phase 0：确认 Superpowers 已加载
新 Agent 会话，确认 skills 可用。
Phase 1：Brainstorming（设计门禁）
你说：
text
给登录加「记住我」，勾选后会话 30 天，未勾选保持 24 小时。Agent 应 不写代码，而是：
- 读项目上下文（
SecurityConfig、现有 session、Redis） - 一次一个问题（优先选择题）
- 提出 2--3 种方案 + 权衡
- 分段展示设计（架构、组件、数据流、错误处理、测试），每段等你确认
- 写入并 commit：
text
docs/plans/2026-08-14-remember-me-design.md你不能跳过 approve。 即使你觉得「很简单」。
Phase 2：Writing Plans（微任务计划）
设计 approve 后，Agent 调用 writing-plans，产出 docs/plans/2026-08-14-remember-me.md。
计划特征：
- 头部：Goal、Architecture、Tech Stack、
REQUIRED SUB-SKILL: executing-plans 或 subagent-driven-development - 每个 Task：精确文件路径、完整测试代码、精确命令、Expected: FAIL/PASS
- 每步 2--5 分钟：写失败测试 → 跑失败 → 最小实现 → 跑通过 → commit
示例 Task 片段：
markdown
### Task 2: RememberMe Cookie 写入
**Files:**
- Modify: `src/main/java/.../SecurityConfig.java`
- Test: `src/test/java/.../RememberMeTest.java`
**Step 1: Write the failing test**
[完整测试代码]
**Step 2: Run test to verify it fails**
Run: `./mvnw test -Dtest=RememberMeTest`
Expected: FAIL --- RememberMeService not found
**Step 3: Minimal implementation**
[最小实现代码]
**Step 4: Run test to verify it passes**
Expected: PASS
**Step 5: Commit**
git add ... && git commit -m "feat: remember-me cookie on login"Agent 会问你选哪种执行方式：
- A. subagent-driven-development（同会话，每 task 新 subagent + 双 review）
- B. executing-plans（新会话分批）
Phase 3：Git Worktree（推荐）
Agent 使用 using-git-worktrees：
- 检查
.worktrees/是否存在且在.gitignore git worktree add .worktrees/remember-me -b feature/remember-menpm install/./mvnw test确认 基线全绿- 报告：
Worktree ready at ... Tests passing (N, 0 failures)
Phase 4：实施（subagent-driven-development 详解）
对 每个 Task：
text
1. Orchestrator 提取 task 全文（不让 subagent 自己读 plan 文件）
2. Dispatch implementer subagent → TDD 实施 → 自审 → commit
3. Dispatch spec reviewer → 是否符合 task/spec？有无 YAGNI 越界？
❌ 有问题 → implementer 修 → 再 review
4. ✅ spec 合规后 → Dispatch code quality reviewer
❌ 有问题 → implementer 修 → 再 review
5. ✅ 双 review 通过 → TodoWrite 标记完成 → 下一 task顺序铁律：必须先 spec compliance ✅，再 code quality review。
全部 task 完成后：final code reviewer + finishing-a-development-branch。
Phase 5：TDD 在每个 Task 内
test-driven-development 铁律：
text
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST若 Agent 先写了实现再补测试 → 应删除重来。你必须看到测试 先失败、再因缺功能失败、再通过后全绿。
Phase 6：Verification Before Completion
宣称「完成」前，Agent 必须：
bash
./mvnw test # 或你的测试命令并贴 完整输出（0 failures），不能说「应该通过了」。
Phase 7：Finishing
finishing-a-development-branch 四选一：
text
1. 本地 merge 回 main
2. Push 并创建 PR
3. 保留分支稍后处理
4. 丢弃（需输入 discard 确认）测试未通过 不得 进入此步。Option 1/4 会清理 worktree。
4.4 存量项目（Brownfield）要点
| 要点 | 做法 |
|---|---|
| 测试基础设施差 | 先补最小测试 harness，或与小功能一起做第一个可测模块 |
| 老代码难 TDD | 对新逻辑严格 TDD；触老逻辑时加 characterization test |
| 设计可很短 | brainstorming 允许几段话，但 必须 present + approve |
| 调试走 systematic-debugging | 禁止「猜一下改一下」；四阶段 + 3 次失败问架构 |
| 计划可增量 | 大功能拆多个 plan 文件，每个走完整循环 |
4.5 单体场景最佳实践
| 实践 | 说明 |
|---|---|
docs/plans/ 进 Git |
设计与计划是工程资产 |
.worktrees/ 必须 gitignore |
worktree skill 会强制检查 |
| 小功能也要 brainstorming | 「太简单」是最高频浪费来源 |
| 优先 subagent-driven-development | 长任务自治、上下文不污染 |
| 遇阻用 executing-plans | 紧耦合 task、需要你看每批结果 |
| 显式测试命令写进 AGENTS.md | verification skill 需要可执行命令 |
5. 场景二：微服务多仓库
5.1 适用条件
- 每微服务独立 Git 仓库
- 跨服务需求（Event、API、网关）需协调
- 各服务有测试（至少新代码可 TDD）
- 使用 Multi-Root Workspace 联调
5.2 Superpowers 在多仓库中的约束
| 能力 | 单仓库 | 多仓库 |
|---|---|---|
| brainstorming | 一次设计整个功能 | 平台级设计 + 各服务细化 |
| writing-plans | 一个 plan | 每仓库一个 plan（推荐） |
| subagent-driven-development | 一个 orchestrator 管所有 task | 每仓库独立 orchestrator 会话 |
| worktree | 本仓库 .worktrees/ |
各仓库各自 worktree |
| 跨仓库并行 | 不适用 | dispatching-parallel-agents 仅限 独立失败域 |
| 插件安装 | 一次 | 每个 Agent 工作环境 需有 Superpowers |
Superpowers 不会 自动把 plan 里的 task 路由到多个 Git 仓库------与 OpenSpec Stores、Spec Kit 一样，跨仓实施靠 人工拆分 + 多会话/多 worktree。
5.3 推荐架构
text
platform-docs/ ← 跨服务设计与协调（可只 brainstorming + 轻 plan）
├── docs/
│ ├── plans/
│ │ ├── 2026-08-14-checkout-promo-design.md
│ │ └── 2026-08-14-checkout-promo-coordination.md
│ ├── api-contracts/
│ └── service-dependencies.md
├── AGENTS.md
└── platform.code-workspace
order-service/ ← 本服务完整 Superpowers 循环
├── docs/plans/
│ └── 2026-08-14-implement-checkout-promo-api.md
├── .worktrees/
└── AGENTS.md
inventory-service/
├── docs/plans/
│ └── 2026-08-14-implement-checkout-promo-consumer.md
└── ...职责分层：
| 层级 | 仓库 | Superpowers 范围 |
|---|---|---|
| 跨服务设计 | platform-docs |
brainstorming 全链路；coordination plan（契约、顺序、联调） |
| 服务实现 | 各服务仓 | 完整循环：plan → worktree → SDD/TDD → finish |
| 静态上下文 | AGENTS.md |
测试命令、分层、依赖链接 |
5.4 教程：跨服务「结账促销码」
Step 1：各环境安装 Superpowers
- Cursor 打开
platform.code-workspace时，插件在 IDE 级 通常已全局可用 - 若 CI/脚本里跑 Agent，该环境也需安装
- 不要假设 Claude Code 上的安装覆盖 Cursor
Step 2：平台仓 --- 跨服务 Brainstorming
在 platform-docs 根（Workspace 多根之一）开 Agent：
text
设计结账促销码：用户输入 promoCode，eligible 减价，ineligible 展示原因。
涉及 gateway、order-service API、inventory 校验、OrderCreatedEvent 新字段。
先不要写任何服务的实现代码。Agent 应：
- 读
docs/service-dependencies.md、现有 api-contracts - 一次一问澄清边界
- 分段设计：API 契约、Event 字段、错误码、服务边界
- 产出
docs/plans/2026-08-14-checkout-promo-design.md并 commit - 更新
docs/api-contracts/order-service.md（设计的一部分）
Step 3：平台仓 --- Coordination Plan（非代码 plan）
text
基于已 approve 的设计，写协调计划：各服务要改什么、发布顺序、联调检查项。
不要写具体 Java 类实现，那是各服务 plan 的事。产出 docs/plans/2026-08-14-checkout-promo-coordination.md：
markdown
## 服务改动清单
- order-service: API + 促销校验 + Event 字段
- inventory-service: Consumer 适配（若有）
- gateway: 路由不变，确认 body 透传
## 发布顺序
1. platform-docs 契约 PR merge
2. order-service（Producer）
3. inventory-service（Consumer）
4. 联调
## 联调检查
- [ ] POST /api/orders 带 promoCode 返回 discountAmount
- [ ] ineligible 返回明确错误码
- [ ] OrderCreatedEvent 含 promoCode、discountAmount此 plan 不在平台仓 implement ------平台仓通常无业务 src/。
Step 4：order-service --- 独立实施循环
切换上下文 ：在 Workspace 中聚焦 order-service，或只打开该仓库。
- reading design：让 Agent 读 platform 设计 doc（跨根路径或粘贴链接）
- writing-plans ：
docs/plans/2026-08-14-implement-checkout-promo-api.md- 仅本仓库路径与测试
- 引用：
遵循 platform-docs/docs/plans/2026-08-14-checkout-promo-design.md
- using-git-worktrees ：
order-service/.worktrees/checkout-promo-api - subagent-driven-development：按 task TDD + 双 review
- finishing-a-development-branch：PR 链到 platform 设计 PR
Step 5：inventory-service --- 并行另一会话
同理独立 plan + worktree + SDD。
两个服务 不要 在同一 orchestrator 里并行 dispatch implementer subagent（会改同一逻辑文件冲突）。应：
- 两个 Agent 会话，或
- 顺序执行各服务 plan
若只是 多个独立测试文件失败 （联调后），可用 dispatching-parallel-agents：
text
order-service 3 个失败测试在 OrderPromoTest
inventory-service 2 个失败在 EventConsumerTest
→ 两个独立 subagent 并行修，最后全量 ./mvnw testStep 6：联调与 Verification
Workspace 打开所有服务后：
text
各仓库分别跑测试，贴完整输出。
对照 coordination plan 联调检查项逐项 verification。verification-before-completion 要求 逐项对照 plan，不能只说「测试都过了」。
5.5 Monorepo 多服务（一个 Git）
若微服务在同一 monorepo（services/order-service/、services/inventory-service/）：
- Superpowers 在 仓库根 安装一次即可
- 每个服务子目录可有独立
docs/plans/ - 各服务独立 worktree 仍推荐（同一 repo 不同 branch worktree）
- brainstorming 可在根做跨服务设计，implement 按子目录 plan
bash
# order-service worktree
git worktree add .worktrees/order-promo -b feature/order-promo
# 在 worktree 内只改 order-service 相关路径5.6 微服务场景最佳实践
| 实践 | 说明 |
|---|---|
| 契约先于服务 implement | platform design PR 先 merge |
| 每服务一个 plan 文件 | 避免一个 plan 跨多个 src/ 根 |
| PR 互链 | 服务 PR → platform 设计 PR |
| 各服务 AGENTS.md 写测试命令 | ./mvnw test 必须可一键跑 |
| 跨服务设计放 platform-docs | 服务 plan 只引用，不重复定义 Event |
| 不用 SDD 并行改两服务同一 feature | 用顺序会话或独立 worktree |
| 联调用 coordination checklist | verification 逐项勾选 |
| 测试少的 legacy consumer | brainstorming 里明确「先补 consumer 测试 harness」 |
5.7 与 OpenSpec / Spec Kit 组合（推荐）
| 层级 | 工具 | 职责 |
|---|---|---|
| 跨服务契约 | OpenSpec Store 或 Spec Kit platform | 可测试需求、delta |
| 服务 feature 计划 | Spec Kit specify→tasks 或 writing-plans |
工件结构 |
| 实施纪律 | Superpowers | TDD、SDD、debug、verify |
组合时注意：
- 不要让 Spec Kit
/speckit.implement与 Superpowers SDD 同时指挥同一批代码 - 推荐：Spec Kit 产出
tasks.md→ 转成 Superpowers plan 格式 → 只由 Superpowers 实施
6. 两种场景对比与选型
6.1 对比表
| 维度 | 单体服务 | 微服务多仓库 |
|---|---|---|
| 安装 | Cursor 一次 | IDE 一次；多仓共享同一 Agent 环境 |
| 设计 | 单次 brainstorming | 平台 brainstorming + 服务细化 |
| 计划 | 一个 docs/plans/*.md |
平台 coordination + 每服务 implement plan |
| worktree | 一个 .worktrees/feature |
每仓库独立 worktree |
| SDD | 单 orchestrator 跑完全部 task | 每仓库独立 SDD 会话 |
| 并行 | subagent 按 task 顺序 | 仅 dispatching-parallel-agents 修独立测试 |
| 完成 | 一次 finishing | 每服务各自 finishing + 联调 verification |
| 产物 | design + plan + 代码 | + api-contracts + coordination checklist |
6.2 决策树
text
部署形态？
│
├─ 单仓库单体
│ → 标准流程：brainstorm → plan → worktree → SDD → finish
│
├─ Monorepo 多服务
│ → 根目录设计；各服务子目录独立 plan/worktree
│
└─ 多 Git 微服务
│
├─ 单服务改动
│ → 只开该服务仓，完整 Superpowers 循环
│
└─ 跨服务功能
→ platform-docs: brainstorm + coordination
→ 各服务: 独立 plan + SDD + PR
→ workspace 联调 + verification checklist6.3 何时不用 Superpowers
| 场景 | 原因 |
|---|---|
| 改一行 typo | brainstorming 过重 |
| 无测试、无法 TDD | 硬门禁会卡住；先建测试基础设施 |
| 纯文档/配置探索 | 用普通 Agent 即可 |
| 只要快速原型_throwaway | 需明确说「跳过 TDD 原型」，否则仍会触发 |
7. 与 OpenSpec / Spec Kit / AGENTS.md 的配合
text
┌─────────────────────────────────────────────────────────┐
│ AGENTS.md │
│ 仓库结构、测试命令、服务边界 --- Superpowers 读作上下文 │
├─────────────────────────────────────────────────────────┤
│ OpenSpec specs/ 或 Spec Kit spec.md │
│ 「做什么」--- 可测试需求（可选外接） │
├─────────────────────────────────────────────────────────┤
│ docs/plans/*-design.md │
│ Superpowers brainstorming 产出 │
├─────────────────────────────────────────────────────────┤
│ docs/plans/*.md │
│ Superpowers writing-plans 产出 │
├─────────────────────────────────────────────────────────┤
│ Skills: TDD / SDD / debug / verify │
│ 「怎么做」--- 强制过程 │
└─────────────────────────────────────────────────────────┘在 AGENTS.md 中推荐增加：
markdown
## Agent 工作流（Superpowers）
1. 新功能：brainstorming → 设计 approve 后再写代码
2. 实施：writing-plans → worktree → subagent-driven-development
3. 测试：`./mvnw test`（verification 前必须跑并贴输出）
4. 跨服务设计见 platform-docs/docs/plans/
5. 改 Event 前读 platform-docs/docs/service-dependencies.md8. Skills 速查表
8.1 过程链
| 顺序 | Skill | 关键铁律 |
|---|---|---|
| 0 | using-superpowers |
1% 可能适用就必须加载 skill |
| 1 | brainstorming |
无 approve 不写代码 |
| 2 | writing-plans |
微任务、精确路径与命令 |
| 3 | using-git-worktrees |
worktree 必须 gitignore |
| 4a | subagent-driven-development |
spec review 先于 code review |
| 4b | executing-plans |
每批 3 task，等反馈 |
| 5 | test-driven-development |
先失败测试 |
| 6 | verification-before-completion |
先跑命令再宣称 |
| 7 | finishing-a-development-branch |
测试通过才四选一 |
8.2 调试与协作
| Skill | 何时 |
|---|---|
systematic-debugging |
任何 bug、测试失败、构建失败 |
dispatching-parallel-agents |
多个 独立 失败域 |
requesting-code-review |
提 PR 前 |
receiving-code-review |
收到 review 意见后 |
writing-skills |
自定义团队 skill |
8.3 刚性 vs 灵活
| 刚性（必须遵守） | 灵活（原则导向） |
|---|---|
| TDD | brainstorming 设计篇幅 |
| systematic-debugging | executing-plans 批次大小 |
| verification-before-completion | worktree 目录选择 |
| brainstorming 硬门禁 | coordination plan 格式 |
9. 常见问题
Q1：没有 slash command，怎么「启动」？
直接说需求即可。Skills 自动触发。也可显式：use brainstorming skill。
Q2：觉得 brainstorming 太慢怎么办？
设计可以很短，但 不能跳过 approve。简单功能 5 分钟设计可避免 2 小时返工。
Q3：Cursor 的 subagent 够用吗？
subagent-driven-development 在 Claude Code 上最成熟。Cursor 支持 Task/subagent 但能力因版本而异；可退而使用 executing-plans 分批人工 checkpoint。
Q4：老项目几乎没测试，还能用吗？
TDD skill 会要求先建测试。选项：① 先为一个模块补 harness；② 明确声明 throwaway 原型跳过 TDD（需你主动说，否则 Agent 仍会坚持）。
Q5：多仓库要装几次 Superpowers？
每个 Agent 运行环境一次 （通常 Cursor IDE 级一次）。不是每个 Git 仓库都要装插件，但 每个仓库 需要自己的 plan/worktree/测试。
Q6：能和 Spec Kit 同时用吗？
可以。推荐 Spec Kit 到 tasks.md，再转为 Superpowers plan 实施；避免 /speckit.implement 与 SDD 同时改代码。
Q7：Agent 说「完成了」但没说跑了测试？
违反 verification-before-completion。要求：Run ./mvnw test and show full output before claiming done.
Q8：worktree 目录被 git 跟踪了怎么办？
using-git-worktrees 应自动加 .gitignore。若已跟踪，手动 untrack 并 commit。
Q9：如何自定义团队 skill？
读 writing-skills skill，在团队仓库或用户 skills 目录添加 SKILL.md，遵循与 Superpowers 相同的触发约定。
Q10：Composer 能用吗？
官方说明：优化对象是 Agent 聊天 。Composer 可能部分生效，完整流程用 Agent（Cmd+L）。
10. 参考链接
附录 A：单体服务一日工作流（清单）
text
□ /plugin-add superpowers（首次）
□ 新 Agent 会话
□ 描述需求 → brainstorming → approve 设计
□ writing-plans → docs/plans/YYYY-MM-DD-feature.md
□ using-git-worktrees → .worktrees/feature-xxx
□ subagent-driven-development（每 task：TDD + 双 review）
□ 全量测试 + verification-before-completion
□ finishing-a-development-branch → PR附录 B：微服务跨功能工作流（清单）
text
□ platform-docs: brainstorming → design.md → coordination.md
□ 更新 api-contracts + service-dependencies
□ platform PR merge
□ order-service: plan → worktree → SDD → PR（链 platform）
□ inventory-service: plan → worktree → SDD → PR
□ workspace 联调：各仓测试 + coordination checklist
□ 各服务 finishing / 合并附录 C：三件套组合参考
| 你要... | OpenSpec | Spec Kit | Superpowers |
|---|---|---|---|
| 活文档、delta review | ✅ 主 | --- | --- |
| 团队 SDD 标准流程 | --- | ✅ 主 | 实施接管 |
| TDD + 长任务自治 | --- | --- | ✅ 主 |
| 微服务契约 | Store | platform specify | platform brainstorm |
| 服务 implement | references | 服务 specify/tasks | 服务 SDD + TDD |
本文基于 Superpowers 官方文档与 obra/superpowers 仓库（2026 年初）整理。Skills 行为以你安装的插件版本为准；升级后执行 /plugin-update superpowers 并重开 Agent 会话。