Superpowers(Agentic Skills Framework)

• Superpowers는 AI 코딩 에이전트를 위한 composable skills 기반 소프트웨어 개발 워크플로우 플러그인
• 에이전트가 코드를 바로 작성하지 않고, 체계적인 프로세스(브레인스토밍 → 설계 → 플랜 → 구현 → 리뷰)를 자동으로 따르게 강제하는 행동 제어 시스템
• Jesse Vincent과 Prime Radiant 팀이 만든 오픈소스 서드파티 플러그인 (MIT 라이센스)
• Claude Code, Cursor, Codex, OpenCode, GitHub Copilot CLI, Gemini CLI 등 멀티 하네스(multi-harness) 지원
• oh-my-claudecode과 같은 범주의 플러그인이지만, Claude Code 전용이 아닌 멀티 플랫폼 배포가 특징

해당 개념이 필요한 이유

• AI 코딩 에이전트는 지시를 받으면 바로 코드를 작성하려는 경향이 있어, 설계 없이 구현에 돌입하면 품질이 떨어짐
• 테스트 없이 코드를 작성하거나, 검증 없이 “완료”라고 주장하는 등 에이전트의 나쁜 습관을 교정할 필요가 있음
• 복잡한 작업을 2-5분짜리 bite-sized task로 분해하고, 각 task마다 서브에이전트를 dispatch하는 체계적 접근이 필요
• 에이전트가 스스로 합리화(rationalization)하여 프로세스를 건너뛰는 것을 명시적으로 차단하는 메커니즘이 필요

AS-IS

sequenceDiagram
    autonumber
    actor User
    participant Agent as AI Agent
    participant Code as Codebase

    User->>Agent: "이 기능 만들어줘"
    Agent->>Code: 바로 코드 작성 시작
    Agent->>Code: 테스트 없이 구현
    Agent->>User: "완료했습니다!" (검증 없음)
    User->>Code: 직접 확인 → 버그 발견
    User->>Agent: "이거 안 되는데?"
    Agent->>Code: 추측 기반 수정 (guess-and-check)
    Note over Agent,Code: 반복... 시간 낭비

TO-BE

sequenceDiagram
    autonumber
    actor User
    participant Agent as Superpowers Agent
    participant Sub as Subagent
    participant Code as Codebase

    User->>Agent: "이 기능 만들어줘"
    Agent->>User: 브레인스토밍 질문 (한 번에 하나씩)
    User->>Agent: 답변 + 피드백
    Agent->>Agent: 설계 문서 작성 + 유저 승인
    Agent->>Agent: 구현 플랜 작성 (bite-sized tasks)
    Agent->>Sub: Task 1 dispatch (TDD 강제)
    Sub->>Code: RED → GREEN → REFACTOR
    Sub->>Agent: 완료 보고
    Agent->>Sub: Spec 준수 리뷰 dispatch
    Agent->>Sub: 코드 품질 리뷰 dispatch
    Agent->>Sub: Task 2 dispatch...
    Note over Agent,Code: 모든 task 완료 후 최종 검증
    Agent->>User: 머지/PR 옵션 제시

Plugin / Skill / Agent / Harness 계층 구조

Superpowers 생태계에서 이 네 용어는 서로 다른 계층이다.

계층	의미	예시
Harness	에이전트를 실행하는 플랫폼/환경	Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot CLI
Agent	Harness 위에서 실행되는 AI 에이전트 인스턴스	Claude (main agent), code-reviewer subagent
Skill	에이전트의 행동을 제어하는 개별 지침 문서	brainstorming, TDD, systematic-debugging (14개)
Plugin	여러 skill + agent + hook + command를 묶어서 배포하는 패키지	Superpowers 자체가 이것

Superpowers는 Plugin이다. 14개 skill, 1개 agent config, hook, command를 하나로 묶은 패키지.

