Obra/superpowers 使用指南：用 Skill 做 Coding + Planning

Aiko · June 1, 2026, 1:57pm

1. 它是什麼

obra/superpowers 是一套給 coding agent 用的「軟體開發方法論 + skills 系統」。它不是單一 prompt，而是一組流程化技能，讓 agent 在寫程式前先釐清需求、寫 spec、拆 implementation plan、用 TDD 開發、做 code review、最後 merge 或 PR。官方 README 明確說它支援 Claude Code、Codex CLI、Codex App、Factory Droid、Gemini CLI、OpenCode、Cursor、GitHub Copilot CLI。(GitHub)

核心差異：

一般 AI coding	Superpowers coding
直接寫 code	先 brainstorming / spec
邊寫邊猜	先確認設計與限制
大段修改	切成 2–5 分鐘小任務
寫完才測	TDD：先寫 failing test
自稱完成	必須跑驗證命令
單一 agent 長上下文混亂	用 subagent 分工與 review

2. 安裝方式

Claude Code

/plugin install superpowers@claude-plugins-official

或使用 Superpowers marketplace：

/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

README 目前列出以上兩種 Claude Code 安裝方式。(GitHub)

Codex CLI

/plugins

然後搜尋：

superpowers

選擇 Install Plugin。README 顯示 Codex CLI 透過官方 Codex plugin marketplace 安裝。(GitHub)

Codex App

在 Codex App sidebar 點 Plugins，Coding 區會看到 Superpowers，按 + 安裝。(GitHub)

OpenCode

Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md

README 指出 OpenCode 需要獨立安裝，即使你已經在其他 harness 安裝過也一樣。(GitHub)

Cursor

/add-plugin superpowers

或在 Cursor plugin marketplace 搜尋 superpowers。(GitHub)

Gemini CLI

gemini extensions install https://github.com/obra/superpowers
gemini extensions update superpowers

(GitHub)

3. 核心工作流

Superpowers 的基本流程是：

brainstorming
→ using-git-worktrees
→ writing-plans
→ subagent-driven-development / executing-plans
→ test-driven-development
→ requesting-code-review
→ finishing-a-development-branch

README 直接列出這個 basic workflow：先 brainstorming，再建立 isolated workspace，接著寫 plan，然後執行任務、TDD、code review，最後完成 branch。(GitHub)

4. 每個 Skill 的用途

Skill	使用時機	作用
`using-superpowers`	每次 conversation 開始	判斷是否要載入相關 skill；明確規則是「只要 1% 可能適用，就先 invoke skill」。(GitHub)
`brainstorming`	新功能、元件、行為修改前	先理解 context、問需求、提出 2–3 種方案、寫 design spec，不允許直接寫 code。(GitHub)
`writing-plans`	已有 spec / requirements 後	把需求拆成 implementation plan，預設存到 `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`。(GitHub)
`using-git-worktrees`	開始 feature work 或執行 plan 前	建立 isolated workspace，避免污染目前 branch，並先跑 baseline tests。(GitHub)
`test-driven-development`	實作 feature、bugfix、refactor 前	嚴格要求先寫 failing test，再寫最小 code 通過測試。(GitHub)
`systematic-debugging`	遇到 bug、test failure、build failure	先找 root cause，不允許猜測式修 bug。(GitHub)
`subagent-driven-development`	有 implementation plan 且支援 subagents	每個任務派 fresh subagent，經過 spec review + code quality review。(GitHub)
`executing-plans`	有 plan，但不使用 subagents 或不同 session 執行	讀 plan、逐步執行、跑驗證；若有 subagents，官方建議改用 `subagent-driven-development`。(GitHub)
`requesting-code-review`	完成功能、task、merge 前	派 code reviewer subagent 檢查需求符合度與 code quality。(GitHub)
`verification-before-completion`	宣稱完成、修好、測試通過前	必須先跑完整驗證命令；「沒有新鮮證據，不准宣稱完成」。(GitHub)
`finishing-a-development-branch`	所有任務完成後	先確認 tests pass，再提供 merge、PR、keep、discard 選項。([GitHub][12])

5. 最適合的使用方式

適合

任務類型	適合度
多檔案 feature	高
Next.js / Sanity / Webflow tooling / plugin 開發	高
bugfix with tests	高
refactor	高
CLI tool / backend API / integration workflow	高
一次性小改文案	低
沒有 test framework 的純 UI 微調	中低
prototype / throwaway demo	中

Superpowers 的價值在於「降低 AI coding 失控率」。它會犧牲一點速度，換來更穩定的 plan、test、review、branch hygiene。

