# Superpowers 사용법

> Claude Code용 플러그인. 버전 **5.1.0** (claude-plugins-official)
> 제작: Jesse Vincent · https://github.com/obra/superpowers

---

## 1. Superpowers가 뭔가

Superpowers는 **코딩 에이전트에게 "개발 방법론"을 입히는 스킬 모음집**이다.
설치하면 Claude가 코드를 짤 때 곧장 코드부터 쓰지 않고,

1. **무엇을 만들려는지 먼저 캐묻고(brainstorming)** →
2. **설계 문서를 보여주고 승인을 받고** →
3. **실행 계획서(plan)를 만들고** →
4. **TDD(빨강→초록) 기반으로 한 단계씩 구현하고** →
5. **검증하고 코드 리뷰까지** 하는

체계적인 흐름을 자동으로 따른다.

핵심은 **"스킬이 자동으로 발동된다"**는 것. 사용자가 특별히 명령하지 않아도, Claude가 상황을 보고 알아서 맞는 스킬을 꺼내 쓴다.

---

## 2. 가장 중요한 사실 — 따로 외울 명령어가 없다

Superpowers는 슬래시 명령(`/superpowers ...` 같은 것)이 **없다.**
대신 **14개의 스킬**로 구성되어 있고, Claude가 대화 맥락에 맞춰 **알아서 호출**한다.

| 사용자가 하는 일 | Claude가 자동으로 하는 일 |
|---|---|
| "○○ 기능 만들어줘" | `brainstorming` 발동 → 질문으로 요구사항 정리 |
| 설계 승인함 | `writing-plans` 발동 → 실행 계획서 작성 |
| "이제 진행해" | `test-driven-development` + `executing-plans` 발동 |
| 버그/에러 발생 | `systematic-debugging` 발동 |
| "다 됐어/끝났어" | `verification-before-completion` → `requesting-code-review` |

즉 **평소처럼 한국어로 시키기만 하면 된다.** Claude가 "Using [스킬명] to [목적]" 이라고 알리고 해당 절차를 따른다.

---

## 3. 14개 스킬 한눈에 보기

### 🧭 시작 & 설계
| 스킬 | 언제 발동 |
|---|---|
| **using-superpowers** | 모든 대화 시작 시 — 어떤 스킬을 쓸지 판단하는 진입점 |
| **brainstorming** | 새 기능·컴포넌트·동작 변경 등 **창작 작업 전 필수**. 의도·요구사항·설계를 먼저 탐색 |
| **writing-plans** | 스펙이 정해진 다단계 작업의 **구현 계획서** 작성 |

### 🔨 구현
| 스킬 | 언제 발동 |
|---|---|
| **test-driven-development** | 모든 기능/버그픽스 구현 시 — 구현 코드 전에 테스트 먼저 |
| **executing-plans** | 작성된 계획서를 **별도 세션에서** 체크포인트 단위로 실행 |
| **subagent-driven-development** | 계획서의 독립 작업들을 **현재 세션에서** 서브에이전트로 실행 |
| **dispatching-parallel-agents** | 의존성 없는 2개 이상 작업을 **병렬** 처리 |
| **using-git-worktrees** | 현재 작업공간과 격리된 별도 워크스페이스가 필요할 때 |

### 🐞 디버깅 & 검증
| 스킬 | 언제 발동 |
|---|---|
| **systematic-debugging** | 버그·테스트 실패·예상 밖 동작 — **고치기 전에** 원인부터 체계적으로 |
| **verification-before-completion** | "완료/수정됨/통과" 라고 말하기 전 — 실제로 명령 돌려 **증거** 확인 |

### 👀 코드 리뷰 & 마무리
| 스킬 | 언제 발동 |
|---|---|
| **requesting-code-review** | 작업 완료·주요 기능 구현·머지 전 검증 |
| **receiving-code-review** | 리뷰 피드백 받았을 때 — 맹목적 수용 말고 기술적 검증 |
| **finishing-a-development-branch** | 구현 끝 + 테스트 통과 후 머지/PR/정리 결정 |

### 🛠 메타
| 스킬 | 언제 발동 |
|---|---|
| **writing-skills** | 새 스킬을 만들거나 기존 스킬을 수정할 때 |

---

## 4. 전형적인 작업 흐름 (예시)

```
나:  "사이트맵 수집 결과를 검증하는 작은 스크립트 만들어줘"
        │
        ▼
[brainstorming]  Claude가 질문을 하나씩 던짐
        - 입력 형식? 어떤 검증? 실패 시 동작?
        - 2~3가지 접근법 + 추천안 제시
        - 설계를 짧게 정리해 보여주고 승인 요청
        - docs/superpowers/specs/YYYY-MM-DD-검증스크립트-design.md 로 저장
        │
        ▼ (내가 "좋아" 승인)
[writing-plans]  구현 계획서 작성 → docs/superpowers/plans/ 에 저장
        │
        ▼ (내가 "진행해")
[test-driven-development]  테스트 먼저 작성(빨강) → 구현(초록) → 리팩터
[subagent-driven-development]  작업 단위로 서브에이전트가 진행/검토
        │
        ▼
[verification-before-completion]  실제로 돌려서 통과 증거 확보
[requesting-code-review]  변경분 리뷰
        │
        ▼
[finishing-a-development-branch]  머지/PR/정리 옵션 제시
```

산출물 저장 위치:
- 설계 문서 → `docs/superpowers/specs/`
- 계획서 → `docs/superpowers/plans/`

---

## 5. 실전 팁

- **그냥 평소대로 시키면 된다.** "○○ 만들어줘"라고 하면 brainstorming부터 시작한다.
- **간단한 작업이라도 설계 단계를 거친다.** "이건 너무 간단한데" 싶어도 Claude가 짧게라도 설계를 보여주고 승인을 받는다 — 이게 의도된 동작이다.
- **특정 스킬을 직접 부르고 싶으면** 이름을 말하면 된다. 예: "systematic-debugging 스킬 써서 이 에러 봐줘"
- **건너뛰고 싶으면 말하면 된다.** 사용자 지시가 스킬보다 우선이다. 예: "설계 단계 생략하고 바로 짜줘", "TDD 말고 그냥 구현해줘" → Claude가 따른다.
- **CLAUDE.md 규칙이 항상 최우선.** 우선순위: ① 사용자 지시(CLAUDE.md·직접 요청) → ② Superpowers 스킬 → ③ 기본 동작.

---

## 6. 설치 / 관리 명령 (Claude Code 터미널)

```bash
# 설치 (이미 설치됨)
/plugin install superpowers@claude-plugins-official

# 적용 (설치 직후 1회)
/reload-plugins

# 플러그인 관리 UI
/plugin
```

설치 경로:
`~/.claude/plugins/cache/claude-plugins-official/superpowers/5.1.0/`

---

## 7. 한 줄 요약

> **"평소처럼 한국어로 작업을 시켜라. Superpowers가 알아서 설계 → 계획 → TDD 구현 → 검증 → 리뷰 흐름을 태운다. 건너뛰고 싶으면 그렇게 말하면 된다."**