superpowers/                  ← Plugin (배포 단위)
├── .claude-plugin/           ← Claude Code용 설정
├── .cursor-plugin/           ← Cursor용 설정
├── .codex/                   ← Codex용 (INSTALL.md)
├── .opencode/                ← OpenCode용
├── GEMINI.md                 ← Gemini CLI용
├── gemini-extension.json     ← Gemini CLI 확장
├── skills/                   ← 14개 Skill (행동 제어 문서)
│   ├── brainstorming/
│   ├── test-driven-development/
│   ├── subagent-driven-development/
│   └── ...
├── agents/                   ← 1개 Agent config
│   └── code-reviewer.md
├── commands/                 ← 유저가 호출 가능한 명령어
│   ├── brainstorm.md
│   ├── write-plan.md
│   └── execute-plan.md
└── hooks/                    ← 자동 실행되는 트리거
    ├── hooks.json            ← Claude Code/Codex hook
    └── hooks-cursor.json     ← Cursor hook

oh-my-claudecode은 Claude Code 전용 플러그인인 반면, Superpowers는 하네스마다 스킬 로딩 방식이 다르기 때문에 (Claude Code는 Skill tool, Gemini CLI는 activate_skill tool, Codex는 URL fetch 방식) 각 플랫폼에 맞는 어댑터를 제공한다.

핵심 워크플로우 7단계

Superpowers의 워크플로우는 7개의 스킬이 순차적으로 자동 활성화되며 진행된다.

1단계: Brainstorming (브레인스토밍)

코드 작성 전에 반드시 발동되는 설계 탐색 단계. 에이전트가 바로 구현에 뛰어드는 것을 차단하는 HARD-GATE가 걸려 있다.

핵심 규칙:

• 한 번에 질문 하나씩 (multiple choice 선호)
• 2-3개 접근법을 trade-off와 함께 제안
• 설계를 섹션별로 나눠서 점진적으로 승인
• “이건 너무 간단해서 설계가 필요 없어”라는 판단 금지 — 모든 프로젝트에 적용
• Visual Companion(브라우저 기반 목업/다이어그램) 선택적 제공
• 설계 완료 후 → docs/superpowers/specs/ 에 저장 → Spec Self-Review → 유저 리뷰 → writing-plans 스킬로 전환

2단계: Using Git Worktrees (격리 워크스페이스)

설계 승인 후, 메인 브랜치를 오염시키지 않기 위해 Git Worktree로 격리된 작업 공간을 생성한다.

프로세스:

1. 기존 .worktrees/ 또는 worktrees/ 디렉토리 확인
2. .gitignore에 포함 여부 검증 (포함 안 되어 있으면 즉시 추가)
3. git worktree add 로 새 브랜치와 함께 워크트리 생성
4. 프로젝트 셋업 자동 감지 (npm install, cargo build 등)
5. 테스트 실행하여 clean baseline 확인

3단계: Writing Plans (구현 플랜 작성)

“열정적이지만 맥락이 없고, 판단력이 부족하며, 테스트를 싫어하는 주니어 엔지니어” 도 따를 수 있을 만큼 상세한 플랜을 작성한다.

Task 단위는 2-5분짜리 한 동작:

• “실패하는 테스트 작성” — 한 step
• “테스트 실행해서 실패 확인” — 한 step
• “테스트를 통과하는 최소 코드 구현” — 한 step
• “테스트 실행해서 통과 확인” — 한 step
• “커밋” — 한 step

철저한 No Placeholder 정책: “TBD”, “TODO”, “implement later”, “Add appropriate error handling” 같은 표현 금지. 모든 step에 실제 코드와 정확한 파일 경로가 포함되어야 한다.

YAGNI: 플랜 작성의 핵심 원칙

YAGNI(You Aren’t Gonna Need It)는 Extreme Programming에서 유래한 원칙으로, **“지금 필요하지 않은 기능은 만들지 마라”**는 뜻이다. Kent Beck이 C3 프로젝트에서 동료 Chet Hendrickson이 “나중에 필요할 기능”을 제안할 때마다 “You aren’t gonna need it”이라고 반복한 데서 시작되었다.

미리 만드는 것이 왜 나쁜가 — Martin Fowler는 “미리 만든 기능(presumptive feature)“의 비용을 3가지로 분류한다:

