이 저장소가 대체 무엇인가.
AI 코딩 에이전트는 본능적으로 "코드부터 친다." 요구사항을 절반만 이해한 채 파일을 만들기 시작하고, 테스트는 나중으로 미루고, 버그가 나면 증상만 땜질한다. Superpowers는 이 습관을 구조적으로 차단한다. 14개의 마크다운 스킬 파일이 브레인스토밍 → 설계 문서 승인 → 계획 수립 → 격리된 워크트리 → 서브에이전트 구현 → RED-GREEN-REFACTOR TDD → 2단계 리뷰 → 브랜치 마무리로 이어지는 파이프라인을 "Hard Gate"로 강제한다.
제작자는 Perl 커뮤니티의 전설적 개발자이자 Request Tracker(RT) 창시자인 Jesse Vincent(obra)다. README의 표현을 빌리면: "a complete software development methodology for your coding agents, built on top of a set of composable skills." ("코딩 에이전트를 위한 완전한 소프트웨어 개발 방법론 — 조합 가능한 스킬들 위에 구축.") 2025년 10월 출시 후 8개월 만에 v6.1.0·243k 스타까지 성장했다.
Superpowers는 전통적인 의미의 "코드 프로젝트"가 아니다. 스킬 정의(마크다운) + 부트스트랩 훅(셸) + 시각화 컴패니언 서버(Node.js) + 9개 플랫폼 어댑터로 구성된 에이전트 행동 규약 시스템이다. 언어 구성비(Shell 51.8%, JavaScript 41.1%, TypeScript 2.6%, HTML 2.2%, Python 1.9%)가 이를 잘 보여준다 — 정작 "제품 로직"은 대부분 마크다운 스킬 파일 안에 프롬프트로 존재하고, 코드는 그것을 세션에 주입하고 시각적으로 보조하는 배관(plumbing)이다.
SKILL.md 파일 하나로 존재하지만, 문서 안에서 다른 스킬을 명시적으로 호출한다("Invoke the writing-plans skill"). 결합도가 낮아 필요한 스킬만 골라 쓸 수 있고, 스킬들이 체인으로 연결돼 하나의 방법론을 이룬다. YAML 프런트매터의 description 필드가 "언제 이 스킬을 써야 하는가"를 담아, 에이전트가 상황에 맞는 스킬을 스스로 매칭하게 한다.대부분의 "AI에게 이렇게 하라고 시키는" 프롬프트는 감(感)으로 작성된다. Superpowers는 다르다. writing-skills 스킬이 규정하는 절차는 이렇다: ① 서브에이전트에게 스킬 없이 작업을 시켜 실패(합리화·규칙 위반)를 관찰(RED) → ② 그 실패를 막는 스킬 문서를 작성(GREEN) → ③ 같은 압박 시나리오로 재검증 → ④ 빠져나갈 구멍을 계속 메움(REFACTOR). CLAUDE.md는 이걸 못박는다 — "Skills are not prose — they are code that shapes agent behavior." 스킬 변경 PR에는 반드시 전후 평가(eval) 결과를 첨부해야 한다.
243k 스타의 성장 속도 · 94% PR 반려율이라는 이례적 품질 관문 · 9개 플랫폼 이식.
2025년 10월 블로그 발표("the original release announcement") 이후 Superpowers는 AI 코딩 에이전트 커뮤니티에서 가장 자주 언급되는 "방법론형" 플러그인이 됐다. v6.1.0 시점 243k 스타 · 21.6k 포크 · 901 워처 · 618 커밋 · 9개 정식 릴리스라는 수치는, 단순한 프롬프트 모음이 아니라 실제로 반복 사용되고 신뢰받는 인프라가 됐음을 보여준다.
① "설계 없이 코드부터 치는" AI의 고질병에 정면으로 답한다. 바이브 코딩(Vibe Coding) 열풍 속에서 에이전트가 요구사항을 오해하고, 테스트를 건너뛰고, 근본 원인 대신 증상만 고치는 문제가 반복적으로 지적돼 왔다. Superpowers는 이걸 brainstorming·test-driven-development·systematic-debugging 세 스킬의 Hard Gate로 구조적으로 막는다.
② 9개 플랫폼 동시 지원. Claude Code, Antigravity, Codex App/CLI, Cursor, Factory Droid, GitHub Copilot CLI, Kimi Code, OpenCode, Pi — 어느 에이전트를 쓰든 같은 스킬 세트를 그대로 쓸 수 있다. v6.0.0에서 스킬 문구를 "Claude Search Optimization"→"Skill Discovery Optimization"으로 개명하는 등, 특정 벤더 용어를 의도적으로 걷어냈다.
③ 이례적으로 엄격한 기여 관문. 저장소 CLAUDE.md는 스스로 밝힌다 — "This repo has a 94% PR rejection rate." AI가 작성한 저품질 PR("슬롭")을 걸러내기 위해 PR 템플릿 전체 작성, 중복 PR 검색, 실제 문제 여부 확인, 모델·하네스·설치 플러그인 공개 의무화까지 요구한다. 이 엄격함 자체가 "신뢰할 수 있는 방법론"이라는 신호로 작동한다.
④ 실측 성능 개선을 공개. v6.0.0 릴리스 노트는 "Claude Code and Codex produce similar high-quality results roughly twice as fast and while spending almost 50% fewer tokens"라고 명시한다 — 서브에이전트 리뷰 파이프라인을 재설계해 실제 프로젝트에서 측정한 수치다.
| 비교 대상 | 한계 | Superpowers의 차별점 |
|---|---|---|
| 단일 CLAUDE.md 설정 | 파일 하나에 규칙을 욱여넣음, 재사용 불가 | 14개 스킬로 분해 — 상황별로 자동 매칭·조합 |
| 일반 프롬프트 모음(Awesome 리스트류) | 검증 없이 "그럴듯해 보이는" 텍스트 | 스킬을 TDD로 개발, 압박 시나리오로 평가(evals) |
| Claude Code 전용 스킬 패키지 | 다른 에이전트로 이식 불가 | 9개 플랫폼 벤더-뉴트럴 어휘("subagent" not "Task tool") |
| GitHub Copilot 자동완성 | 줄 단위 제안, 프로세스 개념 없음 | 에이전트의 사고 순서 자체를 재편(설계→계획→구현→리뷰) |
단일 CLAUDE.md에 "테스트 먼저 짜라"고 한 줄 써봐도 에이전트는 금세 잊는다. 프롬프트 모음형 접근은 검증 없이 "그럴듯해 보이는" 문장을 늘어놓을 뿐이라 상황이 조금만 바뀌어도 무너진다.
Hard Gate + Red Flag 반박 표로 "이번만 예외"를 원천 차단하고, 압박 시나리오로 실제 준수율을 측정해 계속 보강한다. 그래서 벤더가 바뀌어도(9개 플랫폼) 같은 규율이 유지된다.
일반 프롬프트가 "부탁"이라면, Superpowers의 Hard Gate는 "건축 인허가"다. 도면 승인 없이는 착공 자체가 불가능하듯, 설계 문서 승인 없이는 brainstorming 스킬이 구현 스킬 호출을 원천 차단한다. 그리고 "합리화 탐지(Rationalization Detection)" — 에이전트가 "이번만 테스트 건너뛸게" 같은 변명을 시도할 걸 미리 알고, 그 변명 목록 자체를 표로 박아 반박까지 준비해 둔다.
마크다운 스킬(제품) + Shell 부트스트랩(배관) + Node.js 시각화 서버(옵션) + 9개 플랫폼 어댑터.
package.json의 자기소개는 정확하다 — "Superpowers skills and runtime bootstrap for coding agents." 스택을 네 층으로 나눠 보면 역할이 명확해진다.
| 레이어 | 기술 / 구성 | 역할 |
|---|---|---|
| 제품 계층 | 마크다운 스킬 (skills/*.md) | YAML 프런트매터 + 프로세스 문서. 실제 "방법론"이 담기는 곳 |
| 부트스트랩 계층 | Shell (hooks/) | SessionStart 훅이 using-superpowers 스킬 전체를 JSON으로 이스케이프해 세션에 주입 |
| 시각화 계층 | Node.js (server.cjs, zero-dependency) | 브레인스토밍 중 목업·다이어그램을 브라우저 탭에 WebSocket으로 표시(옵션) |
| 플랫폼 어댑터 계층 | 9개 매니페스트(JSON/JS/TS) | 각 코딩 에이전트의 플러그인 시스템에 스킬을 등록하는 얇은 껍데기 |
| 요소 | 설명 |
|---|---|
| YAML 프런트매터 | name·description — description이 "언제 쓸지"를 담아 에이전트의 자동 매칭 트리거로 작동 |
| Graphviz(.dot) 다이어그램 | SKILL.md 안에 digraph 블록을 내장해 프로세스 플로우를 시각적으로 명세(brainstorming·subagent-driven-development 등) |
| 구조 표식 | <HARD-GATE>·<EXTREMELY-IMPORTANT> 같은 유사 XML 태그로 "반드시 지켜야 할 규칙"을 시각적으로 구분 |
| 보조 참조 파일 | 100줄 넘는 레퍼런스는 별도 .md로 분리(testing-anti-patterns.md·root-cause-tracing.md 등) |
| 파일 | 역할 |
|---|---|
hooks/hooks.json | Claude Code용 훅 설정 — SessionStart 이벤트에서 run-hook.cmd session-start 실행 |
hooks/session-start | bash 스크립트. using-superpowers/SKILL.md 전문을 읽어 JSON 문자열로 이스케이프(순수 bash 파라미터 치환, 서브프로세스 없이 처리해 속도 확보) 후 플랫폼별 포맷으로 출력 |
| 플랫폼별 분기 | Cursor는 additional_context(스네이크케이스), Claude Code는 hookSpecificOutput.additionalContext(중첩), Copilot CLI 등은 additionalContext(SDK 표준) — 같은 훅이 3가지 JSON 스키마를 인식해 출력 |
hooks/run-hook.cmd | Windows 폴리글랏 실행기 — cmd.exe가 bash 스크립트를 투명하게 호출(docs/windows/polyglot-hooks.md 참고) |
| 구성 요소 | 역할 |
|---|---|
server.cjs | 외부 의존성 0개(zero-dependency) — Node.js 내장 http/ws 프로토콜만으로 로컬 웹서버 + WebSocket 구현 |
frame-template.html | 브레인스토밍 중 목업·비교안을 렌더링하는 정적 프레임 |
| 세션 키 인증 | v6.0.0에서 추가 — URL에 담긴 1회용 키를 탭 스코프 쿠키로 저장, 모든 요청·WS 연결에서 검증(DNS 리바인딩 방어 포함) |
| 파일 서버 샌드박스 | 심볼릭 링크·dotfile·경로 탈출 차단, macOS 리소스포크 무시, no-store/deny-framing 헤더 |
| 테스트 | tests/brainstorm-server/ — auth·branding·lifecycle·ws-protocol 등 Node 테스트 스위트(자체 package.json) |
| 플랫폼 | 어댑터 위치 | 설치 방식 |
|---|---|---|
| Claude Code | .claude-plugin/plugin.json | /plugin install superpowers@claude-plugins-official |
| Cursor | .cursor-plugin/plugin.json | /add-plugin superpowers |
| Codex App/CLI | .codex-plugin/plugin.json | Codex 공식 마켓플레이스(v6.1.0에서 신규 매니페스트 추가) |
| Kimi Code | .kimi-plugin/plugin.json | /plugins install https://github.com/obra/superpowers |
| OpenCode | .opencode/plugins/superpowers.js | 원격 INSTALL.md fetch 지시 → 모듈 레벨 캐싱(15개 회귀 테스트) |
| Pi | .pi/extensions/superpowers.ts | pi install git:github.com/obra/superpowers — 네이티브 스킬 지원 |
| Antigravity | 루트에서 플러그인 훅 실행 | agy plugin install https://github.com/obra/superpowers |
| Factory Droid | 마켓플레이스 등록형 | droid plugin marketplace add ... |
| GitHub Copilot CLI | Superpowers 자체 마켓플레이스 경유 | copilot plugin marketplace add obra/superpowers-marketplace |
server.cjs)가 npm 패키지를 단 하나도 설치하지 않고, Node.js에 기본 내장된 모듈만으로 HTTP·WebSocket을 직접 구현한 것을 뜻한다. 마치 재료를 사 오지 않고 집에 있는 것만으로 요리하는 것과 비슷하다 — 설치 실패·버전 충돌·공급망 공격 위험이 그만큼 줄어든다.v6.1.0 릴리스 노트: "Google EOLed the Gemini CLI on 2026-06-18; the extension can no longer be installed or updated." 저장소에는 gemini-extension.json과 GEMINI.md가 아직 파일로 남아 있지만 설치 문서·플랫폼 목록에서는 이미 제거됐다. 플랫폼 목록은 릴리스마다 바뀌므로, 최신 지원 현황은 항상 README의 "Quickstart" 링크 목록을 기준으로 확인해야 한다.
세션 시작 부트스트랩부터 서브에이전트 디스패치·파일 기반 핸드오프·재개 가능한 원장(ledger)까지.
Superpowers의 실행 모델은 크게 "부트스트랩 → 워크플로 스킬 체인 → 서브에이전트 오케스트레이션" 세 층으로 이해하면 된다. 먼저 전체 그림을 독수리 시점으로 본 다음, 대표 흐름 한 줄기를 처음부터 끝까지 손으로 따라가 본다.
전체 그림이 눈에 들어왔다면, 이제 사용자가 실제로 던질 법한 요청 하나를 골라 어느 파일이 어떤 순서로 반응하는지 처음부터 끝까지 따라가 본다. 곁가지(에러 처리·플랫폼별 분기)는 생략하고 "정상 경로"만 본다.
using-git-worktrees·writing-plans처럼 동사 중심 이름을 쓴다("무엇을 하는 스킬인가"가 이름만 봐도 보이게). 그리고 SKILL.md 안에 모든 걸 몰아넣지 않고, 100줄 넘는 심화 내용(안티패턴 목록·근본원인 추적법 등)은 같은 폴더의 별도 .md로 뺀다 — 이게 이 레포 특유의 "짧은 진입점 + 깊은 참조" 관례다.
각 스킬은 절대 건너뛸 수 없는 관문을 <HARD-GATE> 태그로 명시한다. 예를 들어 brainstorming의 게이트는 "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." 그리고 에이전트가 이 규칙을 우회하려 할 때 쓸 법한 변명을 미리 표로 등록해 선제 반박한다.
| 에이전트의 변명(Red Flag) | 스킬의 반박 |
|---|---|
| "이건 그냥 간단한 질문이야" | 질문도 태스크다. 스킬 체크가 먼저. |
| "컨텍스트부터 좀 더 파악할게" | 스킬 체크는 명확화 질문보다도 먼저 온다. |
| "이 스킬 기억하고 있어" | 스킬은 계속 바뀐다. 현재 버전을 읽어라. |
| "이번 한 번만 건너뛰자" (TDD) | 첫 번째 건너뜀이 패턴을 만든다. |
subagent-driven-development의 핵심 통찰: "프롬프트에 붙여넣은 텍스트는 세션 끝까지 컨텍스트에 눌러앉고, 이후 모든 턴마다 다시 읽힌다." 그래서 v6.0.0부터는 태스크 명세·diff·리뷰 결과를 전부 파일로 주고받는다.
이렇게 하면 컨트롤러(메인 에이전트)의 컨텍스트에는 파일 경로만 남고, 실제 diff·brief 본문은 서브에이전트가 Read로 필요할 때만 읽는다. 릴리스 노트가 실측한 사례: "a real session's dispatch hit 42k chars of which 99% was pasted history." 파일 핸드오프로 이 낭비를 없앴다.
subagent-driven-development는 태스크 성격별로 명시적으로 다른 모델 등급을 지정하도록 강제한다. "모델을 안 정하면 세션 기본 모델(대개 가장 비싼 모델)을 그대로 물려받는다"는 사실이 실제로 문제가 됐다 — 릴리스 노트: "one run put all 26 of its reviewers on the top tier."
| 태스크 성격 | 권장 모델 등급 |
|---|---|
| 1~2개 파일, 완전한 스펙(코드까지 명시됨) | 가장 저렴한 등급 — "전사(transcription) + 테스트"에 가까움 |
| 여러 파일 통합, 산문 설명 기반 구현 | 표준 등급 |
| 아키텍처 판단, 광범위한 코드베이스 이해 필요 | 가장 강력한 등급 |
| 최종 전체 브랜치 리뷰 | 세션 기본값과 무관하게 항상 최상위 등급 |
흥미로운 실측 통찰: "Turn count beats token price." 값싼 모델이 같은 작업에 2~3배 더 많은 턴을 쓰면 결국 더 비쌀 수 있다.
대화 메모리는 컴팩션(compaction)을 넘기지 못한다. v6.0.3에서는 진행 상황을 .superpowers/sdd/progress.md라는 git-ignore된 작업트리 파일에 기록한다(원래 .git/sdd/에 쓰려 했으나 Claude Code가 .git/ 쓰기를 보호 경로로 차단해 이동). 컨트롤러가 컴팩션 후 재개할 때는 "trust the ledger and git log over your own recollection." 릴리스 노트는 이 문제의 실제 비용도 밝힌다: "controllers that lost their place have re-dispatched entire completed task sequences — the single most expensive failure observed."
v6.0.0의 또 다른 큰 변화: 스킬 문구가 원래 Claude Code 방언("use the Task tool," "put it in CLAUDE.md")으로 쓰여 있었는데, 이걸 행위 중심 어휘("dispatch a subagent," "your instructions file")로 전면 재작성했다. 대신 skills/using-superpowers/references/에 플랫폼별 매핑 파일(codex-tools.md·pi-tools.md·antigravity-tools.md)을 두어, 하네스별 특이사항만 그쪽에서 보충한다.
skills/가 본체, 9개 플랫폼 매니페스트가 얇게 둘러싸고, tests/가 품질을 지킨다.
| 파일/폴더 | 역할 |
|---|---|
skills/ | 14개 디렉토리, 각각 SKILL.md가 핵심. 100줄 넘는 참조만 별도 파일로 분리. 가장 무거운 건 subagent-driven-development/(프롬프트 템플릿 2개 + 스크립트 2개) |
hooks/ | 플랫폼마다 다른 JSON 스키마를 bash 스크립트 하나가 분기 처리. run-hook.cmd가 Windows 폴리글랏 트릭 담당 |
| 9개 플랫폼 어댑터 | 대개 매니페스트 JSON 한두 개짜리 "얇은 껍데기" — 실제 콘텐츠(스킬)는 공유. 예외는 Pi(TS)·OpenCode(JS+캐싱) |
tests/ | "플러그인 코드가 플랫폼별로 올바르게 동작하는가"를 검증(설치 스크립트·훅·매니페스트). 별도 저장소 superpowers-evals가 "스킬이 실제로 에이전트 행동을 바꾸는가"를 LLM 심사관으로 평가(얕은 클론 시 딸려오지 않음) |
CLAUDE.md | 8.8KB — 사실상 "이 저장소에 기여하려면 통과해야 할 체크리스트". AGENTS.md는 이 파일의 심볼릭 링크 |
이 저장소에서 "무엇을 배울 수 있는가" — 개념 → 코드 위치 → 실습 아이디어.
스킬을 감이 아니라 가설 검증으로 만드는 절차를 실물로 배운다. skills/writing-skills/SKILL.md의 "TDD Mapping for Skills" 표(테스트 케이스=압박 시나리오, 프로덕션 코드=SKILL.md, RED=베이스라인 위반 관찰...)가 핵심이다.
실습: 자신이 반복적으로 AI에게 시키는 작업 하나를 골라, 스킬 없이 3번 시켜보고 실패 패턴을 기록(RED) → 그 실패를 막는 짧은 SKILL.md 작성(GREEN) → 다시 3번 시켜 개선을 확인(REFACTOR).
<HARD-GATE> 태그로 절대 규칙을 명시하고, using-superpowers/SKILL.md의 "Red Flags" 표처럼 에이전트가 시도할 변명을 미리 등록해 반박하는 기법. 단순 "하지 마세요"보다 훨씬 강한 준수율을 보인다.
실습: skills/test-driven-development/SKILL.md와 skills/brainstorming/SKILL.md 두 파일의 Hard Gate·Red Flag 섹션을 나란히 놓고 문구 패턴(단정문·반박 표·Iron Law)을 비교 정리.
subagent-driven-development/SKILL.md의 task-brief → implementer → review-package → task-reviewer 파이프라인. "붙여넣은 텍스트는 세션 끝까지 컨텍스트를 차지한다"는 문제를 파일 경로 전달로 해결하는 설계.
실습: skills/subagent-driven-development/scripts/의 task-brief·review-package 스크립트를 읽고, 각각이 어떤 입력을 받아 어떤 파일을 어디에 쓰는지 직접 실행해 확인.
대화 메모리가 컴팩션으로 사라져도 .superpowers/sdd/progress.md와 git 로그로 진행 상태를 복원하는 설계. "자기 기억보다 외부 기록을 신뢰하라"는 원칙은 장시간 자율 실행 에이전트 전반에 적용 가능한 패턴이다.
실습: 로컬 테스트 레포에서 subagent-driven-development를 일부 진행하다 의도적으로 세션을 끊고, 원장 파일과 git log만으로 "어디까지 됐는지"를 재구성해보기.
hooks/session-start 하나가 Cursor·Claude Code·Copilot CLI 3가지 JSON 스키마를 분기 처리하는 코드, 그리고 Windows에서 bash 스크립트를 cmd.exe로 감싸 실행하는 run-hook.cmd 폴리글랏 기법.
실습: hooks/session-start의 escape_for_json() 함수(순수 bash 파라미터 치환)를 읽고, 왜 이 방식이 문자 단위 루프보다 빠른지 설명해보기.
skills/brainstorming/scripts/server.cjs는 외부 패키지 없이 순수 Node 내장 모듈만으로 HTTP+WebSocket 서버를 구현한다. v6.0.0에서 추가된 세션 키 인증(URL 키 → 탭 스코프 쿠키 → 모든 요청 검증)은 로컬 도구의 보안 모델을 배우는 좋은 사례다.
실습: tests/brainstorm-server/auth.test.js·ws-protocol.test.js를 읽고 "DNS 리바인딩 공격을 origin 허용목록만으로 막을 수 없는 이유"를 세션 키 방식과 비교해 정리.
스킬 파일 하나가 실제로 어떻게 생겼는지 감을 잡으려면, Hard Gate 표기 패턴을 코드로 보는 게 빠르다:
---
name: test-driven-development
description: 프로덕션 코드를 짜기 전 실패하는 테스트부터 작성하도록 강제
---
<HARD-GATE>
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.
# "이번만 예외" 요청은 아래 Red Flags 표로 반박한다
</HARD-GATE>마크다운 중심이라 GPU·서버 불필요 — 단, 코딩 에이전트 자체의 요금제/API 비용은 별개.
| 항목 | 요구/권장 |
|---|---|
| 필수: 코딩 에이전트 | 9개 지원 플랫폼 중 하나(Claude Code·Cursor·Codex·Kimi Code·OpenCode·Pi·Antigravity·Factory Droid·Copilot CLI) — 각각 자체 API 키/구독 필요 |
| Git | 2.5 이상(worktree 지원 필수) — using-git-worktrees 스킬의 전제조건 |
| 시각 컴패니언(선택) | Node.js 런타임 — server.cjs가 zero-dependency이므로 npm install 불필요 |
| OS | macOS·Linux 우선 설계, Windows는 MSYS2/cmd.exe 폴리글랏 훅으로 별도 지원 |
| 서드파티 의존성 | CLAUDE.md 원칙: "Superpowers is a zero-dependency plugin by design." 외부 도구가 필요한 기여는 별도 플러그인으로 분리 |
| 메모리/CPU | 스킬 자체는 텍스트 주입이라 무시 가능. 실제 부하는 뒤에서 돌아가는 코딩 에이전트(LLM 추론)에서 발생 |
플러그인 설치 자체는 명령 한 줄로 끝난다. 하지만 subagent-driven-development는 태스크마다 implementer+reviewer 서브에이전트를 추가로 소환하므로, 일반적인 단일 세션보다 API 호출·토큰 소비가 늘어난다. 모델 선택 전략(4장)을 실제로 지키는지가 비용 체감의 핵심이다.
9개 플랫폼을 지원한다고 모두 동일한 성숙도는 아니다. CLAUDE.md의 "신규 하네스 지원" 기준은 "a real integration loads the using-superpowers bootstrap at session start"인데, 과거 여러 시도가 이 기준을 통과하지 못해 반려됐다. 또한 v6.1.0에서 Gemini CLI 지원이 통째로 제거된 사례처럼, 업스트림 플랫폼의 정책 변화가 곧바로 지원 중단으로 이어질 수 있다.
난이도별로 손을 움직여 보는 5가지.
Claude Code(또는 지원 플랫폼)에 설치하고, 새 대화에서 "간단한 CLI 투두 앱 만들어줘"라고만 요청한다.
# Claude Code
/plugin install superpowers@claude-plugins-official에이전트가 코드를 바로 쓰지 않고 "using brainstorming to..."를 선언하며 질문을 시작하는지 관찰한다.
skills/ 아래 아무 스킬이나 골라 <HARD-GATE>·Iron Law·"Red Flags" 표를 찾아 표로 정리한다. brainstorming·test-driven-development·systematic-debugging 셋을 비교하면 패턴이 뚜렷이 보인다.
실제 프로젝트에서 격리 가능한 작은 기능(예: 유틸 함수 하나 + 테스트)을 골라 brainstorming → writing-plans → using-git-worktrees → subagent-driven-development 전 과정을 밟는다. implementer가 보고하는 DONE·NEEDS_CONTEXT·BLOCKED 상태를 최소 한 번씩 만나 보는 것이 목표다.
skills/writing-skills/SKILL.md의 절차를 그대로 따라 자신에게 필요한 스킬 하나를 만든다. RED(스킬 없이 시켜서 실패 관찰) → GREEN(SKILL.md 작성) → REFACTOR(재검증하며 허점 보강) 세 단계를 문서로 기록해 남긴다.
skills/brainstorming/scripts/server.cjs를 직접 node로 실행해 보고, tests/brainstorm-server/의 auth·ws-protocol 테스트를 읽으며 세션 키가 URL → 쿠키 → WebSocket 핸드셰이크로 어떻게 전달되는지 추적한다.
4주 코스 — 스킬 소비자에서 스킬 저작자·플랫폼 이식자로.
| 주차 | 주제 | 학습 자료 |
|---|---|---|
| 1주차 | 워크플로 스킬 7종 소비자 되기 | brainstorming·writing-plans·using-git-worktrees·subagent-driven-development·test-driven-development·requesting-code-review·finishing-a-development-branch를 README의 "Basic Workflow" 순서대로 실전 적용 |
| 2주차 | 서브에이전트 오케스트레이션 심화 | subagent-driven-development/SKILL.md 전문 정독 + 모델 선택 전략·파일 핸드오프·원장 패턴을 자신의 프로젝트에 적용 |
| 3주차 | 스킬 저작 + 평가(eval) 방법론 | writing-skills/SKILL.md + anthropic-best-practices.md 정독. 압박 시나리오로 자기 스킬을 검증하는 절차를 실습 |
| 4주차 | 새 플랫폼 이식 실습 | docs/porting-to-a-new-harness.md를 따라 아직 지원되지 않는 도구에 부트스트랩 훅을 이식. "인수 테스트" 트랜스크립트 확보 |
Kent Beck의 Test-Driven Development by Example은 Superpowers TDD 스킬의 직접적 뿌리다. 서브에이전트 오케스트레이션은 멀티 에이전트 시스템(격리된 컨텍스트·역할 분리·결과 집계) 일반론과 연결된다. 그리고 "스킬을 압박 시나리오로 평가한다"는 접근은 LLM 평가(eval) 방법론 전반과 맞닿아 있다.
이 프로젝트를 읽을 때 반복 등장하는 용어 정리.
| 키워드 | 뜻 |
|---|---|
| Composable Skills | 독립적이면서도 서로를 호출해 체인을 이루는 마크다운 스킬 단위 |
| Hard Gate | 특정 조건 충족 전 다음 단계 진행을 절대 허용하지 않는 스킬 내 제어 장치 |
| Iron Law | 스킬 내 "절대 위반 불가" 최상위 규칙(예: "NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST") |
| Rationalization Detection | 에이전트가 규칙을 어기려 할 때 쓸 변명을 사전에 표로 등록해 선제 반박하는 기법 |
| using-superpowers | 모든 세션 시작 시 주입되는 부트스트랩 스킬 |
| SessionStart 훅 | 세션 시작 이벤트에 using-superpowers 전문을 컨텍스트로 주입하는 셸 스크립트 메커니즘 |
| subagent-driven-development(SDD) | 태스크당 신규 서브에이전트 디스패치 + 2가지 판정(spec/quality) + 최종 전체 브랜치 리뷰 |
| task-brief / review-package | 태스크 명세·diff를 파일로 추출해 경로만 전달하는 스크립트 — 컨텍스트 오염 방지 |
| Progress Ledger | .superpowers/sdd/progress.md에 태스크 완료를 한 줄씩 기록해 컴팩션 후에도 재개 가능하게 하는 원장 |
| DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED | implementer 서브에이전트가 보고하는 4가지 상태 코드 |
| Global Constraints / Interfaces 블록 | writing-plans가 생성하는 계획 문서의 필수 요소 — 전역 규칙과 태스크 간 계약을 명시 |
| Visual Companion | 브레인스토밍 중 목업·다이어그램을 브라우저 탭에 표시하는 zero-dependency Node.js WebSocket 서버 |
| RED-GREEN-REFACTOR | TDD의 3단계 사이클: 실패하는 테스트 → 최소 구현 → 리팩토링 |
| 94% PR Rejection Rate | CLAUDE.md가 공개한 실제 기여 반려율 — AI 슬롭 PR을 걸러내는 엄격한 관문의 근거 |
원본을 직접 확인하고 싶을 때.