# Superpowers 프레임워크 심층 분석 보고서

**버전 기준**: v5.0.5 (2026-03-17)
**분석일**: 2026-03-23
**분석자**: 다그다(팀장)/루(백엔드)/에인(UX) — dev3-team
**이전 분석 대비**: task-328.1 (2026-03-06, v4.3.1 기준) → 재확인

---

## 1. 레포 개요

| 항목 | 내용 |
|------|------|
| URL | https://github.com/obra/superpowers |
| 최신 버전 | v5.0.5 (2026-03-17) |
| 라이선스 | MIT |
| 목적 | Coding agent용 완전한 소프트웨어 개발 워크플로우 프레임워크 |
| 지원 플랫폼 | Claude Code, Cursor, Codex, OpenCode, Gemini CLI |

Superpowers는 단순한 프롬프트 모음이 아니다. SessionStart 훅 기반 자동 주입, 온디맨드 스킬 로딩, 서브에이전트 오케스트레이션까지 아우르는 **구조화된 AI 개발 워크플로우 프레임워크**다. 핵심 철학은 "에이전트의 자유도를 규율로 대체하여 예측 가능한 결과를 얻는다"는 것이다.

---

## 2. 전체 디렉토리 구조

```
superpowers/
├── skills/                                   # 14개 스킬 모음
│   ├── using-superpowers/SKILL.md            # 메타스킬: 스킬 사용 방법 및 세션 시작 가이드
│   ├── brainstorming/SKILL.md                # Phase 1: 아이디어 → 승인된 스펙 변환
│   ├── writing-plans/SKILL.md                # Phase 3: 마이크로태스크 기반 구현 계획 작성
│   ├── subagent-driven-development/          # Phase 4: 서브에이전트 위임 개발
│   │   ├── SKILL.md
│   │   └── implementer-prompt.md             # 구현 서브에이전트용 프롬프트 템플릿
│   ├── executing-plans/SKILL.md              # Phase 4 대안: 인라인 플랜 직접 실행
│   ├── dispatching-parallel-agents/SKILL.md  # 병렬 에이전트 파견 (독립 태스크용)
│   ├── test-driven-development/              # Phase 5: TDD 강제 메커니즘
│   │   ├── SKILL.md
│   │   └── testing-anti-patterns.md          # 피해야 할 테스트 패턴 목록
│   ├── systematic-debugging/SKILL.md         # 체계적 디버깅 프로세스
│   ├── verification-before-completion/SKILL.md # 완료 전 검증 게이트
│   ├── requesting-code-review/SKILL.md       # Phase 6: 코드리뷰 요청 프로세스
│   ├── receiving-code-review/SKILL.md        # Phase 6: 코드리뷰 피드백 수용
│   ├── using-git-worktrees/SKILL.md          # Phase 2: Git Worktree 기반 격리
│   ├── finishing-a-development-branch/SKILL.md # Phase 7: 브랜치 완료 처리
│   └── writing-skills/SKILL.md               # 메타스킬: 새 스킬 작성 방법론
├── agents/
│   └── code-reviewer.md                      # 코드리뷰 서브에이전트 정의
├── commands/
│   ├── brainstorm.md                         # /brainstorm 슬래시 커맨드
│   ├── execute-plan.md                       # /execute-plan 슬래시 커맨드
│   └── write-plan.md                         # /write-plan 슬래시 커맨드
├── hooks/
│   ├── hooks.json                            # Claude Code용 훅 설정
│   ├── hooks-cursor.json                     # Cursor용 훅 설정 (v5.0.3+)
│   └── session-start                         # 훅 실행 스크립트 (bash)
├── .claude-plugin/
│   └── plugin.json                           # 플러그인 메타데이터 (v5.0.5)
├── tests/                                    # 스킬 테스트 스위트
│   ├── explicit-skill-requests/              # 9개 명시적 요청 시나리오
│   ├── skill-triggering/                     # 6개 자동 트리거 검증
│   ├── subagent-driven-dev/                  # Go fractal, Svelte Todo 통합 테스트
│   ├── brainstorm-server/                    # WebSocket 프로토콜 테스트
│   └── claude-code/                          # 스킬 실행 분석, 토큰 사용량 분석
└── docs/                                     # 설계 문서 및 스펙
```

