이 저장소가 대체 무엇인가.
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 자동완성 | 줄 단위 제안, 프로세스 개념 없음 | 에이전트의 사고 순서 자체를 재편(설계→계획→구현→리뷰) |
일반 프롬프트가 "부탁"이라면, Superpowers의 Hard Gate는 "건축 인허가"다. 도면 승인 없이는 착공 자체가 불가능하듯, 설계 문서 승인 없이는 brainstorming 스킬이 구현 스킬 호출을 원천 차단한다. 그리고 "합리화 탐지(Rationalization Detection)" — 에이전트가 "이번만 테스트 건너뛸게" 같은 변명을 시도할 걸 미리 알고, 그 변명 목록 자체를 표로 박아 반박까지 준비해 둔다.
마크다운 스킬(제품) + Shell 부트스트랩(배관) + Node.js 시각화 서버(옵션) + 9개 플랫폼 어댑터.
package.json의 자기소개는 정확하다 — "Superpowers skills and runtime bootstrap for coding agents." 스택을 네 층으로 나눠 보면 역할이 명확해진다.
| 요소 | 설명 |
|---|---|
| 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 + marketplace.json | /plugin install superpowers@claude-plugins-official |
| Cursor | .cursor-plugin/plugin.json | /add-plugin superpowers |
| Codex App/CLI | .codex-plugin/plugin.json + .agents/plugins/marketplace.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 (TypeScript) | pi install git:github.com/obra/superpowers — 네이티브 스킬 지원, 호환 shim 불필요 |
| 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 |
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의 실행 모델은 크게 "부트스트랩 → 워크플로 스킬 체인 → 서브에이전트 오케스트레이션" 세 층으로 이해하면 된다. 전체 흐름을 그림으로 보면 이렇다.
각 스킬은 절대 건너뛸 수 없는 관문을 <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." — 자기 기억보다 원장과 git 로그를 신뢰하라고 명시한다. 릴리스 노트는 이 문제의 실제 비용도 밝힌다: "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")로 전면 재작성했다. "Claude"라는 단어도 대부분 "your agent"로 바뀌었다. 대신 skills/using-superpowers/references/에 플랫폼별 매핑 파일(codex-tools.md·pi-tools.md·antigravity-tools.md)을 두어, 하네스별 특이사항만 그쪽에서 보충한다.
skills/가 본체, 9개 플랫폼 매니페스트가 얇게 둘러싸고, tests/와 신설된 evals/가 품질을 지킨다.
다섯 덩어리로 나눠 읽으면 명료하다.
① 스킬 본체 skills/. 14개 디렉토리, 각각 SKILL.md 하나가 핵심이고 100줄 넘는 참조 자료만 별도 파일로 분리된다. 가장 무거운 것은 subagent-driven-development/로, 프롬프트 템플릿 2개와 스크립트(task-brief·review-package)까지 포함한다.
② 부트스트랩 hooks/. 플랫폼마다 다른 JSON 스키마를 하나의 bash 스크립트가 분기 처리한다. Windows 지원을 위한 run-hook.cmd 폴리글랏 트릭도 여기 있다.
③ 플랫폼 어댑터 9종. 각 어댑터는 대개 매니페스트 JSON 한두 개로 끝나는 "얇은 껍데기"다 — 실제 콘텐츠(스킬)는 공유되고, 어댑터는 그걸 각 플랫폼의 플러그인 시스템에 등록하는 역할만 한다. 유일한 예외가 Pi(TypeScript 확장)와 OpenCode(JS 플러그인 + 캐싱 로직)로, 약간의 런타임 코드를 포함한다.
④ tests/ vs evals/(서브모듈, 클론 안 됨). v6.0.0부터 테스트가 둘로 나뉜다 — tests/는 "플러그인 코드가 플랫폼별로 올바르게 동작하는가"(설치 스크립트·훅·매니페스트), evals/는 별도 저장소(superpowers-evals)에서 실제 tmux 세션으로 Claude Code/Codex를 구동해 "스킬이 에이전트 행동을 실제로 바꾸는가"를 LLM 심사관으로 평가한다. 이 저장소를 얕은 클론(--depth 1)했을 때는 evals 서브모듈이 딸려오지 않는다는 점에 주의(v6.0.2에서 아예 서브모듈 배포를 중단했다).
⑤ 거버넌스 문서 CLAUDE.md. 8.8KB짜리 이 파일이 사실상 "이 저장소에 기여하려면 통과해야 할 체크리스트"다. AGENTS.md는 이 파일의 심볼릭 링크라, Claude Code든 다른 에이전트든 같은 규약을 읽는다.
이 저장소에서 "무엇을 배울 수 있는가" — 개념 → 코드 위치 → 실습 아이디어.
스킬을 감이 아니라 가설 검증으로 만드는 절차를 실물로 배운다. 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 허용목록만으로 막을 수 없는 이유"를 세션 키 방식과 비교해 정리.
마크다운 중심이라 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 불필요, Node 자체만 있으면 됨 |
| 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 호출·토큰 소비가 늘어난다. v6.0.0 릴리스 노트가 "50% 토큰 절감"을 자랑하는 것도 거꾸로 말하면 v5 이하에서는 그만큼 비용이 컸다는 뜻이다. 모델 선택 전략(4장)을 실제로 지키는지가 비용 체감의 핵심이다.
9개 플랫폼을 지원한다고 모두 동일한 성숙도는 아니다. CLAUDE.md의 "신규 하네스 지원" 기준은 "a real integration loads the using-superpowers bootstrap at session start"인데, 과거 여러 시도가 이 기준을 통과하지 못해 반려됐다. 또한 v6.1.0에서 Gemini CLI 지원이 통째로 제거된 사례처럼, 업스트림 플랫폼의 정책 변화가 곧바로 지원 중단으로 이어질 수 있다. 특정 플랫폼용으로 이 도구를 도입하기 전, README의 최신 Quickstart 목록을 반드시 재확인해야 한다.
난이도별로 손을 움직여 보는 5가지.
Claude Code(또는 지원 플랫폼)에 설치하고, 새 대화에서 "간단한 CLI 투두 앱 만들어줘"라고만 요청한다.
# Claude Code
/plugin install superpowers@claude-plugins-official에이전트가 코드를 바로 쓰지 않고 "using brainstorming to..."를 선언하며 질문을 시작하는지 관찰한다. CLAUDE.md의 "신규 하네스 인수 테스트"와 똑같은 절차를 스스로 체험하는 셈이다.
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 핸드셰이크로 어떻게 전달되는지 추적한다. 이어서 docs/superpowers/specs/2026-03-11-zero-dep-brainstorm-server-design.md 설계 문서와 실제 구현을 대조해, "설계서가 실제로 무엇을 놓치거나 바꿨는지" 찾아본다.
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" 순서대로 실전 적용. 각 스킬의 Hard Gate 목록 정리 |
| 2주차 | 서브에이전트 오케스트레이션 심화 | subagent-driven-development/SKILL.md 전문 정독 + 모델 선택 전략·파일 핸드오프·원장 패턴을 자신의 프로젝트에 적용. dispatching-parallel-agents로 독립 문제 병렬 처리 실습 |
| 3주차 | 스킬 저작 + 평가(eval) 방법론 | writing-skills/SKILL.md + anthropic-best-practices.md 정독. 압박 시나리오로 자기 스킬을 검증하는 절차를 실습. superpowers-evals 저장소의 drill 하네스 구조 파악 |
| 4주차 | 새 플랫폼 이식 실습 | docs/porting-to-a-new-harness.md를 따라 아직 지원되지 않는 도구(예: Aider, Continue)에 부트스트랩 훅을 이식. CLAUDE.md의 "인수 테스트"(리액트 투두 요청 시 brainstorming 자동 트리거)를 통과하는 세션 트랜스크립트 확보 |
Kent Beck의 Test-Driven Development by Example은 Superpowers TDD 스킬의 직접적 뿌리다. 서브에이전트 오케스트레이션은 멀티 에이전트 시스템(격리된 컨텍스트·역할 분리·결과 집계) 일반론과 연결된다. 그리고 "스킬을 압박 시나리오로 평가한다"는 접근은 LLM 평가(eval) 방법론 전반 — 특히 "행동을 형성하는 프롬프트를 어떻게 검증할 것인가"라는 질문과 맞닿아 있다.
이 프로젝트를 읽을 때 반복 등장하는 용어 정리.
| 키워드 | 뜻 |
|---|---|
| Composable Skills | 독립적이면서도 서로를 호출해 체인을 이루는 마크다운 스킬 단위 |
| Hard Gate | 특정 조건 충족 전 다음 단계 진행을 절대 허용하지 않는 스킬 내 제어 장치(<HARD-GATE> 태그) |
| Iron Law | 스킬 내 "절대 위반 불가" 최상위 규칙(예: "NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST") |
| Rationalization Detection | 에이전트가 규칙을 어기려 할 때 쓸 변명을 사전에 표로 등록해 선제 반박하는 기법 |
| using-superpowers | 모든 세션 시작 시 주입되는 부트스트랩 스킬. "1% 확률이라도 스킬이 관련되면 호출해야 한다"는 규칙의 근원 |
| 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단계 사이클: 실패하는 테스트 → 최소 구현 → 리팩토링 |
| Root Cause Tracing | 콜스택을 역추적해 에러의 근본 원인을 찾는 systematic-debugging의 기법 |
| Skill Discovery Optimization | 구 "Claude Search Optimization"의 개명(v6.0.0) — 벤더 중립 용어로 교체 |
| Zero-Dependency | Superpowers 핵심 원칙 — 서드파티 의존성이 필요한 기여는 별도 플러그인으로 분리 |
| 94% PR Rejection Rate | CLAUDE.md가 공개한 실제 기여 반려율 — AI 슬롭 PR을 걸러내는 엄격한 관문의 근거 |
| Porting Acceptance Test | 신규 플랫폼 지원 PR의 통과 기준 — "리액트 투두앱 만들어줘"에 brainstorming이 자동 트리거되는 세션 트랜스크립트 필수 |
원본을 직접 확인하고 싶을 때.