6. 建議專案設定

在專案根目錄加 AGENTS.md，讓 Codex / Claude Code 更容易照你的專案規則工作。

# Project Instructions

Use Superpowers for all non-trivial development work.

## Required workflow

1. Use brainstorming before creating or modifying features.
2. Write specs to:
   `docs/superpowers/specs/`
3. Write implementation plans to:
   `docs/superpowers/plans/`
4. Use an isolated worktree before implementation.
5. Use TDD for feature work and bug fixes.
6. Do not claim completion without running verification commands.
7. Prefer small, focused files.
8. Follow existing project structure and naming conventions.

## Tech stack

- Next.js
- TypeScript
- Tailwind CSS
- Sanity CMS

## Verification commands

```bash
npm run lint
npm run typecheck
npm test
npm run build

Coding rules

No broad refactor unless required by the current task.
No unrelated formatting changes.
No new dependencies without explaining why.
Keep implementation minimal.
Commit after each completed task.


重點：Superpowers 文件明確寫到 user instructions，例如 `CLAUDE.md`、`GEMINI.md`、`AGENTS.md` 或直接要求，優先權高於 Superpowers skill。:contentReference[oaicite:19]{index=19}

---

# 7. 可直接使用的 Prompt 範本

## Prompt 1：啟動新功能規劃

```text
Use Superpowers.

I want to build the following feature:

[描述功能]

Before writing any code:
1. Use brainstorming.
2. Inspect the current project structure.
3. Ask only necessary clarification questions.
4. Propose 2–3 implementation approaches with trade-offs.
5. Recommend one approach.
6. Write the approved design spec to docs/superpowers/specs/.
7. Do not implement until I approve the spec.

Project constraints:
- Tech stack: [填入]
- Existing patterns must be followed.
- Avoid unnecessary dependencies.
- Keep the scope minimal.

Prompt 2：把需求轉成 implementation plan

Use Superpowers writing-plans.

Based on the approved spec at:

docs/superpowers/specs/[filename].md

Create a detailed implementation plan.

Requirements:
1. Save it to docs/superpowers/plans/YYYY-MM-DD-[feature-name].md.
2. Break work into small tasks.
3. Each task must include exact files to create or modify.
4. Each task must include test steps.
5. Use TDD.
6. Include verification commands.
7. Keep implementation minimal and avoid unrelated refactor.

Prompt 3：讓 Codex / Claude Code 直接執行 plan

Use Superpowers.

Execute this plan:

docs/superpowers/plans/[filename].md

Rules:
1. Use an isolated worktree before implementation.
2. Use subagent-driven-development if available.
3. If subagents are unavailable, use executing-plans.
4. Follow the plan task by task.
5. Use TDD for every behavior change.
6. Run verification after each task.
7. Request code review after major task completion.
8. Do not continue if tests fail repeatedly.
9. Do not claim completion without fresh verification output.

Prompt 4：Debug bug，不要亂猜

Use Superpowers systematic-debugging.

Bug:

[貼上 bug 描述 / error / stack trace]

Rules:
1. Do not propose a fix before root cause investigation.
2. Reproduce the issue first.
3. Read the full error and trace data flow.
4. Check recent changes and related working examples.
5. State the root cause hypothesis.
6. Write a failing regression test before fixing.
7. Implement the smallest fix.
8. Verify the test fails before the fix and passes after the fix.
9. Run full verification before claiming the bug is fixed.

Prompt 5：Code review

Use Superpowers requesting-code-review.

Review the current changes against:

[spec or plan file path]

Focus on:
1. Requirement compliance.
2. Missing edge cases.
3. Overbuilt or unrelated changes.
4. Test coverage.
5. Type safety.
6. Integration risk.
7. Code maintainability.

Classify issues as:
- Critical
- Important
- Minor

Do not approve unless the implementation matches the plan and verification passes.

Prompt 6：完成 branch / PR

Use Superpowers finishing-a-development-branch.

The implementation is complete.

Before offering merge or PR options:
1. Run the full verification commands.
2. Confirm tests, typecheck, lint, and build status.
3. Detect whether this is a normal repo or worktree.
4. Present the standard completion options:
   - merge locally
   - push and create PR
   - keep branch
   - discard

8. Codex CLI 使用範例

情境

你要在 Next.js + Sanity 專案新增 projectSingleContent block，顯示：

painpoint
strategy
solution
result
gallery

Step 1：安裝 plugin

/plugins

搜尋：

superpowers

Install Plugin。

Step 2：在專案根目錄啟動 Codex CLI