---

## 3. 스킬 시스템 아키텍처

### 3.1 자동 활성화 메커니즘

Superpowers의 가장 핵심적인 기술적 특징은 **SessionStart 훅 기반 자동 주입**이다.

`hooks/hooks.json` 설정:
```json
{
  "hooks": {
    "SessionStart": [{
      "matcher": "startup|clear|compact",
      "hooks": [{
        "type": "command",
        "command": "hooks/session-start",
        "async": false
      }]
    }]
  }
}
```

`async: false`가 결정적이다. 에이전트의 **첫 응답 전에 동기적으로** 훅이 완료되어야 하므로, using-superpowers/SKILL.md 내용이 `<EXTREMELY_IMPORTANT>` 태그로 감싸져 시스템 컨텍스트에 주입된다. 에이전트는 세션 시작부터 Superpowers 워크플로우를 인지한 상태로 동작한다.

플랫폼별 컨텍스트 전달 필드:

| 플랫폼 | 필드명 |
|--------|--------|
| Claude Code | `hookSpecificOutput.additionalContext` |
| Cursor | `additional_context` |
| 그 외 | 자동 감지 |

`startup|clear|compact` 이벤트 모두 대응하는 것도 중요하다. `/clear`로 컨텍스트를 초기화하거나 `/compact`로 압축해도 훅이 재실행되어 스킬 컨텍스트가 재주입된다. v5.0.3에서 `--resume` 플래그 사용 시 훅이 재주입되는 버그가 수정되었다.

### 3.2 스킬 발견 우선순위

스킬 로딩 시 3단계 우선순위로 탐색한다:

```
1순위: .claude/skills/           (프로젝트 로컬 커스터마이징)
2순위: ~/.claude/skills/         (사용자 글로벌 커스터마이징)
3순위: 플러그인 skills/           (Superpowers 기본 스킬)
```

이 구조는 프로젝트별 오버라이드를 허용하면서도 기본 동작을 보장한다. 스킬은 **Skill tool로 온디맨드 로딩**된다. `@` 링크 방식(파일 직접 참조)은 명시적으로 금지되어 있다 — 불필요한 컨텍스트 소비를 막기 위해서다.

### 3.3 스킬 타입 분류

| 타입 | 해당 스킬 | 동작 방식 |
|------|----------|----------|
| **Rigid** | TDD, systematic-debugging | 원칙 양보 불가, 정확히 따름 |
| **Flexible** | brainstorming, writing-plans | 컨텍스트에 맞게 조정 가능 |

TDD와 디버깅이 Rigid로 분류된 이유는 명확하다. 이 두 영역에서 "상황에 따른 예외"는 품질 저하의 주범이기 때문이다.

### 3.4 CSO (Claude Search Optimization)

SKILL.md 파일의 프론트매터 구조:

```yaml
---
name: skill-name          # 글자/숫자/하이픈만, 최대 1024자
description: Use when ... # 트리거 조건만, 워크플로우 요약 금지
---
```

description에 워크플로우 요약을 넣으면 Claude가 description만 읽고 스킬 본문을 건너뛰는 문제가 발생한다. 따라서 description은 **"언제 이 스킬을 쓸지"만** 기술해야 한다.

CSO 원칙:
- 구체적 증상, 오류 메시지, 키워드를 풍부하게 포함
- Claude의 스킬 선택 알고리즘이 description을 임베딩 기반으로 매칭하기 때문에 검색어처럼 작성

### 3.5 스킬 작성 방법론 (TDD for Skills)

writing-skills/SKILL.md는 **스킬 작성 자체에 TDD를 적용**하는 메타 방법론이다:

1. **Baseline (RED)**: 현재 에이전트가 어떤 잘못된 동작을 하는지 기록
2. **스킬 작성 (GREEN)**: 최소한의 지시로 잘못된 동작 교정
3. **루프홀 폐쇄 (REFACTOR)**: 합리화 표(Rationalization Table) + Red Flags 목록으로 예외 상황 차단

