obra/superpowers로 만드는 자율 코딩 워크플로우: 6주 실전 사용기

지난 6주간 obra/superpowers를 Claude Code에 얹어 쓰면서 가장 크게 바뀐 건 PR을 다시 열어보는 횟수였다. 그 전까지는 에이전트가 만든 PR을 받으면 "일단 한번 보자"는 마음으로 모든 라인을 따라 읽었는데, 지금은 작업 단위가 잘게 쪼개져 있고 테스트가 먼저 들어 있어 변경의 의도가 한눈에 들어온다.

이 글은 superpowers를 막 도입했거나 도입을 고민 중인 분께, 무엇이 좋고 어디가 까다로운지를 솔직히 정리한 노트다.

superpowers는 무엇인가

한 줄로 말하면 "코딩 에이전트를 위한 개발 방법론을 스킬 형태로 묶어둔 라이브러리"다. Jesse Vincent(Prime Radiant)가 메인테이너이며, MIT 라이선스로 공개되어 있다. 글 쓰는 시점 기준 깃허브 별이 수만 단위로 빠르게 늘고 있고, 포크와 이슈/PR 활동량 모두 활발하다 — 에이전트 도구 카테고리에서 사실상 가장 빠르게 자리 잡은 프로젝트 중 하나다.

핵심 철학은 세 줄로 요약된다.

• 체계성 > 즉흥성 — 추측 대신 정의된 프로세스
• TDD 강제 — RED → GREEN → REFACTOR를 건너뛸 수 없다
• 검증 후 완료 — 통과한 테스트와 명시적 확인 없이는 "끝났다"가 없다

7단계 워크플로우

superpowers의 동작 단위는 7개의 스킬이다. 각 스킬은 작업의 특정 단계에 진입하면 자동으로 활성화된다.

1. Brainstorming — 코드 한 줄도 쓰기 전에 발동된다. 거친 아이디어를 질문으로 정제하고, 대안을 펼치고, 설계 문서를 디스크에 남긴다.
2. Using-git-worktrees — 설계가 승인되면 새 브랜치 + 격리된 워크트리를 자동 생성한다. main 브랜치가 오염되지 않는다.
3. Writing-plans — 작업을 2~5분짜리 미니 태스크로 쪼갠다. 각 태스크는 정확한 파일 경로, 작성할 코드, 검증 방법을 명시한다.
4. Subagent-driven-development — 미니 태스크마다 새 서브에이전트를 띄워 처리한다. 작업 끝마다 두 단계 검토(사양 준수 → 코드 품질)를 거친다.
5. Test-driven-development — RED-GREEN-REFACTOR. 실패하는 테스트가 먼저 없으면 코드는 폐기된다.
6. Requesting-code-review — 작업 사이사이 자동으로 트리거되며, 심각도별로 문제를 보고한다. 중대한 문제는 다음 단계로 못 가게 막는다.
7. Finishing-a-development-branch — 모든 테스트 검증 후 병합/PR/유지/폐기 옵션을 제시하고 워크트리를 청소한다.

체감하는 차이는 3번과 4번에서 가장 크다. 작업이 미니 태스크 단위로 떨어져 있으니 중간에 컨텍스트를 잃지 않고, 각 태스크가 독립적이라 실패해도 그 단위만 다시 돌리면 된다.

설치 (Claude Code 기준)

가장 짧은 경로는 공식 플러그인 마켓플레이스를 거치는 것이다.

/plugin install superpowers@claude-plugins-official

별도 마켓플레이스를 추가하고 싶다면 다음과 같이 설치한다.

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

설치 후 Claude Code 세션을 새로 시작하면 스킬이 자동 등록된다. 별도 설정 파일을 손볼 필요는 없다.

Codex, Gemini CLI, Cursor, GitHub Copilot CLI 같은 다른 에이전트 환경에서도 동일한 스킬 라이브러리를 쓸 수 있다. 각 도구마다 설치 명령만 다르므로 자세한 건 README를 참고하자.

실전에서 가장 자주 쓰는 스킬 셋

전체 스킬을 다 쓰진 않는다. 6주 동안 손이 가장 많이 간 건 다음 셋이다.

1) systematic-debugging

기본 디버깅 흐름을 4단계(investigate → analyze → hypothesize → implement)로 강제한다. 가장 큰 효과는 "근본 원인 없이 패치 금지" 라는 규칙. "일단 이거 try-catch로 감싸자"가 사라진다. 디버깅 끝나면 그 자리에서 회귀 테스트가 한 줄 더 추가되어 있는 건 덤이다.

2) dispatching-parallel-agents

여러 독립 작업을 병렬 서브에이전트로 동시에 돌린다. 예를 들어 "마이그레이션 5개를 각각 다른 서비스에 적용" 같은 일이 한 번에 끝난다. 단, 의존성이 있는 작업을 잘못 병렬화하면 락이나 데이터 충돌이 나니 사전에 의존성을 끊어두는 작업이 필요하다.

