Superpowers — ‘클로드 코드를 제대로 쓴다’고 말하기 시작할 수 있는 최소한의 메타프레임

TL;DR

• Superpowers는 Jesse Vincent(obra)가 만든 Claude Code용 메타스킬 프레임워크다 — 단일 스킬 묶음이 아니라 에이전트의 작업 방식 자체에 의견을 가진 14개 스킬 + SessionStart 부트스트랩 패키지.
• 주 기능 3가지:
  1. 부트스트랩 자동 주입 — SessionStart 훅이 매 세션 시작 시 using-superpowers를 컨텍스트에 박아 1% 룰·HARD-GATE·우선순위(사용자 지시 > 스킬)를 시스템 프롬프트보다 위에 깐다.
  2. 작업 파이프라인 자동 트리거 — "X 만들어줘" 한 마디로 brainstorming → writing-plans → subagent-driven-development → requesting-code-review까지 자가 호출. 사용자가 스킬을 일일이 부를 필요가 없다.
  3. 품질 디시플린 상시 가동 — test-driven-development의 RED-GREEN-REFACTOR, systematic-debugging의 Iron Law, verification-before-completion이 항상 켜져 있어 "테스트 없이 패치"·"근본 원인 없이 우회"·"검증 없이 완료 선언"을 차단.
• 단독으로 쓰면 충분히 강하다. 다른 메타프레임·커스텀 슬래시·빠른 일회성 작업과 섞으면 충돌이 생기므로 §4의 7가지 패턴과 대응을 참고해 회피 — 95%는 AGENTS.md/CLAUDE.md 1장으로 해결된다.

1. Superpowers 소개

1.1. 무엇인가

obra/superpowers — Jesse Vincent(obra)가 만든 Claude Code용 메타스킬 플러그인. README는 자신을 "a complete software development methodology for your coding agents, built on top of a set of composable skills"라 소개한다 — 스킬 묶음이라기보다 에이전트가 코드를 짜는 방식 자체에 의견을 가진 프레임워크다. 14개 스킬 + SessionStart 부트스트랩 훅으로 구성되며, Claude Code 외에 Codex CLI·Cursor·Gemini CLI·Copilot CLI에도 같은 부트스트랩이 들어가도록 분기되어 있다.

1.2. 장점

• 스킬 호출이 자동화된다. 사용자가 "X 만들어줘"라고 한 마디만 해도 brainstorming → writing-plans → subagent-driven-development → requesting-code-review가 차례로 자가 호출된다. 슬래시를 일일이 칠 필요가 없다.
• 품질 디시플린이 항상 켜져 있다. TDD(RED-GREEN-REFACTOR), systematic-debugging의 Iron Law(근본 원인 없이 패치 금지), verification-before-completion(완료 선언 전 실제 검증)이 코드 작업 내내 디폴트로 작동한다.
• 하네스가 바뀌어도 행동이 일치한다. Claude Code뿐 아니라 Cursor·Copilot CLI 등에서도 같은 using-superpowers 메시지가 첫 컨텍스트에 들어가 일관된 우선순위·디시플린을 유지한다.
• 메타스킬 작성 가이드가 같이 들어 있다. writing-skills가 Cialdini·Meincke 설득 원리 기반의 베스트프랙티스를 깐다 — 자체 스킬을 추가할 때 그대로 활용 가능.

1.3. 설치

Claude Code 공식 마켓플레이스로 한 줄.

/plugin install superpowers@claude-plugins-official

또는 obra의 자체 마켓플레이스를 직접 추가하는 방식.

/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

설치 후 새 세션을 시작하면 SessionStart 훅이 자동 실행되며 using-superpowers/SKILL.md가 첫 컨텍스트에 주입된다 — 1% 룰·HARD-GATE가 별도 설정 없이 바로 켜진다.

2. 작동 구조 — 훅 → 부트스트랩 → 게으른 로드

2.1. SessionStart 훅으로 끼어드는 진입점

플러그인 루트 hooks/hooks.json의 SessionStart 매처는 startup|clear|compact다. 즉 새 세션·/clear·자동 압축 직후마다 부트스트랩 스크립트가 실행된다.

session-start 스크립트는 skills/using-superpowers/SKILL.md를 통째로 읽어 JSON으로 이스케이프한 뒤 컨텍스트에 주입한다 — Claude Code는 hookSpecificOutput.additionalContext, Cursor는 additional_context, Copilot CLI는 additionalContext 형식으로 분기. 즉 하네스가 무엇이든 같은 메시지가 첫 컨텍스트에 들어간다는 보장이 핵심 디자인 결정이다.