필수 구성 요소:
- 합리화 표: 에이전트가 스킬을 우회하려 할 때 쓰는 11가지 핑계 → 현실 반박
- Graphviz DOT 플로차트: 결정 분기점이 있는 경우에만 사용
- 토큰 효율성: 자주 로드되는 스킬은 150단어 이하로 제한

---

## 4. 7-Phase 워크플로우 심층 분석

### Phase 1: Brainstorming

**트리거**: 코딩 시작 전 `EnterPlanMode` 진입, 창의적 작업 전

**HARD-GATE**: 설계 승인 전 어떠한 구현 행동도 절대 금지. 이는 단순 권고가 아닌 강제 차단이다.

9단계 프로세스:

| 단계 | 내용 |
|------|------|
| 1 | 프로젝트 컨텍스트 탐색 (파일, 문서, 최근 커밋) |
| 2 | Visual Companion 제안 (UI 관련 시각적 작업 있을 때) |
| 3 | 질문 하나씩, 멀티플 초이스 선호 |
| 4 | 2-3가지 접근법 + 트레이드오프 제시 |
| 5 | 설계 섹션별 제시 + 사용자 승인 |
| 6 | 설계 문서 작성 (`docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`) + 커밋 |
| 7 | spec-document-reviewer 서브에이전트 최대 3회 루프 |
| 8 | User Review Gate (사용자 최종 검토) |
| 9 | writing-plans 스킬로 전환 |

**Visual Companion** (v5.0.1+): 브라우저 기반 시각 도구. 목업, 다이어그램 생성. 별도 메시지로만 제안 (메인 흐름 방해 금지).

**YAGNI 원칙**: 모든 설계에서 "지금 당장 필요 없는 기능"을 명시적으로 제거하는 단계 포함.

### Phase 2: Git Worktrees

**트리거**: 기능 작업 시작 전, 구현 계획 실행 전

디렉토리 선택 우선순위:
1. `.worktrees/` 디렉토리 존재 여부 확인
2. `CLAUDE.md` 설정 참조
3. 1, 2 없으면 사용자에게 직접 질문

안전 검증: `git check-ignore` 명령으로 project-local worktree가 `.gitignore`에 포함됐는지 **반드시** 확인. 미포함 시 작업 중단.

설정 자동 감지: `package.json`, `Cargo.toml`, `requirements.txt` 등 빌드 파일 감지 후 의존성 자동 설치. 베이스라인 테스트 실행으로 클린 상태 확인 후 작업 시작.

### Phase 3: Writing Plans

**트리거**: 스펙이 확정됐을 때, 코드에 손대기 전

계획 문서 필수 헤더:
```markdown
## Goal
[구현 목표]

## Architecture
[아키텍처 결정사항]

## Tech Stack
[사용 기술]
```

각 마이크로태스크(2~5분 단위)에 반드시 포함해야 할 4가지:
1. 정확한 파일 경로
2. 완성된 코드 (의사코드 금지)
3. 검증 명령어 + 기대 출력
4. 커밋 명령어

**Plan Review Loop**: plan-document-reviewer 서브에이전트를 최대 3회 실행하여 계획 품질 검증.

**실행 방식 선택** (v5.0.5에서 강제 해제, 선택 복원):
- Subagent-Driven Development (권장): 태스크별 신선한 서브에이전트
- Inline Execution: 현재 에이전트가 직접 실행

### Phase 4: Subagent-Driven Development

**핵심 원칙**: Fresh subagent per task + Two-stage review

전체 프로세스 흐름:

```
플랜 읽기 → TodoWrite 생성
    ↓
태스크별 반복:
  implementer 서브에이전트 파견
    ↓ 질문 응답
  구현 + 테스트 + 커밋 + 셀프리뷰
    ↓
  spec-reviewer → [미준수 시 수정 반복]
    ↓
  code-quality-reviewer → [품질 이슈 수정 반복]
    ↓
  태스크 완료 표시
    ↓
전체 완료 → final code reviewer → finishing-a-development-branch
```