비용 유형	설명
Build 비용	결국 안 쓸 기능을 분석, 구현, 테스트하는 데 쓴 시간
Delay 비용	그 시간에 진짜 필요한 기능을 먼저 배포했으면 얻었을 가치 (기회비용)
Carry 비용	불필요한 코드가 코드베이스 복잡도를 높여, 이후 모든 개발과 디버깅을 느리게 만드는 비용

Microsoft 연구(Kohavi et al.)에 따르면, 신중하게 계획한 기능조차 1/3만이 의도한 성과를 달성했다. 나머지 2/3는 예측이 틀렸다는 뜻이다.

Superpowers에서 YAGNI가 작동하는 방식:

Reviewer: "나중을 위해 CSV export 기능도 추가하는 게 좋겠습니다"

에이전트 (YAGNI 적용):
  → codebase grep → 이 endpoint를 호출하는 코드 없음
  → "사용되지 않는 기능입니다. 제거할까요? (YAGNI)"

• Writing Plans에서: 플랜에 “혹시 필요할” step을 넣지 않음. 현재 요구사항만 task로 분해
• Code Review에서: 리뷰어가 “proper하게 구현하라”고 제안하면, 먼저 grep으로 실제 사용 여부 확인
• TDD에서: 테스트를 통과하는 최소한의 코드만 작성. over-engineering 금지

YAGNI가 적용되지 않는 경우: 미래를 위한 구현이 지금 복잡도를 전혀 추가하지 않는다면, 굳이 피할 이유는 없다. 또한 YAGNI는 코드를 나중에 쉽게 바꿀 수 있는 malleable code(리팩토링, 자동 테스트, CI/CD)가 전제되어야 제대로 작동한다.

4단계: Subagent-Driven Development (서브에이전트 구동 개발)

각 task마다 fresh subagent를 dispatch하여 구현하고, 2단계 리뷰를 거친다.

flowchart TD
    A[Task 텍스트 + 컨텍스트 준비] --> B[Implementer Subagent Dispatch]
    B --> C{질문 있음?}
    C -->|Yes| D[컨텍스트 제공] --> B
    C -->|No| E[구현 + 테스트 + 커밋 + 셀프리뷰]
    E --> F[Spec Reviewer Subagent Dispatch]
    F --> G{Spec 준수?}
    G -->|No| H[Implementer가 수정] --> F
    G -->|Yes| I[Code Quality Reviewer Subagent Dispatch]
    I --> J{품질 통과?}
    J -->|No| K[Implementer가 수정] --> I
    J -->|Yes| L[Task 완료 → 다음 Task]

Implementer 상태 처리:

• DONE → 리뷰 진행
• DONE_WITH_CONCERNS → 우려사항 확인 후 진행
• NEEDS_CONTEXT → 추가 컨텍스트 제공 후 재dispatch
• BLOCKED → 모델 업그레이드 또는 task 분할, 필요시 human에게 escalate

모델 선택 전략: task 복잡도에 따라 cheap/standard/capable 모델을 구분 사용하여 비용 절감.

5단계: Test-Driven Development (TDD)

모든 구현에 RED-GREEN-REFACTOR 사이클을 강제한다.

Iron Law: 테스트 없이 프로덕션 코드 작성 금지

• RED: 실패하는 테스트 하나 작성 → 실패 확인 (필수)
• GREEN: 테스트를 통과하는 최소한의 코드 작성 → 통과 확인 (필수)
• REFACTOR: 중복 제거, 이름 개선, 헬퍼 추출 (테스트 green 유지)

테스트 전에 코드를 먼저 작성했다면? 삭제. “참고용”으로 보관 금지. “적응”하면서 테스트 작성 금지. 삭제 = 삭제.

합리화 방지 테이블이 내장되어 있어, 에이전트가 “이건 너무 간단해서 테스트 필요 없어”, “나중에 테스트할게”, “TDD는 교조적이야” 같은 변명을 하면 즉시 차단한다.

6단계: Requesting/Receiving Code Review (코드 리뷰)

task 사이마다 code-reviewer subagent를 dispatch하여 리뷰한다.

리뷰 요청 시:

• Git SHA 범위 지정 (BASE → HEAD)
• 구현 내용 + 플랜/요구사항을 리뷰어에게 전달
• Critical/Important/Minor 심각도로 이슈 분류

