Superpowers 사용법: Claude Code Codex에 TDD 개발 워크플로 적용하기

Superpowers는 AI 코딩 에이전트가 곧바로 코드를 고치지 않고 요구사항 정리, 구현 계획, 테스트 우선 개발, 코드 검토, 완료 검증을 차례로 따르게 하는 오픈소스 개발 방법론입니다. 단일 만능 스킬이 아니라 여러 Agent Skill과 초기 지침을 연결한 워크플로에 가깝습니다.

2026년 9월 1일 GitHub REST API 조회 당시 obra/superpowers 저장소는 별 280,305개를 기록했고, 최신 공개 릴리스는 2026년 8월 12일 게시된 v6.3.0이었습니다. 별은 저장소에 대한 관심 신호일 뿐 설치 수, 사용자 수, 품질을 뜻하지 않습니다. 버전과 설치법도 바뀔 수 있으므로 실제 설치 전 README와 Releases를 다시 확인해야 합니다.

이 글의 설치 및 실습 명령은 조사 자료를 바탕으로 작성한 미검증 예제입니다. 필자가 해당 명령을 실행하거나 결과를 재현했다고 주장하지 않습니다.

 

이 글에서 사용하는 주요 용어 정의

용어	이 글에서의 뜻
Agent Skill	에이전트가 특정 상황에서 따라야 할 절차와 도구 사용법을 담은 재사용 가능한 지침입니다.
플러그인	스킬 같은 기능 묶음을 에이전트 하네스에 설치하고 배포하는 단위입니다.
하네스	Claude Code, Codex App, Codex CLI처럼 모델에 파일·터미널·도구 사용 환경을 제공하는 실행 프로그램입니다.
TDD	실패하는 테스트를 먼저 만들고 최소 구현으로 통과시킨 뒤 구조를 개선하는 RED→GREEN→REFACTOR 방식입니다.
subagent-driven development	작은 작업을 서브에이전트에 나누고 명세 준수와 코드 품질을 단계적으로 검토하는 개발 흐름입니다.
git worktree	한 저장소의 다른 브랜치를 별도 작업 디렉터리에 펼쳐 기존 작업과 격리하는 Git 기능입니다.

 

Superpowers란 무엇인가

원저자 README는 Superpowers를 구성 가능한 스킬과 초기 지침으로 만든 소프트웨어 개발 방법론으로 설명합니다. 코드 생성 기능 하나를 추가하기보다 에이전트가 개발 단계마다 어떤 증거를 남겨야 하는지 정합니다.

대표 흐름은 다음과 같습니다.

brainstorming
  → using-git-worktrees
  → writing-plans
  → subagent-driven-development 또는 executing-plans
  → test-driven-development
  → requesting-code-review
  → verification-before-completion
  → finishing-a-development-branch

저장소는 관련 스킬이 상황에 맞춰 자동으로 활성화되는 방식을 의도합니다. 하지만 실제 준수 여부는 모델, 하네스, 현재 컨텍스트와 권한에 따라 달라질 수 있습니다. 중요한 단계는 “스킬이 알아서 했을 것”이라고 추정하지 말고 생성된 계획, 테스트 출력과 diff로 확인해야 합니다.

루프 엔지니어링과도 초점이 다릅니다. 루프가 같은 목표를 반복 실행하는 제어 방식이라면 Superpowers는 각 개발 단계의 진입 조건과 검증 조건을 스킬로 제공합니다.

 

Superpowers가 코딩 작업을 처리하는 순서

 

1. brainstorming: 코드를 쓰기 전에 설계한다

brainstorming은 에이전트가 요구사항을 질문하고 대안을 검토한 뒤 설계 승인을 받도록 유도합니다. 여기서 확인할 것은 기능 이름보다 경계 조건입니다.

예를 들어 slugify(text)를 만든다면 다음 항목을 먼저 정합니다.

• 공백은 하이픈으로 바꾸는가
• 영문 대문자는 소문자로 바꾸는가
• 연속 하이픈은 하나로 줄이는가
• 빈 문자열은 어떻게 처리하는가
• 한글과 특수 문자는 유지하는가, 제거하는가

이 단계의 결과는 승인된 짧은 설계안입니다. 코드가 먼저 생겼다면 Superpowers가 의도한 순서대로 진행됐는지 다시 확인할 필요가 있습니다.

 

2. writing-plans와 git worktree: 계획과 작업 공간을 분리한다

writing-plans는 구현을 파일 단위의 작은 작업으로 나눕니다. 좋은 계획에는 수정할 경로, 먼저 작성할 테스트, 구현 범위와 검증 명령이 들어갑니다.