3) writing-plans

기획 문서가 없는 1인 프로젝트에서 자기 자신에게 명세를 쓰는 도구로 잘 맞는다. "오늘 밤 안에 이거 끝낸다"라고 채팅창에 던지면 superpowers가 그걸 30분 단위 작업 네 개로 쪼개주는 식이다.

자동 트리거가 기본, 슬래시는 강제용

처음 도입했을 때 가장 헷갈렸던 건 "그래서 슬래시 커맨드를 어떻게 쳐야 하는가"였다. 답은 두 줄이다.

• 기본은 자동. README의 표현을 그대로 빌리면 "because the skills trigger automatically, you don't need to do anything special" — 평소처럼 자연어로 일을 시키면 superpowers가 작업 성격을 보고 알맞은 스킬을 자기 판단으로 발동시킨다. 작업 단계가 진입할 때 "The agent checks for relevant skills before any task. Mandatory workflows, not suggestions" 라는 강제 규칙이 함께 박혀 있어, 모델이 단계를 건너뛰는 일이 거의 없다.
• 그러나 명시 호출용 슬래시 커맨드도 함께 제공된다. marketplace에 정의된 핵심 명령은 다음 셋이다:
  • /brainstorm — 설계 단계로 강제 진입
  • /write-plan — 계획 작성을 강제로 띄움
  • /execute-plan — 승인된 계획을 명령 한 줄로 실행 시작
• 일상적으로는 자연어로 충분하다. 슬래시는 자동 트리거가 어긋났을 때, 또는 단계를 강제로 분리하고 싶을 때의 보조 도구로 두면 된다.

실제로 던지는 프롬프트 예시

아래는 6주 동안 가장 자주 쓴 프롬프트 패턴 네 가지다. 모두 슬래시 없이 자연어만 던진 케이스이고, 자동 트리거에 의존한다.

1) 신규 기능 추가 — 풀 7단계 발동

Stripe 결제 모듈을 추가해줘. 결제 성공/실패 모두 웹훅으로 처리하고
이벤트 로깅도 포함. 기존 user-service의 인증 흐름은 건드리지 않는 선에서.

이 한 줄로 Brainstorming → Writing-plans → Subagent-driven-development → TDD → Review → Finishing까지 거의 모든 단계가 차례로 돈다. 사람이 개입하는 시점은 두 곳 — 설계 승인("이 방향 OK") 과 계획 승인("go") 뿐이다. 나머지는 서브에이전트가 알아서 처리하고, 마지막에 PR 후보를 들고 다시 등장한다.

2) 버그 수정 — systematic-debugging이 메인

결제 처리 중 간헐적으로 발생하는 timeout을 디버깅해줘.
재현은 안 되지만 로그는 prod-2026-05.log 에 5건 있어.
근본 원인 찾을 때까지 패치 금지.

근본 원인 찾을 때까지 패치 금지 한 줄이 핵심이다. 이게 없어도 systematic-debugging이 4단계를 돌긴 하지만, 명시하면 모델이 도중에 "일단 try-catch로 감싸볼까요?"를 시도하지 않는다. 결과는 "가설 3개 → 각각 검증 → 1개 채택 → 회귀 테스트와 함께 패치" 라는 형태로 떨어진다.

3) 리팩토링/마이그레이션 — writing-plans + worktree

user-service의 인증 로직을 별도 auth-service 모듈로 분리해줘.
기존 호출자 영향 없이, 단계별로 안전하게.
계획부터 보여주고 승인받아.

이 패턴에서 가장 큰 가치는 계획부터 보여주고 승인받아 한 줄이다. writing-plans가 30분 단위 작업 5~7개로 분해해 보여주고, 사람이 한 번 승인하면 그 다음부터는 워크트리에서 독립 실행된다. main이 절대 깨지지 않는 게 보장되니 점심시간에 켜놓고 자리를 비울 수 있다.

4) 여러 모듈 병렬 작업 — dispatching-parallel-agents

lib/payments, lib/orders, lib/notifications 세 모듈에 각각
동일한 logging middleware를 추가해줘. 의존성 없으니 병렬로 처리해도 됨.

의존성 없으니 병렬로 처리해도 됨 단서가 dispatching-parallel-agents를 깨운다. 세 모듈이 동시에 처리되어 직렬 처리 대비 시간이 1/3 수준으로 줄어든다. 단, 의존성이 있는 작업에 잘못 이 단서를 붙이면 락 충돌이 나니 신중하게.

패턴이 보이는가

네 케이스에서 공통되는 건 "의도 + 제약 + 진행 방식" 의 세 줄 구조다.