cd your-project
codex

Step 3：貼這段 prompt

Use Superpowers.

I want to add a new projectSingleContent section to this Next.js + Sanity project.

Feature requirements:
- Read project fields from Sanity:
  - painpoint
  - strategy
  - solution
  - result
  - gallery
- Render them on the project single page.
- Follow existing schema, GROQ query, component, and section patterns.
- Use TypeScript types.
- Keep styling consistent with the existing Tailwind design system.
- Do not introduce new dependencies.
- Do not refactor unrelated project structure.

Before writing code:
1. Use brainstorming.
2. Inspect the current codebase.
3. Identify existing project single page patterns.
4. Propose 2–3 implementation approaches.
5. Recommend one.
6. Write a design spec to docs/superpowers/specs/.
7. Wait for approval before implementation.

Step 4：你 approve spec 後貼

Use Superpowers writing-plans.

Create the implementation plan from the approved spec.

Plan requirements:
- Save to docs/superpowers/plans/YYYY-MM-DD-project-single-content.md
- Include exact file paths.
- Include test or verification steps.
- Include TypeScript, lint, and build verification.
- Break the work into small tasks.
- Do not implement yet.

Step 5：你 approve plan 後貼

Use Superpowers.

Execute:

docs/superpowers/plans/YYYY-MM-DD-project-single-content.md

Rules:
- Use using-git-worktrees before implementation.
- Use subagent-driven-development if Codex supports it.
- Use TDD where behavior can be tested.
- Run npm run lint, npm run typecheck, and npm run build before completion.
- Request code review before finishing.
- Do not claim completion without verification output.

9. 實際工作流範例

User:
Use Superpowers. Build projectSingleContent for my Next.js + Sanity project.

Agent:
I'm using the brainstorming skill to explore the design before implementation.

Agent actions:
- Reads project structure
- Finds Sanity schema
- Finds project single page query
- Finds existing section components
- Asks necessary clarification
- Proposes 2–3 approaches
- Writes spec:
  docs/superpowers/specs/2026-06-01-project-single-content-design.md

User:
Approved.

Agent:
I'm using the writing-plans skill to create the implementation plan.

Agent actions:
- Writes plan:
  docs/superpowers/plans/2026-06-01-project-single-content.md
- Breaks work into tasks:
  Task 1: update Sanity schema
  Task 2: update GROQ query
  Task 3: update TypeScript types
  Task 4: create ProjectSingleContent component
  Task 5: integrate into page
  Task 6: verify build

User:
Execute.

Agent:
I'm using the using-git-worktrees skill to set up an isolated workspace.

Agent actions:
- Creates worktree
- Runs npm install if needed
- Runs baseline tests

Agent:
I'm using subagent-driven-development to execute the plan.

Agent actions:
- Subagent implements Task 1
- Spec reviewer checks requirement compliance
- Code quality reviewer checks implementation
- Repeat for every task
- Runs lint/typecheck/build
- Requests final review
- Uses finishing-a-development-branch

10. 實務判斷

用 Superpowers 的最大價值

它把 AI coding 從「一次丟 prompt 賭結果」改成「spec → plan → test → review → verification」。對 Codex CLI / Claude Code 這種 agentic coding 工具尤其有用，因為長任務最容易失控的地方不是寫不出 code，而是：

沒理解需求就開始改
改太多不相關檔案
沒測試就宣稱完成
bugfix 靠猜
branch 污染
code review 不嚴格
task 越做越偏

Superpowers 的設計就是壓制這些失敗模式。

它的缺點

問題	說明
流程重	小任務會顯得太慢
TDD 很硬	不適合所有 UI prototype
需要測試基礎	沒有 test setup 的專案會先卡住
對 agent 能力有要求	subagent 支援越完整，效果越好
對人也有要求	你要 review spec / plan，不要讓 agent 自己一路亂跑

最佳使用策略

任務規模	建議
5 分鐘內小改	直接改，不一定需要全套
30–90 分鐘 feature	用 brainstorming + writing-plans + TDD
多檔案功能	用完整 Superpowers workflow
bugfix	一定用 systematic-debugging
refactor	一定先寫 plan
production code	一定跑 verification-before-completion

11. 最短可用 Prompt

Use Superpowers.

For this coding task:
1. Use brainstorming before implementation.
2. Write a spec.
3. Write an implementation plan.
4. Use an isolated worktree.
5. Implement task by task.
6. Use TDD.
7. Request code review.
8. Run verification before claiming completion.

Task:
[貼需求]

12. 最推薦的 Codex CLI Prompt