using-git-worktrees는 작업 브랜치를 별도 디렉터리에 펼쳐 현재 작업 공간과 분리합니다. worktree 자체가 안전을 보장하지는 않습니다. 시작 전에 현재 저장소의 미커밋 변경과 대상 브랜치를 확인하고, 첫 실습은 업무 저장소가 아닌 작은 샘플 저장소에서 진행하는 편이 낫습니다.

 

3. TDD와 subagent-driven development: 테스트와 검토를 작업 단위에 붙인다

test-driven-development는 RED→GREEN→REFACTOR 순서를 요구합니다.

1. RED: 요구사항을 나타내는 테스트를 작성하고 올바른 이유로 실패하는지 확인합니다.
2. GREEN: 테스트를 통과시키는 최소 구현을 작성합니다.
3. REFACTOR: 테스트가 통과하는 상태를 유지하며 중복과 복잡성을 줄입니다.

subagent-driven-development를 쓸 때는 작업을 맡은 서브에이전트의 결과를 바로 완료 처리하지 않습니다. README가 설명한 흐름은 먼저 명세 준수를 확인하고, 그다음 코드 품질을 검토하는 두 단계 검토입니다. 하네스가 서브에이전트를 지원하지 않거나 사용하지 않는다면 executing-plans로 계획을 순서대로 수행할 수 있습니다.

 

4. 코드 리뷰와 verification: 새 증거로 완료를 판단한다

Superpowers는 완료를 선언하기 전에 테스트 출력 같은 새 증거를 요구하는 verification-before-completion 원칙을 둡니다. “구현상 문제없다”는 설명만으로는 부족합니다.

확인할 증거는 다음과 같습니다.

단계	확인할 산출물
설계	질문, 합의된 경계 조건, 승인된 설계안
계획	수정 파일, 작은 작업 목록, 검증 명령
RED	예상한 이유로 실패한 테스트 출력
GREEN	같은 테스트가 통과한 출력
검토	명세 누락과 코드 품질 지적 및 반영 내역
완료	전체 테스트 결과, git status, git diff --stat

마지막에는 브랜치를 병합할지, PR로 보낼지, 보관하거나 폐기할지 결정합니다. 병합과 삭제는 저장소 상태와 사용자의 승인을 확인한 뒤 수행해야 합니다.

 

설치 전 확인할 것

외부 스킬은 에이전트의 행동과 도구 사용을 바꿀 수 있습니다. 다음 조건을 갖춘 뒤 설치합니다.

• Git을 사용할 수 있고 테스트가 통과하는 독립 샘플 저장소
• 미커밋 변경이 없는 격리 브랜치 또는 별도 worktree
• 설치할 저장소, 릴리스 또는 태그 확인
• 플러그인 안의 SKILL.md, hooks와 초기 지침 검토
• 파일 수정, 셸 실행, 네트워크 접근 등 하네스 권한 확인
• Claude Code 또는 Codex 버전과 설치 날짜 기록

2026년 9월 1일 공식 README의 Visual companion telemetry 안내에 따르면, brainstorming의 선택적 visual companion은 기본적으로 Prime Radiant 웹사이트에서 로고를 불러오며 사용 중인 Superpowers 버전을 전달합니다. 프로젝트, 프롬프트, 코딩 에이전트의 세부 정보와 클릭은 보내지 않는다고 명시돼 있습니다. 외부 요청을 막으려면 설치 전에 SUPERPOWERS_DISABLE_TELEMETRY를 참 값으로 설정하거나 Claude Code의 DISABLE_TELEMETRY, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 옵트아웃을 확인해야 합니다.

여러 하네스를 함께 쓴다면 각각 설치해야 합니다. Superpowers 설치 문서는 Claude Code, Codex App과 Codex CLI의 설치 경로를 따로 안내합니다.

 

Claude Code에 Superpowers 설치하기

아래 문장은 PowerShell 명령이 아니라 Claude Code 세션 안에서 입력하는 slash command입니다.

/plugin install superpowers@claude-plugins-official

 

이 경로는 원저자 README와 Anthropic의 Superpowers 플러그인 페이지에 안내돼 있습니다. 설치 후 새 세션을 열고 작은 설계 요청으로 스킬이 노출되는지 확인합니다.

Superpowers 워크플로를 사용해 slugify 함수의 요구사항만 정리해 주세요.
아직 코드는 작성하지 말고, 확인이 필요한 경계 조건을 먼저 질문해 주세요.

 