• 의도: 무엇을 원하는가 (Stripe 모듈 추가, timeout 디버깅, 모듈 분리)
• 제약: 무엇을 건드리면 안 되는가, 무엇은 반드시 해야 하는가 (기존 인증 흐름 건드리지 마, 근본 원인 찾을 때까지 패치 금지)
• 진행 방식: 어떤 흐름으로 가야 하는가 (계획부터 보여주고 승인받아, 병렬로 처리해도 됨)

이 세 줄만 명시해도 superpowers는 자기가 어떤 스킬을 발동할지 알아서 결정한다. 자연어로 의도와 경계를 그려주는 것이 일상적 사용법이다.

자동 트리거가 어긋날 때 — 슬래시 호출

자연어가 80%를 해결해주지만, 자동 트리거가 작업 한 단계를 건너뛰거나 너무 일찍 다음 단계로 넘어갈 때가 가끔 있다. 그때 쓰는 게 marketplace에 정의된 슬래시 셋이다.

• /brainstorming — 모델이 설계를 건너뛰고 바로 코드를 짜려 들 때 강제로 설계 단계를 띄운다. "잠깐, 먼저 큰 그림부터 잡고 가자"가 필요한 순간.
• /writing-plans — 설계는 끝났는데 모델이 곧장 코딩으로 진입하려 할 때, 미니 태스크 단위 계획을 강제로 출력시킨다. 점심 먹으러 자리 비울 때 특히 유용하다 — 계획을 보고 떠나면 돌아왔을 때 결과 검증이 쉽다.
• /executing-plans — 승인된 계획을 한 줄로 실행 개시. 계획을 띄워놓고 다른 채팅 흐름이 끼어들었다가 돌아올 때 "이거 그대로 돌려" 신호로 가장 깔끔하다.

세 명령어의 공통점: 워크플로우 단계 사이의 경계를 사람이 명시적으로 끊는 것. 자동 트리거가 한 흐름으로 이어 처리하려는 걸 일부러 멈춰 세우고, 단계 결과물을 검증한 뒤 다음으로 넘어가게 만든다. 자연어 프롬프트가 의도를 그리는 도구라면, 이 셋은 속도를 조절하는 도구에 가깝다.

그 외에 using-superpowers, writing-skills 같은 메타 스킬이 README에 언급되지만, 정확한 슬래시 호출 인터페이스는 README/marketplace 페이지만으로는 단정하기 어렵다 — 본인 환경에서 /help로 한 번 확인해 보길 권한다.

함정 — 알고 들어가면 좋은 것들

좋은 점만 말하면 거짓말이다. 도입하면서 만난 까다로운 지점들:

• 시작 비용이 있다. 에이전트가 코드 한 줄을 짜기 전에 브레인스토밍과 계획 단계에서 10~20분이 소비된다. "한 줄 수정하고 PR 만들기" 같은 작은 작업에는 오히려 무겁다. 30분 이상 걸릴 일에만 켜는 게 합리적이다.
• TDD를 회피하면 작업이 안 끝난다. 실패 테스트를 먼저 안 쓰면 코드를 폐기해버리는 규칙이 있어, "에이 그냥 빠르게 짜고 나중에 테스트 붙이지"가 안 된다. 익숙해지기 전엔 답답할 수 있다.
• 워크트리 청소를 잊지 말 것. 7단계가 끝까지 가지 않으면 워크트리가 그대로 남아 디스크가 차오른다. git worktree list를 가끔 점검하자.
• 모델 토큰 사용량이 늘어난다. 서브에이전트, 검토, 계획 작성이 모두 별도 컨텍스트를 쓰므로, 가벼운 작업 대비 토큰 비용이 1.5~2배까지 늘 수 있다. 비용 민감 환경이면 워크플로우 일부만 켜는 식의 튜닝이 필요하다.

누구에게 추천하나

• 추천: 매일 에이전트로 30분 이상 걸리는 작업을 굴리는 사람. 작업이 다단계로 끊기는 백엔드, 리팩토링, 마이그레이션 일이 많을수록 ROI가 좋다.
• 보류: 단순 스크립트나 한두 줄 수정 위주의 작업이 많은 환경. 시작 오버헤드가 그 비용을 넘어선다.
• 반드시 도입: 팀 단위로 에이전트 PR을 받는 환경. 일관된 워크플로우가 PR 리뷰 시간을 직접적으로 줄인다.

마무리

superpowers의 진짜 가치는 "에이전트가 더 똑똑해진다"가 아니라, 에이전트의 작업 방식을 사람이 예측할 수 있게 만들어준다는 점이라고 본다. 똑같은 모델(Opus 4.7, Sonnet 4.6)을 써도 결과의 분산이 줄어드니 PR을 받는 쪽이 편해진다.

다음 글에서는 superpowers의 writing-skills 스킬로 자기 프로젝트에 맞는 커스텀 스킬을 만든 경험을 정리할 예정이다.