**병렬 구현 서브에이전트 금지**: 파일 충돌 위험으로 구현 서브에이전트의 병렬 실행은 명시적으로 금지됨. dispatching-parallel-agents 스킬은 완전히 독립된 태스크에만 사용.

### Phase 5: TDD

별도 섹션(6번)에서 상세 분석.

### Phase 6: Code Review

**타이밍**: 각 태스크 완료 후(SDD), major feature 완료 후, main 브랜치 병합 전

**방법**: git SHA 기반으로 code-reviewer 서브에이전트에 정밀 컨텍스트 전달. SHA를 명시하면 리뷰 범위가 명확해져 노이즈가 줄어든다.

이슈 심각도 분류:

| 등급 | 처리 | 예시 |
|------|------|------|
| Critical | 즉시 수정, 진행 중단 | 보안 취약점, 데이터 손실 위험 |
| Important | 진행 전 수정 | 로직 오류, API 계약 위반 |
| Minor | 나중에 처리 | 스타일, 최적화 제안 |

**receiving-code-review 스킬**: 피드백 무비판적 수용 금지. 기술적 근거 없는 변경 요청은 반박하도록 명시되어 있다.

### Phase 7: Branch Completion

4가지 옵션 제시:

| 옵션 | 내용 | Worktree 정리 |
|------|------|--------------|
| 1. 로컬 병합 | 현재 저장소에 직접 병합 | 자동 정리 |
| 2. PR 생성 | GitHub/GitLab PR 생성 | 유지 |
| 3. 현재 유지 | 브랜치 그대로 보존 | 유지 |
| 4. 폐기 | "discard" 타이핑 확인 후 삭제 | 자동 정리 |

폐기 옵션에서 `"discard"` 타이핑 요구는 실수 방지 안전장치다.

---

## 5. 서브에이전트 아키텍처

### 5.1 컨텍스트 격리 원칙

v5.0.2에서 강화된 핵심 원칙: **서브에이전트에게 세션 히스토리 전달 금지**.

대신 필요한 컨텍스트만 정밀하게 구성:
- 태스크 전문 텍스트
- 장면 설정 (Scene-setting): 현재 프로젝트 상태, 관련 파일 내용
- 코드 조직 원칙

이유: 전체 세션 히스토리를 전달하면 (1) 토큰 낭비, (2) 관련 없는 컨텍스트로 인한 혼란, (3) 서브에이전트의 결정이 세션 히스토리에 오염될 위험이 있다.

### 5.2 서브에이전트 상태 모델

| 상태 | 의미 | 오케스트레이터 대응 |
|------|------|-------------------|
| `DONE` | 태스크 완료 | 다음 단계 진행 |
| `DONE_WITH_CONCERNS` | 완료했으나 우려사항 있음 | 우려사항 검토 후 결정 |
| `NEEDS_CONTEXT` | 추가 정보 필요 | 컨텍스트 보완 후 재파견 |
| `BLOCKED` | 진행 불가 | 에스컬레이션 처리 |

에스컬레이션 조건 (BLOCKED 보고 시점):
- 아키텍처 결정이 필요한 경우
- 태스크 내용을 이해할 수 없는 경우
- 결과에 불확실성이 높은 경우
- 코드 재구성이 필요한 경우
- 파일 탐색이 무한루프에 빠진 경우

### 5.3 2단계 리뷰 프로세스

구현 완료 후 두 개의 독립 리뷰어 서브에이전트를 순차 실행:

```
구현 완료
    ↓
spec-reviewer (스펙 준수 검증)
    → 미준수 항목 발견 → 수정 반복 (최대 3회)
    ↓
code-quality-reviewer (코드 품질 검증)
    → 품질 이슈 발견 → 수정 반복 (최대 3회)
    ↓
태스크 완료
```

v5.0.4에서 중요한 변경: 리뷰를 **청크별이 아닌 전체 1회**로 변경하여 토큰 최적화. 리뷰어 판단 기준도 강화됨.

### 5.4 모델 선택 전략