예상 관찰 지점은 에이전트가 바로 코드를 생성하는 대신 질문하고 설계안을 제시하는지 여부입니다. 자동 트리거가 되지 않으면 설치 상태, 새 세션 여부와 현재 스킬 목록을 확인합니다. 제품 버전에 따라 확인 UI와 명령이 달라질 수 있으므로 실제 화면을 기준으로 기록합니다.

미검증 안내: 위 설치 명령과 확인 프롬프트는 이 원고 작성 과정에서 실행하지 않았습니다. 설치 성공 출력도 제시하지 않습니다.

 

Codex App과 Codex CLI에 설치하기

Codex App에서는 원저자 README가 안내하는 대로 Plugins 사이드바 → Coding → Superpowers → + 순서로 설치합니다.

Codex CLI에서는 Codex 세션 안에서 /plugins를 열고 superpowers를 검색한 뒤 Install Plugin을 선택합니다. Claude Code용 /plugin install ... 명령을 Codex에 그대로 입력하는 방식이 아닙니다.

환경	설치 진입점	입력 위치
Claude Code	/plugin install superpowers@claude-plugins-official	Claude Code 세션
Codex App	Plugins → Coding → Superpowers → +	앱 UI
Codex CLI	/plugins → 검색 → Install Plugin	Codex CLI 세션

미검증 안내: 위 Codex UI와 slash command는 원저자 README의 2026년 9월 1일 조사 내용을 옮긴 것입니다. 이 원고 작성 과정에서는 앱 또는 CLI에서 설치하지 않았습니다.

 

작은 기능으로 워크플로 실습하기

첫 실습은 외부 API나 자격 증명이 필요 없는 기능이 적합합니다. 여기서는 문자열을 URL 경로에 쓰기 좋은 형태로 바꾸는 slugify(text) 함수를 예로 듭니다.

 

실습 성공 조건

• 경계 조건을 구현 전에 합의합니다.
• 실패 테스트를 실제로 관찰합니다.
• 테스트를 통과하는 최소 구현만 추가합니다.
• 명세 검토와 코드 품질 검토를 구분합니다.
• 전체 테스트와 Git 변경 내역을 마지막에 확인합니다.

 

첫 프롬프트

다음 프롬프트를 Claude Code 또는 Codex 중 한 환경의 독립 샘플 저장소에서 사용합니다.

Superpowers 워크플로를 사용해 slugify(text) 함수를 설계하고 구현해 주세요.

코드를 쓰기 전에 공백, 대소문자, 연속 구분자, 빈 문자열,
한글과 특수 문자 처리 방식을 질문해 주세요.
제가 설계를 승인하면 파일별 구현 계획을 작성하세요.
그다음 실패하는 테스트를 먼저 실행해 RED를 확인하고,
최소 구현으로 GREEN을 만든 뒤 코드 검토와 전체 테스트를 진행하세요.
각 단계에서 확인한 명령과 결과를 요약하고, 병합하거나 삭제하지 마세요.

이 프롬프트는 자동 트리거를 보장하지 않습니다. 스킬 이름이나 출력 형식도 하네스마다 달라질 수 있습니다. 확인해야 할 것은 이름이 아니라 설계→계획→실패 테스트→최소 구현→검토→전체 검증 순서와 실제 산출물입니다.

 

단계별 확인 명령

 

아래 PowerShell 명령은 미검증 예제이며, 프로젝트의 테스트 명령은 언어와 테스트 러너에 맞게 바꿔야 합니다.

# 현재 브랜치와 변경 파일 확인
git status --short --branch

# 구현 전후 변경 규모 확인
git diff --stat

# 실제 테스트 명령으로 교체
npm test

 

RED 단계에서는 실패했다는 사실만 보지 말고 요구사항 때문에 실패했는지 읽습니다. 모듈 경로 오류나 의존성 설치 실패는 기능의 RED 증거가 아닙니다. GREEN 단계에서는 같은 테스트와 전체 테스트를 다시 실행합니다.

실행 기록은 다음처럼 남기면 두 하네스의 결과를 과장 없이 비교할 수 있습니다.

 

OS/셸:
하네스와 버전:
Superpowers 버전 또는 태그:
샘플 프로젝트와 테스트 러너:
실행 날짜:
설계 문서 경로:
RED 명령과 관찰 결과:
GREEN 명령과 관찰 결과:
리뷰 지적과 수정 내용:
최종 테스트 결과:
git diff --stat:

 

삭제와 되돌리기는 어떻게 처리할까

설치 제거 UI와 명령은 하네스 버전에 따라 바뀔 수 있습니다. 이 글은 실행으로 확인하지 않은 제거 명령을 추측해 제시하지 않습니다. 제거가 필요하면 해당 하네스의 플러그인 관리 화면과 현재 Superpowers README에서 제거 기능을 확인하고, 먼저 설치 대상과 범위를 기록합니다.