2.2. using-superpowers 스킬이 행동 규칙을 깐다

주입되는 using-superpowers/SKILL.md는 117줄의 짧은 부트스트랩이지만, 다음 세 가지를 못 박는다:

• 1% 룰 — 스킬이 적용될 가능성이 1%라도 있으면 호출해야 한다. "이건 너무 단순해서 안 써도 됨"을 차단하는 합리화 가드.
• 명령형 톤 — "YOU MUST", "Not negotiable", "No exceptions". 의도된 디자인이며, writing-skills/persuasion-principles.md에 Authority 원칙으로 명문화되어 있다(Meincke et al. 2025의 7개 설득 원리, N=28k 대화 — 33% → 72% 컴플라이언스 향상 인용).
• 사용자 우선 — CLAUDE.md·AGENTS.md·대화 직접 지시는 스킬보다 우선. 이건 Anthropic이 정한 룰이 아니라 obra가 명시적으로 깔아둔 우선순위다.

2.3. 14개 SKILL.md는 게으르게(lazy) 로드된다

부트스트랩은 목록만 컨텍스트에 두고, 실제 SKILL.md 본문은 Skill 툴로 호출되는 시점에 로드된다. 14개 스킬을 다 합치면 3,207줄이지만 세션 시작 시점에 들어가는 건 부트스트랩 117줄뿐. 컨텍스트 비용을 의식적으로 줄인 설계다.

호출 트리거는 두 갈래:

1. 모델 자가 호출 — description 매칭으로 알아서 호출 (brainstorming description: "You MUST use this before any creative work").
2. 사용자 명시 — /skill-name 슬래시 명령. 단 v5.1.0에서 /brainstorm, /execute-plan, /write-plan 같은 레거시 슬래시가 제거되어, 공식적으로는 자가 호출이 기본 경로다.

3. 14개 스킬 카탈로그

가장 많이 쓰는 5개 스킬

작업 한 사이클에서 사실상 매번 거치는 다섯.

brainstorming (164줄, 프로세스 게이트)

새 기능·동작 변경 발화가 들어오면 가장 먼저 트리거되는 HARD-GATE. 코드 쓰기 전 의도·요구사항·디자인을 사용자와 합의시킨다. SKILL.md가 "Every project goes through this process. A todo list, a single-function utility, a config change — all of them"이라 못 박아 예외를 봉쇄. 이 글에서 다룰 충돌 대부분이 여기서 시작된다.

writing-plans (152줄, 프로세스 게이트)

브레인스토밍에서 합의된 디자인을 실행 가능한 구현 계획서로 변환. 멀티 세션에 걸쳐 진행되는 작업에서 별도 컨텍스트로 옮길 수 있는 영구 산출물을 만든다. 다음 단계로 subagent-driven-development(권장) 또는 폴백으로 executing-plans에 넘긴다.

subagent-driven-development (279줄, 프로세스 게이트)

계획을 같은 세션 내에서 서브에이전트로 분산 실행 + 2단계 리뷰. executing-plans/SKILL.md가 명시적으로 "SDD 가능 시 그쪽으로 가라"라고 권하는 권장 경로. 메인 컨텍스트 오염을 막고 태스크 단위로 결과를 리뷰한다.

test-driven-development (371줄, 품질 디시플린)

새 기능·버그픽스 작업에 RED-GREEN-REFACTOR를 강제. 코드 작업 동안 디폴트로 항상 켜져 있어 "테스트 없이 짠 코드는 지워라"가 베이스라인. 코드가 아닌 작업(문서·설정 등)에 잘못 매칭되면 §4.5처럼 마찰이 생긴다.

systematic-debugging (296줄, 품질 디시플린)

버그·테스트 실패에 대해 Iron Law(근본 원인 없이 패치 금지)를 강제. 11개 보조 파일을 동반하는 무거운 스킬로, 가설 → 실험 → 검증 절차를 단계별로 가이드한다.

4. 다른 스킬·커스텀 절차와 같이 쓸 때 깨지는 지점

아래는 실제로 충돌을 겪어 적은 게 아니라, Superpowers의 훅·SKILL.md 정의를 읽고 어디서 부딪칠 수밖에 없는지 연역한 것이다.

4.1. brainstorming HARD-GATE vs 커스텀 절차 명령

가장 흔하다. "이 절차를 실행하라"가 명백한 자작 슬래시 명령(예: 매일 정보 수집 루틴, 정기 보고서 생성)에도 brainstorming description("You MUST use this before any creative work")이 매칭해서 "오늘 어떤 걸 만들까요?" 같은 디자인 단계가 먼저 뜬다.

