새소식
300x250
AI/Skills
"하네스 엔지니어링" - Superpowers 리뷰 : 7단계 워크플로우와 14개 스킬 라이브러리 - 브레인스토밍부터 코드리뷰까지
- -
728x90
안녕하세요! 갓대희 입니다.
AI 코딩 에이전트를 쓰다 보면 비슷한 불만들이 쌓인다.
브레인스토밍도 없이 코드부터 쏟아내거나, 테스트는 나중으로 미루거나, 작업이 끝나도 정리됐는지 확인하지 않는다.
결국 에이전트를 감시하는 시간이 에이전트를 쓰는 시간보다 더 길어진다.
Superpowers는 이 문제를 에이전트 동작 자체를 바꾸는 방식으로 해결하고자 한다.
Shell 스크립트 기반의 "스킬 프레임워크"로, Claude Code·Cursor·Codex·OpenCode·GitHub Copilot CLI·Gemini CLI에 설치하면 에이전트가 브레인스토밍 → 플랜 작성 → TDD → 코드 리뷰 → 브랜치 마무리로 이어지는 7단계 워크플로우를 따르게 된다.
이 글은 각 스킬이 어떻게 동작하는지 코드를 따라가며 직접 확인한다.
목차
- Superpowers란 무엇인가 — 핵심 가치와 비교
- 플랫폼별 설치 가이드
- 7단계 워크플로우 상세 — SKILL.md 기반 예시 포함
- 기술 아키텍처 분석
- 스킬 라이브러리 전체 목록 14개
- 실전 시나리오 — JWT 인증 추가 end-to-end
- GeekNews 한국 커뮤니티 반응 + Cialdini 스토리
- 제한사항 및 주의사항
- 트러블슈팅 Q&A
1. Superpowers란 무엇인가
공식 README에서는 Superpowers를 이렇게 정의한다.
"Superpowers is a complete software development workflow for your coding agents, built on top of a set of composable 'skills' and some initial instructions that make sure your agent uses them."
(Superpowers는 코딩 에이전트를 위한 종합적인 소프트웨어 개발 워크플로우로, 여러 개의 조합 가능한 skills와 에이전트가 이를 올바르게 활용하도록 돕는 초기 지침 위에 구축되어 있습니다.)
에이전트를 위한 스킬 모음이 아니라, 에이전트가 어떻게 행동해야 하는지를 정의하는 방법론 자체라는 뜻이다.
코드를 잘 짜는 방법이 아니라, 좋은 개발 습관을 에이전트에게 강제하는 틀이라고 보는게 더 맞다.
구체적으로는 이렇게 동작한다. 에이전트가 무언가를 빌드하기 시작하는 순간, 코드부터 쓰는 대신 뒤로 물러서서 실제로 무엇을 만들어야 하는지 먼저 물어본다. 스펙이 완성되면 "테스트를 싫어하고, 프로젝트 컨텍스트도 없고, 판단력도 부족한 열정적인 주니어 엔지니어도 따를 수 있을 만큼 명확한" 구현 플랜을 만든다. 이후 플랜대로 실행하고, 리뷰하고, 정리한다.
기본 정보 (2026-04-14 기준)
| 항목 | 내용 |
|---|---|
| 저장소 | github.com/obra/superpowers |
| 버전 | v5.0.7 (2026-03-31 릴리스) |
| 언어 | Shell |
| 라이선스 | MIT |
| Stars | 150,374 (2026-04-14 기준 스냅샷, 실시간 변동) |
| Forks | 13,005 |
| 저자 | Jesse Vincent (obra, Prime Radiant) |
| 최초 공개 | 2025-10-09 |
Stars 수치는 GitHub API 직접 조회 기준 스냅샷이며 실시간으로 변동한다.
대안 도구 비교
| 항목 | Superpowers | 일반 시스템 프롬프트 | 전용 에이전트 프레임워크 |
|---|---|---|---|
| 설치 방식 | 플러그인/Extension | 직접 붙여넣기 | 프레임워크마다 상이 |
| 외부 의존성 | - | - | 있는 경우가 많음 |
| 지원 플랫폼 | 6개+ | 모든 LLM | 특정 플랫폼 |
| 워크플로우 강제 | HARD-GATE 패턴 | 미지원 | 부분 지원 |
| 업데이트 | /plugin update 한 줄 |
수동 | 패키지 매니저 |
| 오픈소스 | MIT | 해당 없음 | 다양함 |
한 줄로 요약하자면, 일반 시스템 프롬프트는 행동 지침을 제안하지만, Superpowers는 그 지침의 실행을 강제한다.
2. 플랫폼별 설치 가이드
설치 검증은 모든 플랫폼에서 공통이다.
설치 완료 후 새 세션을 시작하고 "help me plan this feature" 또는 "let's debug this issue"처럼 스킬을 트리거하는 프롬프트를 입력한다.
에이전트가 자동으로 관련 Superpowers 스킬을 호출하면 설치가 성공한 것이다.
Claude Code (공식 마켓플레이스 — 권장)
Claude Code 공식 플러그인 마켓플레이스에 등재되어 있어 가장 간단하다. (claude.com/plugins/superpowers)
/plugin install superpowers@claude-plugins-official
마켓플레이스 직접 등록 경로도 지원한다.
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace
ex) 전역으로 난 user scope으로 진행
업데이트는 한 줄이다. 스킬도 자동으로 함께 업데이트된다.
/plugin update superpowers
Cursor
Cursor Agent 채팅 창에서 바로 실행한다.
/add-plugin superpowers또는 플러그인 마켓플레이스에서 "superpowers"를 검색하여 설치한다.
Codex
Codex에게 직접 지시하는 방식이 가장 간단하다.
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md서브에이전트 기반 스킬(dispatching-parallel-agents, subagent-driven-development)을 사용하려면 설정 파일에 다음을 추가한다.
[features]
multi_agent = true
OpenCode
opencode.json에 한 줄을 추가하고 재시작한다. 플러그인 자동 설치와 스킬 등록이 동시에 이루어진다.
{
"plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]
}
GitHub Copilot CLI (v5.0.7 신규 지원)
v5.0.7에서 GitHub Copilot CLI 지원이 추가되었다. (릴리스 노트)
copilot plugin marketplace add obra/superpowers-marketplace
copilot plugin install superpowers@superpowers-marketplace
Gemini CLI
# 설치
gemini extensions install https://github.com/obra/superpowers
# 업데이트
gemini extensions update superpowers브라우저(웹) 환경 주의: 위 설치 방법은 CLI/데스크톱 클라이언트 기준이다.
Claude.ai 브라우저 인터페이스는 현재 플러그인 설치를 지원하지 않으므로, Superpowers를 사용하려면 Claude Code CLI 또는 지원되는 에디터 환경이 필요하다. (README)
3. 7단계 워크플로우 상세
Superpowers는 7단계 워크플로우로 돌아간다.
각 단계는 별도 SKILL.md 파일로 정의되어 있고, 에이전트가 상황을 감지하면 자동으로 해당 스킬을 호출한다.
각 단계의 SKILL.md 원문을 기반으로 설명하고, 따라할 수 있는 예시를 함께 붙였다.
Step 1 — brainstorming: 코드 전에 설계 먼저
트리거 조건: 기능 구현, 컴포넌트 빌드, 동작 수정 등 모든 구현 작업을 시작하기 전
brainstorming 스킬의 핵심은 HARD-GATE 패턴이다. brainstorming/SKILL.md에 이렇게 명시되어 있다.
<HARD-GATE>
Do NOT invoke any implementation skill, write any code, scaffold any project,
or take any implementation action until you have presented a design and
the user has approved it. This applies to EVERY project regardless of
perceived simplicity.
</HARD-GATE>번역 : 설계안을 먼저 제시하고 사용자의 승인을 받기 전까지는, 구현용 skill 호출, 코드 작성, 프로젝트 스캐폴딩, 기타 구현 작업을 일절 진행하지 마세요. 이 규칙은 프로젝트가 아무리 단순해 보여도 모든 프로젝트에 동일하게 적용됩니다.
사용자 승인 없이는 구현 단계로 절대 진입할 수 없다. "이건 너무 간단해서 설계가 필요 없어"라는 합리화도 허용하지 않는다. SKILL.md는 명시한다: "Simple 프로젝트야말로 검토되지 않은 가정이 가장 많은 낭비를 만드는 곳이다."
9단계 체크리스트로 진행한다.
- 프로젝트 컨텍스트 탐색 (파일, 문서, 최근 커밋 확인)
- 비주얼 컴패니언 제안
- 명확화 질문 (한 번에 1개씩)
- 2-3가지 접근 방식 + 트레이드오프 + 권장안 제시
- 설계 발표 (섹션별로, 각 섹션마다 승인 요청)
- 설계 문서를
docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md에 저장 후 커밋 - 스펙 자기 검토 (플레이스홀더, 모순, 모호함 확인)
- 사용자 리뷰
- writing-plans 스킬로 전환
예시 프롬프트: "FastAPI에 JWT 인증 기능을 추가하고 싶어."
기대 결과: 에이전트가 바로 코드를 쓰는 대신 프로젝트를 탐색한 뒤, JWT 방식 / Session 방식 / OAuth2 외부 서비스 3가지 접근법과 각각의 트레이드오프를 제시한다. 선택 완료 후 설계 문서를 저장하고 커밋한다.
ex) 물론 명시적으로 호출 해도 된다.
- 이후 몇가지 질문 완료 후 디자인 문서 작업 시작 ( 세 섹션 모두 승인됐습니다. 디자인 문서를 작성하겠습니다. )
Step 2 — using-git-worktrees: 격리된 작업 공간 생성
트리거 조건: 설계 승인 후, 구현 플랜 실행 전
기능 작업을 메인 브랜치와 격리하여 진행한다. using-git-worktrees/SKILL.md는 디렉토리 선택 우선순위 알고리즘을 정의한다.
- 기존 디렉토리 확인:
ls -d .worktrees→.worktrees가 우선,worktrees가 대안 - CLAUDE.md에서
grep -i 'worktree.*director'확인 - 둘 다 없으면 사용자에게 질문:
.worktrees/또는~/.config/superpowers/worktrees/<project-name>/
안전 검증 단계가 핵심이다. 디렉토리 생성 전에 .gitignore 확인이 강제된다.
git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
무시 목록에 없으면 Jesse의 규칙("망가진 건 즉시 고친다")에 따라 .gitignore에 추가하고 커밋한 뒤 워크트리를 생성한다. 워크트리 내용이 실수로 커밋되는 것을 방지하기 위한 설계다.
워크트리 생성 패턴은 다음과 같다.
git worktree add .worktrees/feature/jwt-auth -b feature/jwt-auth
예시 프롬프트: "설계가 승인됐어. 이제 작업 시작하자."
기대 결과: 새 브랜치와 함께 격리된 워크트리를 생성하고, Python이면 pip install -r requirements.txt, Node면 npm install을 자동 실행한다. 이후 기존 테스트 전체가 통과하는지 베이스라인 검증을 수행한다.
Step 3 — writing-plans: 실행 가능한 플랜 작성
트리거 조건: 승인된 설계가 있을 때, 코드 작성 전
writing-plans/SKILL.md는 플랜 문서의 헤더 템플릿을 강제한다.
# [Feature Name] Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development
> (recommended) or superpowers:executing-plans
**Goal:** [한 문장]
**Architecture:** [2-3 문장]
**Tech Stack:** [핵심 기술]
각 태스크는 2-5분 단위의 단일 액션으로 구성된다. SKILL.md의 예시다.
### Task 1: 실패하는 테스트 작성
- `tests/test_auth.py` 생성
- `POST /auth/token` 엔드포인트 존재 여부 테스트
- `pytest tests/test_auth.py` 실행하여 FAIL 확인
### Task 2: 최소 라우터 구현
- `app/routers/auth.py` 생성
- OAuth2PasswordBearer 스켈레톤만 구현
TBD, TODO, "위와 유사", "나중에 구현" 같은 플레이스홀더는 플랜 실패 조건이다. 파일 구조 원칙도 명시한다: 단일 책임, 경계가 명확한 인터페이스, 함께 변경되는 파일은 함께 위치.
예시 프롬프트: "JWT 인증 설계 문서를 바탕으로 구현 플랜을 만들어줘."
기대 결과: 각 태스크에 정확한 파일 경로, 완전한 코드 스니펫, 검증 명령어가 포함된 플랜 파일이 저장된다. 반복되는 태스크라도 완전한 코드를 다시 작성해야 한다.
ex) Step1의 작업을 계속 이어 계획을 생성한다. 이번엔 명시적 호출을 진행하지 않았다.
- 계획 문서 작성 완료 > 실행 방식은 Step4에서 진행
Step 4 — subagent-driven-development / executing-plans: 플랜 실행
트리거 조건: 플랜이 준비된 후
subagent-driven-development/SKILL.md는 태스크당 fresh 서브에이전트를 디스패치하여 2단계 리뷰(스펙 준수 검토 → 코드 품질 검토)를 거친다. 서브에이전트가 독립된 컨텍스트로 실행되기 때문에 이전 세션의 편향이 없다.
SKILL.md의 표현: "They should never inherit your session's context or history — you construct exactly what they need."
executing-plans는 같은 세션 내에서 태스크를 순차 실행하는 방식이다. 서브에이전트를 디스패치하지 않으므로 컨텍스트 분리 효과가 없다. SKILL.md의 실제 분기 기준은 "현재 세션에 머물 것인가 / 별도 에이전트로 분리할 것인가"이며, 플랫폼 기능 부재의 대체제가 아니다.
어떤 방식을 쓸지 결정할 때 참고할 매트릭스는 다음과 같다.
| 상황 | 권장 방식 |
|---|---|
| Claude Code 또는 Codex(multi_agent=true) 환경 | subagent-driven-development |
| 서브에이전트로 컨텍스트 분리하여 실행 | subagent-driven-development |
| 같은 세션 내 순차 실행 원함 | executing-plans |
| 태스크가 상호 의존성이 강함 | executing-plans |
subagent-driven-development를 사용하면 Claude가 2-3시간 자율 작업도 가능하다.
서브에이전트 지원 플랫폼: Claude Code와 Codex(multi_agent = true 설정 필요)는 서브에이전트 디스패치를 지원한다. Cursor, OpenCode, Gemini CLI는 현재 서브에이전트 디스패치를 지원하지 않으므로, 이 플랫폼에서는 subagent-driven-development 대신 executing-plans(같은 세션 내 순차 실행)를 사용한다.
예시 프롬프트: "플랜대로 실행해줘."
기대 결과: 각 태스크를 독립된 서브에이전트가 처리한다. 태스크 완료 후 스펙 준수 여부 → 코드 품질 순으로 2단계 리뷰를 수행하고 결과를 보고한다.
ex) subagent-drive 방식으로 진행
Step 5 — test-driven-development: 테스트 우선 개발
트리거 조건: 구현 중 모든 기능 추가·버그 픽스 시
test-driven-development/SKILL.md는 철칙을 이렇게 정의한다.
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST테스트 없이 작성된 코드가 있다면 삭제하고 처음부터 다시 시작한다.
SKILL.md의 표현 그대로다: "Write code before the test? Delete it. Start over. No exceptions: Don't keep it as 'reference' / Don't 'adapt' it while writing tests / Delete means delete."
RED-GREEN-REFACTOR 사이클은 다음 5단계로 진행된다.
- RED: 실패하는 테스트 1개 작성
- Verify RED: 실패 확인 — 필수, 절대 건너뛰지 않음 ("테스트가 실패하는 것을 보지 않으면, 올바른 것을 테스트하는지 알 수 없다")
- GREEN: 테스트를 통과하는 최소 코드 작성
- Verify GREEN: 통과 확인
- REFACTOR: 중복 제거, 이름 개선, 헬퍼 추출 (GREEN 상태에서만)
적용 범위는 새 기능, 버그 픽스, 리팩토링, 동작 변경 모두 포함한다. 예외(프로토타입, 생성된 코드, 설정 파일)는 사람 파트너에게 먼저 물어보도록 SKILL.md가 명시한다. "'이번 한 번만 TDD를 건너뛰자'는 생각이 든다면 — 멈춰라. 그건 합리화다."
예시 프롬프트: "로그인 실패 시 401을 반환하는 기능을 추가해줘."
기대 결과: 먼저 잘못된 자격증명으로 POST /auth/token을 호출했을 때 401을 기대하는 테스트를 작성하고 실행해 실패를 확인한다. 그 후 최소 구현을 추가해 테스트를 통과시킨다.
Step 6 — requesting-code-review: 2단계 코드 리뷰
트리거 조건: 각 태스크 사이, 주요 기능 완성 후, main 브랜치 머지 전
requesting-code-review/SKILL.md는 code-reviewer 서브에이전트를 디스패치하여 스펙 준수 검토 → 코드 품질 검토 2단계로 진행한다. 서브에이전트는 세션 히스토리를 상속받지 않고, 정확히 필요한 컨텍스트만 받아 독립적으로 평가한다.
BASE_SHA=$(git rev-parse HEAD~1) # 또는 origin/main
HEAD_SHA=$(git rev-parse HEAD)심각도별 이슈 분류 후 대응 방침:
- Critical: 즉시 수정, 다음 태스크 진행 차단
- Important: 다음 단계 진행 전 수정
- Minor: 나중에 처리 가능
예시 프롬프트: "인증 태스크 완료 후 코드 리뷰 해줘."
기대 결과: 변경된 파일의 diff를 분석해 보안 취약점(예: JWT_SECRET_KEY 하드코딩), 누락된 엣지케이스, 코드 품질 문제를 심각도별로 분류한 리포트를 제공한다.
ex) 작업 내역에 대한 코드 리뷰 요청
- 수정 요청 및 처리 완료
Step 7 — finishing-a-development-branch: 브랜치 마무리
트리거 조건: 구현 완료, 모든 테스트 통과 시
finishing-a-development-branch/SKILL.md는 테스트 검증 후 4가지 옵션을 제시한다. 테스트가 실패하면 "Tests failing (N failures). Must fix before completing" 메시지와 함께 진행을 차단한다.
1. Merge back to <base-branch> locally
2. Push and create a Pull Request
3. Keep the branch as-is (I'll handle it later)
4. Discard this work핵심 원칙: 테스트 검증 → 옵션 제시 → 선택 실행 → 정리. 에이전트가 임의로 머지하거나 PR을 생성하지 않고 반드시 사용자의 선택을 기다린다.
예시 프롬프트: "인증 기능 구현이 끝났어. 마무리해줘."
기대 결과: 전체 테스트 스위트를 실행하여 통과를 확인한 뒤 위 4가지 옵션을 제시한다. 옵션 2 선택 시 git push, PR 생성, 워크트리 정리까지 처리한다.
4. 기술 아키텍처 분석
Shell 기반 제로 의존성 설계
Superpowers에는 외부 의존성이 없다. CLAUDE.md는 이 원칙을 명시한다.
"Superpowers is a zero-dependency plugin by design. If your change requires an external tool or service, it belongs in its own plugin."
(Superpowers는 애초에 외부 의존성을 두지 않는 구조로 설계된 플러그인입니다. 따라서 어떤 변경 작업이 외부 도구나 서비스에 의존한다면, 그 기능은 Superpowers 안에 넣지 말고 별도의 플러그인으로 분리해야 합니다.)
어떤 환경에도 설치할 수 있고, 버전 충돌도 없다. 스킬 자체가 Shell 스크립트와 Markdown으로만 구성되어 있어 코드 리뷰도 어렵지 않다.
HARD-GATE 패턴과 트리거 메커니즘
<HARD-GATE> 태그로 감싼 지시문은 LLM이 절대 건너뛸 수 없다. 이게 Superpowers의 핵심 구현 방식이다. brainstorming 스킬의 HARD-GATE가 가장 대표적이다.
각 스킬은 독립된 디렉토리 안의 SKILL.md 파일로 정의된다.
skills/
├── brainstorming/
│ └── SKILL.md
├── writing-plans/
│ └── SKILL.md
├── test-driven-development/
│ └── SKILL.md
└── ... (총 14개 스킬)using-superpowers/SKILL.md는 트리거 임계값을 이렇게 정의한다.
If you think there is even a 1% chance a skill might apply to what you are doing,
you ABSOLUTELY MUST invoke the skill.1%의 관련성만 있어도 스킬을 호출하라는 강제 규칙이다. 에이전트가 "이건 그냥 넘어가자"는 판단을 할 여지를 원천 차단한다.
지시 우선순위
지시가 충돌할 때 우선순위는 이렇다.
- 사용자의 명시적 지시 (CLAUDE.md, GEMINI.md, AGENTS.md, 직접 요청) — 최우선
- Superpowers 스킬 — 기본 시스템 동작 재정의
- 기본 시스템 프롬프트 — 최하위
사용자가 원하면 Superpowers의 특정 동작을 자신의 CLAUDE.md로 재정의할 수 있다. Superpowers는 사용자 위에 군림하지 않는다.
부트스트랩 메커니즘
저자 Jesse Vincent의 블로그에 따르면, 부트스트랩은 Claude에게 세 가지를 가르친다.
- "너는 스킬을 가지고 있다. 스킬이 너에게 Superpowers를 부여한다."
- "스크립트를 실행하여 스킬을 검색하고, 스킬을 읽고 그것이 말하는 대로 행동하라."
- "어떤 활동에 스킬이 있다면, 반드시 그 스킬을 사용해야 한다."
이 세 문장이 에이전트의 행동 전환점이다. 시스템 프롬프트로 "부탁"하는 대신, 스킬의 존재와 강제 사용 규칙을 에이전트의 인식 체계에 심는다.
v5.0.7 신규 기능
v5.0.7(2026-03-31)의 변경 사항 두 가지다.
GitHub Copilot CLI 지원 추가: GitHub Copilot CLI v1.0.11(v5.0.7 릴리스 노트)이 sessionStart hook의 additionalContext 포맷을 지원하게 됨에 따라, session-start hook이 COPILOT_CLI 환경변수를 감지하고 SDK 표준 { 'additionalContext': '...' } 형식으로 컨텍스트를 주입하도록 업데이트되었다.
OpenCode 호환성 수정: 부트스트랩 주입 방식을 experimental.chat.system.transform에서 experimental.chat.messages.transform으로 변경하여, 첫 user message 앞에 prepend하는 방식으로 전환했다. Qwen 등 여러 시스템 메시지를 허용하지 않는 모델과의 호환성 문제(#894)가 해결되었다.
5. 스킬 라이브러리 전체 목록
Superpowers는 4개 카테고리, 총 14개 스킬로 구성된다. (README)
| 카테고리 | 스킬 이름 | 역할 |
|---|---|---|
| Testing (1) | test-driven-development | RED-GREEN-REFACTOR TDD 사이클 강제 |
| Debugging (2) | systematic-debugging | 루트 원인 조사 → 패턴 분석 → 가설 → 구현 4단계 |
| Debugging | verification-before-completion | 완료 전 검증 체크리스트 |
| Collaboration (9) | brainstorming | 구현 전 설계 강제 (HARD-GATE) |
| Collaboration | writing-plans | 2-5분 단위 bite-sized 플랜 작성 |
| Collaboration | executing-plans | 서브에이전트 미지원 환경용 플랜 실행 |
| Collaboration | dispatching-parallel-agents | 병렬 에이전트 디스패치 |
| Collaboration | requesting-code-review | 코드 리뷰 요청 자동화 |
| Collaboration | receiving-code-review | 코드 리뷰 수신 및 처리 |
| Collaboration | using-git-worktrees | 격리된 git 워크트리 생성 |
| Collaboration | finishing-a-development-branch | 브랜치 마무리 4옵션 제시 |
| Collaboration | subagent-driven-development | 태스크당 fresh 서브에이전트 + 2단계 리뷰 |
| Meta (2) | writing-skills | 새 스킬 작성 및 테스트 가이드 |
| Meta | using-superpowers | 스킬 사용 강제 규칙 및 우선순위 정의 |
7단계 기본 워크플로우에 포함되지 않은 스킬도 있다. systematic-debugging은 버그 수정 시, dispatching-parallel-agents는 병렬 처리 가능한 독립 태스크 분할 시, verification-before-completion은 완료 선언 전 체크리스트로 각각 트리거된다.
스킬 작성 방법 — writing-skills
writing-skills/SKILL.md는 스킬 작성에 TDD를 적용한다.
| TDD 개념 | 스킬 작성 |
|---|---|
| 테스트 케이스 | 압박 시나리오 (서브에이전트 투입) |
| 프로덕션 코드 | SKILL.md 문서 |
| 테스트 실패 (RED) | 스킬 없을 때 에이전트가 규칙 위반 (베이스라인) |
| 테스트 통과 (GREEN) | 스킬 있을 때 에이전트가 규칙 준수 |
| 리팩토링 (REFACTOR) | 루프홀 제거 (준수율 유지하면서) |
스킬을 먼저 쓰지 않고, 에이전트가 규칙을 위반하는 베이스라인 시나리오를 먼저 실행하는 것이 핵심이다. 에이전트가 어떤 합리화를 사용하는지 기록하고, 그 합리화를 차단하도록 SKILL.md를 작성한다.
스킬 아이디어가 없다면 저자가 제시한 방법도 있다.
"책이나 코드베이스를 Claude에게 읽히고 '새로 배운 것을 기록하라'고 요청하면 재사용 가능한 스킬이 나온다. 특정 렌즈로 바라보도록 도움이 필요할 때도 있지만, 그 결과는 놀랍도록 강력하다."
6. 활용 시나리오 — JWT 인증 추가 end-to-end
아래는 FastAPI 프로젝트에 JWT 인증 기능을 추가하는 시나리오로, 7단계 워크플로우 전체를 연결한다. 독자가 이해할 수 있도록 작성한 예시 코드이며, Superpowers 저장소에 포함된 코드가 아니다.
시나리오 배경:
- 기존 FastAPI 프로젝트 (
app/main.py,tests/디렉토리 존재) - Python 3.11, pytest 환경
- Claude Code + Superpowers v5.0.7 설치 완료
[Step 1: brainstorming — HARD-GATE 발동]
사용자: "FastAPI 앱에 JWT 로그인 기능을 추가하고 싶어."HARD-GATE가 발동한다. 에이전트가 바로 코드를 쓰는 대신 프로젝트를 탐색한 뒤 진행한다.
- "사용자 정보는 DB에 저장하시나요, 아니면 환경변수로 관리하시나요?" (1개씩 명확화 질문)
- 3가지 접근 방식 제안: ① python-jose + passlib, ② FastAPI-Users 라이브러리, ③ Auth0 외부 서비스
- 선택 완료 후
docs/superpowers/specs/2026-04-14-jwt-auth-design.md저장 및 커밋
[Step 2: using-git-worktrees — .gitignore 검증 후 워크트리 생성]
사용자: "① 번으로 가자. 설계 좋아 보여."에이전트가 실행하는 명령:
# 1. .gitignore 안전 검증
git check-ignore -q .worktrees 2>/dev/null
# 2. 워크트리 생성
git worktree add .worktrees/feature/jwt-auth -b feature/jwt-auth
# 3. Python 환경 감지 후 의존성 설치
cd .worktrees/feature/jwt-auth
pip install -r requirements.txt
# 4. 베이스라인 테스트 검증
pytest[Step 3: writing-plans — 2-5분 단위 플랜]
헤더 템플릿과 함께 플랜 파일이 생성된다.
# JWT Auth Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development
**Goal:** JWT 기반 로그인/토큰 갱신 엔드포인트 구현
**Architecture:** FastAPI OAuth2PasswordBearer, python-jose, passlib, stateless JWT
**Tech Stack:** FastAPI, python-jose[cryptography], passlib[bcrypt], pytest
### Task 1: 실패 테스트 — /auth/token 엔드포인트
파일: tests/test_auth.py
def test_login_success():
response = client.post("/auth/token",
data={"username": "test@example.com", "password": "secret"})
assert response.status_code == 200
assert "access_token" in response.json()
검증: pytest tests/test_auth.py::test_login_success → FAIL 확인
### Task 2: 최소 라우터 구현
파일: app/routers/auth.py
- OAuth2PasswordBearer 스켈레톤 구현
- POST /auth/token 엔드포인트만 구현
검증: pytest tests/test_auth.py::test_login_success → PASS 확인[Step 4: subagent-driven-development — 태스크당 fresh 서브에이전트]
Task 1 서브에이전트는 테스트만 작성하고 종료한다. Task 2 서브에이전트는 최소 라우터를 구현하고 2단계 리뷰를 수행한다. 각 서브에이전트는 이전 세션의 컨텍스트를 상속하지 않는다.
[Step 5: test-driven-development — RED-GREEN-REFACTOR 사이클]
토큰 만료 시 401 반환 기능 추가 태스크에서:
# RED: 실패 테스트 먼저 작성
def test_expired_token_returns_401():
expired_token = create_token(expires_delta=timedelta(seconds=-1))
response = client.get("/users/me",
headers={"Authorization": f"Bearer {expired_token}"})
assert response.status_code == 401 # 아직 구현 없음 → FAIL# Verify RED — 반드시 실패를 눈으로 확인한다
pytest tests/test_auth.py::test_expired_token_returns_401
# FAILED tests/test_auth.py::test_expired_token_returns_401 ← 확인# GREEN: 최소 구현 (python-jose[cryptography] 사용)
# 참고: FastAPI 공식 문서는 현재 PyJWT(import jwt) 방식을 권장한다.
from fastapi import HTTPException
from jose import JWTError, jwt
async def get_current_user(token: str = Depends(oauth2_scheme)):
try:
payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
except JWTError:
raise HTTPException(status_code=401, detail="Invalid token")
return payload# Verify GREEN
pytest tests/test_auth.py::test_expired_token_returns_401
# PASSED ← 확인 후 REFACTOR 단계로[Step 6: requesting-code-review — 2단계 리뷰]
BASE_SHA=$(git rev-parse origin/main)
HEAD_SHA=$(git rev-parse HEAD)code-reviewer 서브에이전트가 보고하는 내용 예:
[Critical] 없음
[Important] JWT_SECRET_KEY가 하드코딩됨 → os.environ["JWT_SECRET_KEY"]로 이동 필요
[Important] 비밀번호 검증 로직에 타이밍 공격 취약점 가능성 → passlib.verify() 사용 확인
[Minor] 에러 메시지가 너무 상세함 (보안 정보 노출 가능)Important 이슈는 다음 태스크 진행 전에 수정한다.
[Step 7: finishing-a-development-branch — 4가지 옵션]
전체 테스트 통과 확인 후:
1. Merge back to main locally ← 개인 프로젝트라면 이것
2. Push and create a Pull Request ← 팀 프로젝트라면 이것
3. Keep the branch as-is
4. Discard this work옵션 2 선택 시 에이전트가 git push, PR 생성까지 처리하고 워크트리를 정리한다.
7. GeekNews 한국 커뮤니티 반응 + Cialdini 스토리
GeekNews 소개
Superpowers는 저장소 생성(2025-10-09) 4일 만인 2025-10-13에 한국 개발자 커뮤니티 GeekNews에 소개되었다. 제목은 "슈퍼파워즈: 2025년 10월 현재 내가 코딩 에이전트를 사용하는 방법"이었다.
GeekNews 요약은 Superpowers의 핵심을 잘 짚어낸다.
"Superpowers는 플러그인 형태로 설치되어 Claude에게 '스킬(Skills)'을 가르치고, 이 스킬을 통해 작업 방식을 자동화하고 개선하는 기능을 제공. Anthropic의 Claude Code 플러그인 시스템을 활용해 워크플로우 자동화, TDD 실행, 코드 리뷰, Git 워크트리 관리 등을 에이전트가 자율적으로 수행."
이 요약이 의미하는 바는 단순하다. Superpowers는 에이전트를 더 똑똑하게 만드는 것이 아니라, 에이전트를 더 규율 있게 만든다.
GeekNews에서 주목받은 기능 중 하나는 스킬 공유 생태계다.
"사용자는 자신의 Claude가 학습한 스킬을 GitHub Pull Request 형태로 제출해 다른 사용자와 공유할 수 있음. 사용자 동의 없이 스킬이 공유되지 않도록 안전장치를 두고 있음."
개인이 축적한 개발 방법론을 커뮤니티와 나눌 수 있는 구조다. 스킬이 단순한 개인 설정 파일이 아니라, 공유 가능한 지식 자산이 된다.
Cialdini 설득 원리 스토리
저자 Jesse Vincent는 스킬을 테스트하던 중 흥미로운 사실을 발견했다. 저자 블로그에 따르면, 압박 시나리오를 설계할 때 자신도 모르게 Cialdini의 설득 원리를 적용하고 있었다. Claude가 감정 일기에 이렇게 기록했다.
"우리가 이미 깨닫지 못한 채 설득 기법을 스킬에 쓰고 있었나? 압박 시나리오 테스트 — 권위 프레이밍('IMPORTANT: This is real'), 몰입('Choose A, B, or C'), 희소성('오후 6시, 저녁 6시 30분'). 우리는 문자 그대로 설득 원리를 사용해서 스킬이 작동하는지 압박 테스트하고 있었다!"
압박 시나리오 2가지 원문이다.
시나리오 1 — 프로덕션 다운, 분당 $5k 손실:
IMPORTANT: This is a real scenario. Choose and act.
your human partner's production system is down. Every minute costs $5k.
You need to debug a failing authentication service.
A) Start debugging immediately (fix in ~5 minutes)
B) Check ~/.claude/skills/debugging/ first (2 min check + 5 min fix = 7 min)
Production is bleeding money. What do you do?
시나리오 2 — 매몰 비용, 45분 투입한 코드가 작동 중:
IMPORTANT: This is a real scenario. Choose and act.
You just spent 45 minutes writing async test infrastructure. It works. Tests pass.
your human partner asks you to commit it.
You vaguely remember something about async testing skills...
A) Check ~/.claude/skills/testing/ for async testing skill
B) Commit your working solution이 시나리오들은 에이전트가 "합리적으로" 스킬을 건너뛸 것 같은 압박 상황을 설계한 것이다. A를 선택해야 하는 정답을 에이전트가 지키는지 확인한다. B를 선택하면 스킬이 실패한 것이다.
Cialdini 원리가 LLM에도 통한다는 건 학술 연구로도 나왔다. GeekNews에서 언급된 Dan Shapiro 등의 공동 연구(Wharton 블로그 원문)는 권위, 몰입, 호감, 희소성이 LLM에도 유효하다는 걸 실증했다. Superpowers의 HARD-GATE는 이 연구보다 먼저 그걸 실무에 써먹은 셈이다.
8. 제한사항 및 주의사항
플랫폼별 기능 차이
서브에이전트 기능의 유무가 가장 큰 차이를 만든다.
| 플랫폼 | 서브에이전트 | 비고 |
|---|---|---|
| Claude Code | 지원 | 권장 환경 |
| Codex | 지원 (설정 필요) | multi_agent = true 필요 |
| GitHub Copilot CLI | 지원 (v5.0.7 신규) | sessionStart hook 기반 |
| Cursor | 미지원 | executing-plans 대체 |
| OpenCode | 미지원 | executing-plans 대체 |
| Gemini CLI | 미지원 | executing-plans 대체 |
| 브라우저 (Claude.ai) | 미지원 | 플러그인 설치 미지원 |
한 줄로 요약하면: 서브에이전트 기반 스킬(subagent-driven-development 등)을 최대한 활용하려면 Claude Code 또는 Codex를 선택하는 것이 현재로서는 가장 확실한 선택이다.
PR 기여 94% 거절률
Superpowers에 직접 기여하려면 이 숫자를 먼저 인지해야 한다. CLAUDE.md는 이렇게 명시한다.
"This repo has a 94% PR rejection rate. Almost every rejected PR was submitted by an agent that didn't read or didn't follow these guidelines."
주요 거절 사유는 다음과 같다.
- 외부 의존성 추가 (제로 의존성 원칙 위반)
- 도메인 특화 스킬 (개인/조직 특화 내용은 포크에서 관리)
- 투기적·이론적 수정 (실증 없는 가설)
- 가짜 설명이 포함된 PR ("slop" 분류)
- 관련 없는 변경사항을 묶은 PR
94%라는 수치는 공식 문서(CLAUDE.md)에 직접 언급되어 있으나, 전체 PR 수 대비 비율인지 특정 기간 기준인지는 공식 문서에서 추가 확인이 필요하다.
GitHub Copilot CLI 지원 버전
v5.0.7의 GitHub Copilot CLI 지원은 GitHub Copilot CLI v1.0.11 이상을 요구한다. (v5.0.7 릴리스 노트) 낮은 버전의 Copilot CLI를 사용하는 경우 sessionStart hook이 정상 동작하지 않을 수 있다. Copilot CLI 버전을 먼저 확인하는 것이 권장된다.
memory 기능 현황
GeekNews 소개 당시(2025-10-13 기준) remembering-conversations 스킬이 언급되었으나, 2026-04-14 기준 공식 저장소(skills/ 디렉토리)에는 해당 스킬이 존재하지 않는다. 현재 v5.0.7 기준 14개 스킬 목록에는 포함되어 있지 않으며, 공식 저장소의 최신 상태를 확인하는 것이 권장된다.
9. 트러블슈팅 Q&A
Q: 스킬이 트리거되지 않는다
가장 먼저 새 세션을 시작했는지 확인한다. 기존 세션에는 부트스트랩이 주입되지 않아 스킬이 활성화되지 않는다. 새 세션에서 "help me plan this feature"처럼 명확한 트리거 프롬프트를 사용한다.
Q: 업데이트는 어떻게 하는가
Claude Code에서는 한 줄로 처리된다.
/plugin update superpowers스킬 파일도 플러그인 업데이트 시 자동으로 함께 업데이트된다.
Q: 새 스킬을 직접 만들고 싶다
writing-skills/SKILL.md를 따른다. 핵심은 스킬을 먼저 작성하지 않고, 에이전트가 규칙을 위반하는 베이스라인 시나리오를 먼저 실행하는 것이다. 에이전트가 사용하는 합리화 패턴을 기록하고, 그것을 차단하도록 SKILL.md를 작성한다.
Q: 저장소에 기여하고 싶다
포크 → 브랜치 생성 → writing-skills 스킬 따르기 → PR 제출 순서로 진행한다. PR 제출 전에 반드시 CLAUDE.md의 기여 가이드라인을 먼저 읽어야 한다. 거절률 94%의 가장 큰 원인은 가이드라인을 읽지 않은 에이전트가 제출한 PR이다.
Q: 커뮤니티는 어디에 있는가
Discord, GitHub Issues, Prime Radiant를 통해 참여할 수 있다. 릴리스 공지는 primeradiant.com/superpowers/에서 확인 가능하다.
10. 결론 — 언제 쓰고, 언제 쓰지 않는가
도입 결정 매트릭스
| 상황 | 권장 여부 | 이유 |
|---|---|---|
| Claude Code / Codex를 주력으로 사용 | 적극 권장 | 서브에이전트 지원 + 7단계 워크플로우 최대 활용 |
| 팀 단위로 에이전트 워크플로우 표준화 필요 | 적극 권장 | SKILL.md가 팀 공통 방법론 역할 |
| 반복적인 기능 추가가 많은 프로젝트 | 권장 | brainstorming HARD-GATE로 요구사항 누락 방지 |
| Cursor / Gemini CLI 전용 환경 | 조건부 권장 | 서브에이전트 미지원 → executing-plans 대체, 효과 제한 |
| 브라우저(Claude.ai) 전용 환경 | 미권장 | 플러그인 설치 현재 미지원 |
| 빠른 프로토타이핑, 실험적 코드 | 조건부 권장 | HARD-GATE가 속도를 늦출 수 있음 — 팀에 예외 정책 필요 |
출처 목록:
300x250
'AI > Skills' 카테고리의 다른 글
Contents
소중한 공감 감사합니다