리뷰 수신 시 (receiving-code-review):

• “You’re absolutely right!” 같은 performative agreement 금지
• 외부 리뷰어 피드백은 기술적으로 검증 후 구현
• 불명확한 항목은 전부 clarify 후 진행 (부분 구현 금지)
• YAGNI 체크 — 사용되지 않는 기능 추가 제안은 거부

7단계: Finishing a Development Branch (브랜치 완료)

모든 task 완료 후 구조화된 4가지 옵션을 제시한다:

1. 로컬 머지 — base 브랜치로 merge + worktree 정리
2. PR 생성 — push + gh pr create
3. 브랜치 유지 — 나중에 처리
4. 작업 폐기 — typed “discard” 확인 필수

보조 스킬

Systematic Debugging (체계적 디버깅)

Iron Law: 근본 원인 조사 없이 수정 시도 금지

4단계 프로세스:

1. Root Cause Investigation — 에러 메시지 정독, 재현, 최근 변경사항 확인, 데이터 흐름 추적
2. Pattern Analysis — 동작하는 유사 코드와 비교, 차이점 식별
3. Hypothesis & Testing — 단일 가설, 최소 변경, 한 번에 하나씩
4. Implementation — 실패 테스트 케이스 생성 → 수정 → 검증

3회 이상 수정 실패 시 → 아키텍처 문제를 의심하고, 추가 수정 대신 human partner와 논의.

Verification Before Completion (완료 전 검증)

Iron Law: 검증 증거 없이 완료 주장 금지

• “should work now”, “looks correct” → 금지
• “Great!”, “Perfect!”, “Done!” → 검증 없이 금지
• 반드시 커맨드 실행 → 출력 확인 → 그 다음에 완료 주장

Dispatching Parallel Agents (병렬 에이전트)

2개 이상의 독립적인 문제가 있을 때, 각 문제 도메인당 하나의 에이전트를 병렬로 dispatch.

Writing Skills (스킬 작성)

스킬 작성 자체가 TDD 프로세스를 따름:

• RED: 스킬 없이 pressure scenario 실행 → 에이전트의 실패 행동 기록
• GREEN: 해당 실패를 교정하는 최소한의 스킬 문서 작성
• REFACTOR: 에이전트가 찾는 새로운 합리화 루프홀을 반복적으로 차단

아키텍처와 설계 철학

Zero-Dependency 설계

외부 의존성 없는 순수 텍스트 기반 플러그인. Shell(58.8%), JavaScript(29.6%), HTML(4.3%), Python(3.7%), TypeScript(2.8%)로 구성.

Skill = 행동을 제어하는 코드

스킬은 단순한 문서가 아니라 에이전트의 행동을 제어하는 코드로 취급된다. 수정 시 TDD와 adversarial pressure testing이 필수이며, 94%의 PR이 거부될 만큼 엄격한 품질 기준을 적용한다.

”Human Partner” 용어

의도적으로 “user” 대신 “human partner”를 사용. 에이전트가 인간을 단순한 사용자가 아닌 협업 파트너로 인식하도록 유도하는 행동 제어 장치.

합리화 방지 패턴

모든 discipline 스킬에 공통적으로 적용되는 3가지 방어 메커니즘:

1. Iron Law — 절대 어길 수 없는 핵심 규칙 (e.g., “테스트 없이 코드 금지”)
2. Rationalization Table — 에이전트가 사용할 변명과 그에 대한 반박을 미리 테이블로 작성
3. Red Flags List — “이런 생각이 들면 STOP하라”는 자가 점검 목록

Claude Search Optimization (CSO)

스킬의 description 필드는 언제 사용하는지만 기술하고, 무엇을 하는지/어떻게 하는지는 기술하지 않음. 테스트 결과, description에 워크플로우를 요약하면 에이전트가 스킬 본문을 읽지 않고 description만 따르는 문제가 발견되었기 때문.

참고 문서

• GitHub Repository
• Superpowers Blog Post
• Discord Community
• Agent Skills Specification
• Prime Radiant
• Martin Fowler - YAGNI