왜 깨지는가: HARD-GATE는 의도적으로 강하게 설계됐다. brainstorming/SKILL.md는 "Every project goes through this process. A todo list, a single-function utility, a config change — all of them"이라고 못 박는다. "예외 없음"이 가드의 목적이다.

대응:

1. 프로젝트 AGENTS.md 또는 CLAUDE.md 최상단에 "이 디렉토리의 슬래시 명령은 모두 디자인이 끝난 작업이다. brainstorming 스킬을 호출하지 마라" 명시.
2. 커스텀 슬래시 명령(.claude/commands/<name>.md) 본문에 "이 명령은 이미 합의된 절차를 실행한다. 브레인스토밍 스킬 비활성화" 1줄 박기.
3. 작업 시작 시 사용자가 명시적으로 "브레인스토밍 스킵" 발화. PROFILE.md의 MVP 모드 같은 토글이 있으면 더 깔끔.

4.2. 1% 룰 + MVP/일회성 작업의 마찰

"한 줄만 고쳐줘"가 매번 스킬 체크 라운드로 돌아간다. 1% 룰의 Red Flags 표는 "This is just a simple question" 같은 사고를 합리화로 분류한다. 즉 단순함이 스킵 사유가 못 된다.

왜 깨지는가: 위반자가 모델 자신이 아니라 사용자인 케이스를 디자인이 거의 고려하지 않는다. obra의 의도는 "에이전트가 게으르지 못하게"인데, "에이전트가 너무 부지런해서" 사용자가 마찰을 느끼는 케이스가 반대급부.

대응: 스킬 무관 모드를 명시. PROFILE.md에 "사용자가 '브레인스토밍 스킵' 등을 선언한 경우 → 사용자 이전 결정 무시 가능" 같은 구문을 둔다(이 사이트의 PROFILE이 그렇게 되어 있다). 사용자 지시는 스킬보다 우선이라는 게 부트스트랩에 명문화돼 있어서 이 토글이 작동한다.

4.3. SessionStart 훅 중복 (다른 메타프레임워크 동시 설치 시)

addyosmani/agent-skills와 obra/superpowers는 둘 다 hooks/hooks.json으로 SessionStart 훅을 등록한다 — 같이 깔면 부트스트랩 메시지가 두 번 주입된다(obra는 using-superpowers, addyosmani는 자체 메타스킬 컨텍스트). 두 프레임이 비슷하지만 다른 우선순위 표를 깔면 모델이 어느 표를 따를지 흔들린다.

mattpocock/skills는 케이스가 다르다. 이쪽은 .claude-plugin/plugin.json이 스킬 매니페스트만 들고 있고 SessionStart 훅이 없다 — ~/.claude/skills/에 마크다운만 떨어뜨리는 형태라 훅 중복은 발생하지 않는다. 대신 스킬 이름 충돌(caveman·tdd 등이 superpowers의 동명 스킬과 겹칠 가능성)이 별개 문제.