| 작업 유형 | 추천 모델 | 예시 |
|----------|----------|------|
| 1-2파일 기계적 작업 | cheap (Haiku 등) | 보일러플레이트, 단순 변환 |
| 멀티파일 통합 | standard (Sonnet 등) | 기능 구현, 리팩토링 |
| 아키텍처/리뷰 | most capable (Opus 등) | 설계 결정, 코드 리뷰 |

이 전략은 비용 최적화와 품질 균형을 동시에 달성한다.

---

## 6. TDD 강제 메커니즘 상세

### Iron Law

> "NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST"

단순 권고가 아닌 **삭제 규칙**으로 강제된다: 코드 먼저 작성 시 해당 코드를 삭제하고 재시작. "Delete means delete" — 수정, 리팩토링이 아닌 완전 삭제.

### RED-GREEN-REFACTOR 사이클 상세

**RED 단계**:
- 테스트 작성
- 테스트 실행 → 실패 확인 필수
- 왜 실패했는지 이유 확인 (단순 실패 확인 아님)

**GREEN 단계**:
- 최소한의 코드만 작성 (YAGNI)
- 과잉 구현 금지
- 테스트를 통과시키는 가장 단순한 구현

**REFACTOR 단계**:
- 모든 테스트 유지하며 코드 정리
- 새로운 기능 추가 금지

각 단계에서 **실제 명령어 실행 후 출력 확인** 필수. 가정만으로 진행 불가.

### 합리화 표 (11가지 핑계)

testing-anti-patterns.md에 수록된 대표 안티패턴:
- 모의 동작(Mock behavior) 테스트: 실제 동작 대신 Mock이 특정 메서드를 호출했는지 테스트
- 프로덕션 클래스에 테스트 전용 메서드 추가
- 테스트에서만 사용되는 생성자 파라미터

합리화 표 예시 (SKILL.md 내 형식):

| 핑계 | 현실 반박 |
|------|----------|
| "이건 너무 단순해서 테스트 필요 없어" | 단순한 코드가 가장 많이 변경됨 |
| "시간이 없어" | 나중에 디버깅하는 시간이 더 걸림 |
| "레거시 코드라 테스트 작성이 어려워" | 어렵기 때문에 더 테스트가 필요함 |

---

## 7. 테스트 인프라

Superpowers 자체가 테스트 스위트를 갖추고 있다는 점이 독특하다. 프레임워크가 의도한 대로 동작하는지 검증하는 메타 테스트다.

| 디렉토리 | 내용 | 수량 |
|----------|------|------|
| `tests/explicit-skill-requests/` | 스킬 명시적 요청 시나리오 | 9개 |
| `tests/skill-triggering/` | 자동 트리거 검증 | 6개 스킬 |
| `tests/subagent-driven-dev/` | 통합 테스트 (Go fractal, Svelte Todo) | 2개 |
| `tests/brainstorm-server/` | WebSocket 프로토콜, 윈도우 라이프사이클 | - |
| `tests/claude-code/` | 스킬 실행 분석 스크립트, 토큰 사용량 분석 | - |

`tests/claude-code/` 의 토큰 사용량 분석 스크립트가 특히 흥미롭다. 스킬 로딩이 컨텍스트 윈도우에 미치는 영향을 정량적으로 측정한다. 이는 "자주 로드되는 스킬 150단어 이하" 제한의 근거가 된다.

통합 테스트에서 Go fractal과 Svelte Todo를 선택한 이유: 두 프로젝트 모두 (1) 언어/프레임워크가 다르고, (2) 테스트 인프라가 명확하고, (3) 구현 복잡도가 적당하기 때문이다.

---

## 8. 최신 변경사항 (v5.0.x, 최근 3주)

| 버전 | 날짜 | 주요 변경 |
|------|------|----------|
| v5.0.5 | 2026-03-17 | 서버 ESM 모듈 수정, 실행 방식 선택 복원 (강제 → 선택) |
| v5.0.4 | 2026-03-16 | 리뷰 루프 토큰 최적화 (청크별 → 전체 1회), 리뷰어 기준 강화 |
| v5.0.3 | 2026-03-15 | Cursor 지원 (hooks-cursor.json 추가), `--resume` 훅 재주입 버그 수정 |
| v5.0.2 | 2026-03-11 | Zero-dep Brainstorm Server (Node.js 내장 모듈만), 컨텍스트 격리 강화 |
| v5.0.1 | 2026-03-10 | Gemini CLI 지원 (GEMINI.md + gemini-extension.json), agentskills.io 호환 |