Use Superpowers.

You are working in an existing production codebase.

Task:
[貼上你的功能或 bugfix]

Hard rules:
- Do not write code immediately.
- Inspect the codebase first.
- Use brainstorming to clarify the design.
- Save the spec to docs/superpowers/specs/.
- After approval, use writing-plans.
- Save the plan to docs/superpowers/plans/.
- Use using-git-worktrees before implementation.
- Use subagent-driven-development if available.
- Use executing-plans only if subagents are unavailable.
- Use TDD for all behavior changes.
- Use systematic-debugging for any bug or failing test.
- Request code review before finishing.
- Run lint, typecheck, tests, and build before claiming completion.
- Do not make unrelated refactors.
- Do not add dependencies unless required.
- Follow existing project patterns.

結論：obra/superpowers 最適合拿來管 Codex CLI / Claude Code 的「開發流程」，不是拿來取代 prompt。你應該把它當成 AI agent 的 engineering operating system：先規劃、再拆工、再測試、再審查、最後驗證。

[12]: https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/skills/finishing-a-development-branch/SKILL.md "" --body "$(cat <<‘EOF’
## Summary
<2-3 bullets of what changed>

## Test Plan
-
EOF
)"
```

*Do NOT clean up worktree* — user needs it alive to iterate on PR feedback.

#### Option 3: Keep As-Is

Report: "Keeping branch . Worktree preserved at ."

*Don’t cleanup worktree.*

#### Option 4: Discard

*Confirm first:*
```
This will permanently delete:
- Branch
- All commits:
- Worktree at

Type ‘discard’ to confirm.
```

Wait for exact confirmation.

If confirmed:
```bash
MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"
```

Then: Cleanup worktree (Step 6), then force-delete branch:
```bash
git branch -D
```

### Step 6: Cleanup Workspace

*Only runs for Options 1 and 4.* Options 2 and 3 always preserve the worktree.

```bash
GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
WORKTREE_PATH=$(git rev-parse --show-toplevel)
```

*If GIT_DIR == GIT_COMMON:* Normal repo, no worktree to clean up. Done.

*If worktree path is under .worktrees/, worktrees/, or ~/.config/superpowers/worktrees/:* Superpowers created this worktree — we own cleanup.

```bash
MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"
git worktree remove "$WORKTREE_PATH"
git worktree prune # Self-healing: clean up any stale registrations
```

*Otherwise:* The host environment (harness) owns this workspace. Do NOT remove it. If your platform provides a workspace-exit tool, use it. Otherwise, leave the workspace in place.

## Quick Reference

| Option | Merge | Push | Keep Worktree | Cleanup Branch |
|--------|-------|------|---------------|----------------|
| 1. Merge locally | yes | - | - | yes |
| 2. Create PR | - | yes | yes | - |
| 3. Keep as-is | - | - | yes | - |
| 4. Discard | - | - | - | yes (force) |

## Common Mistakes

*Skipping test verification*
- Problem: Merge broken code, create failing PR
- Fix: Always verify tests before offering options

*Open-ended questions*
- Problem: "What should I do next?" is ambiguous
- Fix: Present exactly 4 structured options (or 3 for detached HEAD)

*Cleaning up worktree for Option 2*
- Problem: Remove worktree user needs for PR iteration
- Fix: Only cleanup for Options 1 and 4

*Deleting branch before removing worktree*
- Problem: git branch -d fails because worktree still references the branch
- Fix: Merge first, remove worktree, then delete branch

*Running git worktree remove from inside the worktree*
- Problem: Command fails silently when CWD is inside the worktree being removed
- Fix: Always cd to main repo root before git worktree remove

*Cleaning up harness-owned worktrees*
- Problem: Removing a worktree the harness created causes phantom state
- Fix: Only clean up worktrees under .worktrees/, worktrees/, or ~/.config/superpowers/worktrees/

*No confirmation for discard*
- Problem: Accidentally delete work
- Fix: Require typed "discard" confirmation

## Red Flags

*Never:*
- Proceed with failing tests
- Merge without verifying tests on result
- Delete work without confirmation
- Force-push without explicit request
- Remove a worktree before confirming merge success
- Clean up worktrees you didn’t create (provenance check)
- Run git worktree remove from inside the worktree

*Always:*
- Verify tests before offering options
- Detect environment before presenting menu
- Present exactly 4 options (or 3 for detached HEAD)
- Get typed confirmation for Option 4
- Clean up worktree for Options 1 & 4 only
- cd to main repo root before worktree removal
- Run git worktree prune after removal
"