왜 깨지는가: SessionStart 훅은 글로벌 컨텍스트에 메시지를 추가한다. 두 프레임이 다른 톤·다른 우선순위 선언을 동시에 주입하면 직접 충돌한다(obra의 알려진 이중 주입 버그는 obra/superpowers#648 참조).

대응: 부트스트랩 훅을 가진 메타프레임은 하나만. obra/superpowers를 베이스로 두고, addyosmani처럼 자체 SessionStart를 깔아두는 다른 메타프레임은 같이 깔지 않는다. mattpocock 스타일의 훅 없는 스킬 컬렉션은 .claude/skills 단위로 같이 임포트해도 무방하지만, 스킬 이름이 겹치는지는 미리 확인.

4.4. AGENTS.md 우선순위는 정책 파일이 있을 때만 작동

부트스트랩은 "사용자 명시 지시 > 스킬"이라고 박지만, CLAUDE.md/AGENTS.md/GEMINI.md 자체가 없으면 결정자가 사라진다. 이때 모델은 보수적으로 스킬 우선으로 기운다.

왜 깨지는가: 우선순위 표는 "사용자가 무언가를 명시했을 때" 작동한다. 빈 프로젝트는 명시 사항이 없으니 표가 무용지물.

대응: 얇아도 정책 파일을 둔다. 디렉토리에 AGENTS.md 한 줄짜리("이 프로젝트는 MVP 모드로 운영한다. 브레인스토밍·계획 단계 생략")만 있어도 우선순위 표가 작동한다. 빈 프로젝트일수록 더 필요.

4.5. TDD 스킬 + 코드가 아닌 작업

test-driven-development/SKILL.md는 "Always: New features, Bug fixes"를 강제 시나리오로 적는다. 그런데 코드가 아닌 작업(설정 변경, 문서 수정, 마크다운 글쓰기)에 작업 키워드("fix", "add", "implement")가 섞이면 TDD가 트리거된다.

왜 깨지는가: 스킬 description의 자가 매칭은 의미 기반이지만, 작업 발화의 어휘가 description의 트리거 어휘("New features, Bug fixes")와 겹치면 모델이 컨텍스트 차이를 약하게 평가한다.

대응: 작업 발화에서 키워드 의식적으로 회피("update", "rewrite"보다 "rephrase", "reword"). 또는 작업 시작 시 "이건 코드 변경 아님"을 1줄로 명시. 후자가 안정적.

4.6. dispatching-parallel-agents 자동 디스패치 vs 단일 컨텍스트 추적

description: "Use when facing 2+ independent tasks that can be worked on without shared state". 의도는 좋지만, "보안 리뷰 + 마이그레이션 + 데이터 변환" 같이 결정 추적이 중요해서 일부러 한 컨텍스트에 두려는 작업도 매칭된다.

왜 깨지는가: "독립적이면 병렬"이라는 룰이 너무 일반적이라 사용자의 의도("같이 추적해야 함")를 못 잡는다.

대응: 작업 시작 시 "이건 한 컨텍스트에서 같이 추적할 작업" 1줄 명시. 또는 결정 추적이 중요한 도메인(보안·금융·의료) 프로젝트의 AGENTS.md에 "병렬 디스패치 비활성화" 명시.

4.7. writing-skills의 무게

655줄짜리 메타스킬이다. "스킬 1개 만들어줘"라고 하면 압박 시나리오 + 서브에이전트 검증 루틴이 트리거된다. 정당한 디자인이지만 스킬 1개가 한 페이지 마크다운 정도면 충분한 케이스에는 과하다.

왜 깨지는가: writing-skills는 스킬을 행동을 강제하는 문서로 본다. 본문이 못 박는 룰은 "Iron Law: No skill without failing test first"(writing-skills/SKILL.md:651) — 스킬 없이 에이전트가 룰을 어기는 baseline(RED)과 스킬 적용 시 컴플라이언스(GREEN)를 서브에이전트로 직접 검증하는 RED-GREEN 매트릭스를 요구한다. 단순 메모 수준의 스킬에는 안 맞는 디자인.

대응: "이 스킬은 가벼운 메모용이라 압박 시나리오 검증 생략한다"고 명시하고 simple하게 작성. 또는 .md를 ~/.claude/skills/가 아닌 .claude/commands/에 두면 슬래시 명령으로 다뤄지고 writing-skills의 압박은 적용되지 않는다.

5. 종합 — Superpowers는 "강한 의견"의 프레임워크다

세 줄로 줄이면:

1. 단일 스킬셋이 아니다. SessionStart 훅 + 부트스트랩 + 14개 lazy-loaded 스킬로 구성된 에이전트 행동 프레임워크다.
2. 강한 우선순위 디자인. Authority·Commitment·Social proof 같은 설득 원리가 SKILL.md 본문에 의식적으로 박혀 있다(writing-skills/persuasion-principles.md 참고). 우연이 아니라 디자인.
3. 마찰의 원천도 그 의견에서 온다. brainstorming HARD-GATE, 1% 룰, TDD 강제 — 다 의도된 디자인이지만, 작업 컨텍스트가 안 맞으면 매번 부딪힌다. AGENTS.md/CLAUDE.md에 우선순위를 명시하는 것이 95%의 충돌을 해결한다.

운영 결론: Superpowers를 베이스로 깔고, 도메인 스킬·커스텀 슬래시 명령은 .claude/skills 또는 .claude/commands에 개별 단위로 추가. 두 번째 메타프레임을 같이 깔지 마라. AGENTS.md 한 페이지로 우선순위 가드레일을 깔아두면 대부분의 마찰이 사라진다.

참고

• obra/superpowers — v5.1.0 기준
• Superpowers RELEASE-NOTES.md — 2026-04-30 v5.1.0 변경사항 (legacy 슬래시 제거, 워크트리 스킬 재작성, 코드 리뷰 통합)
• writing-skills/persuasion-principles.md — Meincke et al. (2025) 기반 7개 설득 원리 적용 가이드
• Agent Skills 가이드 (addyosmani) — 비교 대상 메타프레임의 입장