**주목할 변경**: v5.0.5에서 SDD 실행 방식이 "Subagent-Driven 강제"에서 "Subagent-Driven(권장) vs Inline Execution(선택)"으로 복원되었다. 소규모 작업에서 서브에이전트 오버헤드가 과도하다는 피드백을 반영한 것으로 보인다.

**플랫폼 지원 확장 속도**: v5.0.1(Gemini) → v5.0.3(Cursor) → v5.0.4(OpenCode) 순으로 2주 안에 4개 플랫폼 지원. 활발한 개발 속도.

---

## 9. 핵심 설계 철학 정리

| 철학 | 구현 방식 |
|------|----------|
| **규율이 자유를 만든다** | HARD-GATE, Iron Law, "Delete means delete" 등 강제 규칙 |
| **컨텍스트 오염 방지** | 서브에이전트 격리, @ 링크 금지, 필요한 컨텍스트만 정밀 전달 |
| **단계적 검증** | 각 Phase 완료 후 다음 Phase 진입, 리뷰 루프 내재화 |
| **YAGNI** | Brainstorming과 TDD 모두에서 과잉 구현을 명시적으로 차단 |
| **토큰 경제** | 150단어 제한, 청크별 리뷰 → 전체 1회, 온디맨드 로딩 |
| **메타 규율** | 스킬 작성에도 TDD 적용, 테스트 인프라로 프레임워크 자체 검증 |

가장 독특한 점은 **에이전트의 합리화를 예측하고 선제적으로 차단**하는 설계다. 합리화 표, Red Flags 목록, "예외 없음" 명시 등이 모두 에이전트가 규칙을 우회하려는 경향을 막기 위한 장치다. 이는 일반적인 프롬프트 엔지니어링을 넘어서 에이전트 행동 패턴에 대한 깊은 이해에서 나온다.

---

## 10. 한계 및 약점

| 항목 | 내용 | 영향도 |
|------|------|--------|
| **오버헤드** | 소규모 작업에서도 전체 Phase를 거쳐야 함. v5.0.5에서 일부 완화했으나 여전히 존재 | 중간 |
| **훅 의존성** | SessionStart 훅 미지원 플랫폼에서는 자동 주입이 작동하지 않음. 수동 스킬 로딩 필요 | 높음 |
| **서브에이전트 비용** | 태스크마다 새 서브에이전트 생성으로 API 호출 비용 증가 | 중간 |
| **토큰 상한** | 복잡한 프로젝트에서 스킬 컨텍스트 + 코드베이스 컨텍스트가 윈도우 초과 위험 | 중간 |
| **TDD 강제의 경직성** | 레거시 코드 통합, 외부 API 연동 등 테스트 작성이 구조적으로 어려운 상황에서도 예외 없음 | 낮음~중간 |
| **스킬 버전 관리** | 프로젝트 로컬 스킬이 플러그인 기본 스킬을 덮으면 Superpowers 업데이트가 반영되지 않음 | 낮음 |
| **플랫폼 파편화** | hooks.json, hooks-cursor.json, GEMINI.md, gemini-extension.json 등 플랫폼별 설정 파일 관리 부담 | 낮음 |

**v4.3.1 대비 주요 개선 (task-328.1 이후)**:
- 서브에이전트 컨텍스트 격리 명시화 (v5.0.2)
- Cursor/Gemini CLI 지원 추가 (v5.0.1, v5.0.3)
- Zero-dep Brainstorm Server (v5.0.2)
- 실행 방식 선택권 복원 (v5.0.5)

전반적으로 Superpowers는 "에이전트를 믿지 말고 프로세스를 신뢰하라"는 철학을 코드로 구현한 프레임워크다. 팀 내 도입 시 초기 학습 비용이 있으나, 대규모 기능 개발에서 품질 일관성을 확보하는 데 유효한 도구로 평가한다.