실습 변경을 되돌릴 때도 곧바로 파일이나 worktree를 삭제하지 않습니다.

1. git status --short --branch로 현재 브랜치와 변경 파일을 확인합니다.
2. git diff와 테스트 결과를 보관할지 판단합니다.
3. 필요한 변경은 커밋 또는 패치 등 팀이 쓰는 복구 가능한 방식으로 보존합니다.
4. 병합, 브랜치 삭제와 worktree 정리는 정확한 대상 경로와 사용자 승인을 확인한 뒤 진행합니다.

첫 실습을 독립 저장소에서 해야 하는 이유도 여기에 있습니다. 폐기해도 업무 변경과 섞이지 않고, 잘못된 자동 수정의 범위를 작게 유지할 수 있습니다.

 

Superpowers가 과한 경우와 주의점

Superpowers의 절차가 모든 작업에 이득인 것은 아닙니다.

• 한 줄짜리 문서나 설정 수정은 브레인스토밍, 계획과 worktree 비용이 더 클 수 있습니다.
• 테스트가 없는 레거시 프로젝트에서는 TDD 전에 기존 동작을 보호할 안전망부터 정해야 합니다.
• 서브에이전트 검토는 시간과 토큰을 더 쓰며, 병렬 작업은 같은 파일에서 충돌할 수 있습니다.
• 자동 트리거는 모델과 하네스에 따라 달라질 수 있습니다. 계획 파일과 테스트 출력으로 준수 여부를 확인해야 합니다.
• 외부 플러그인의 지침과 hooks는 권한 있는 도구 사용에 영향을 줄 수 있습니다. 설치 전 내용을 읽고 최소 권한으로 시험해야 합니다.

README가 제시하는 TDD와 검증 철학은 프로젝트의 설계 원칙입니다. 별 수나 문서만으로 결함 감소, 개발 속도 향상 또는 토큰 절약을 보증할 수는 없습니다.

 

Superpowers와 GitHub Spec Kit 중 무엇을 선택할까

Superpowers와 Spec Kit는 서로 대체되는 단일 도구라기보다 프로세스의 강조점이 다릅니다.

필요	적합한 후보	선택 이유
브레인스토밍부터 TDD·디버깅·검토까지 개발 규율 운영	Superpowers	조합된 스킬이 전체 개발 흐름을 다룹니다.
명세와 계획 산출물을 중심으로 Spec-Driven Development 수행	GitHub Spec Kit	Specify → Plan → Tasks → Implement 흐름이 명확합니다.
GitHub Copilot에 특정 업무용 스킬 하나 추가	awesome-copilot	커뮤니티 카탈로그에서 목적별 스킬을 찾을 수 있습니다.
Agent Skills의 공개 예제 구조 학습	anthropics/skills	Anthropic이 공개한 예제를 직접 분석할 수 있습니다.

GitHub Spec Kit는 명세를 구조화하고 작업으로 변환하는 데 무게를 둡니다. Superpowers는 설계 이후 TDD, 디버깅, 리뷰와 완료 증거까지 넓게 다룹니다. 요구사항 문서가 핵심이면 Spec Kit부터, 코딩 과정 전체에 규율을 적용하려면 Superpowers부터 검토할 수 있습니다.

 

마무리

Superpowers의 핵심은 더 강한 모델이 아니라 에이전트가 따라야 할 개발 절차와 확인 가능한 증거입니다. 브레인스토밍, 계획, RED→GREEN→REFACTOR, 두 단계 검토와 최종 테스트가 실제 산출물로 남아야 의미가 있습니다.

처음부터 업무 저장소에 설치하지 말고 독립 샘플 저장소에서 작은 기능 하나를 끝까지 진행해 보세요. 자동 트리거 이름보다 질문, 계획, 테스트 출력과 diff가 올바른 순서로 남았는지를 확인하면 됩니다.

 

참고 자료

• Superpowers README — obra/superpowers maintainers, 개별 발행일 없음, 2026-09-01 접근
• Superpowers v6.3.0 Release — obra/superpowers maintainers, 2026-08-12 게시
• GitHub REST API: obra/superpowers — GitHub, 2026-09-01 조회
• Superpowers Plugin — Anthropic, 개별 발행일 없음, 2026-09-01 접근
• GitHub Spec Kit — GitHub, 개별 발행일 없음, 2026-09-01 접근
• Awesome GitHub Copilot — GitHub, 개별 발행일 없음, 2026-09-01 접근
• Anthropic Agent Skills examples — Anthropic, 개별 발행일 없음, 2026-09-01 접근