Superpowers — 코딩 에이전트에 설계·계획·구현·검증 습관을 주입하는 skill-driven 개발 프레임워크

분석 범위: README.md, 플랫폼별 설치 가이드, hooks/, .opencode/plugins/, skills/, tests/, 릴리스/패키지 메타데이터
분석 시점 기준 확인된 패키지 버전: 5.0.7
Asset note: 저장소를 확인했을 때 공식 PNG/GIF/UI 스크린샷 자산은 거의 드러나지 않았다. 아래 figures/ 이미지는 README·문서·코드 구조를 바탕으로 재구성한 분석용 도해다.

Title

Superpowers
코딩 에이전트가 즉흥적으로 코드를 생성하기보다, 브레인스토밍 → 계획 → 구현 → 테스트 → 리뷰 → 검증의 강한 개발 루프를 따르도록 만드는 skill-driven workflow framework이자, 여러 에이전트 런타임에 같은 규율을 이식하는 bootstrap/adaptor 레이어다.

---

Quick Links

• Repository: obra/superpowers
• Main README: README.md
• Codex guide: docs/README.codex.md
• OpenCode guide: docs/README.opencode.md
• Release notes: RELEASE-NOTES.md
• Project page / release signup: Prime Radiant — Superpowers
• Background post: Skills for Claude!
• Related paper: 공식 논문 링크는 확인되지 않음
• Demo: 별도 제품 데모보다는 각 플랫폼 설치 문서와 브레인스토밍 companion 설계가 실제 사용 흐름을 설명한다.

---

Key Features

1) 멀티플랫폼 bootstrap: 한 번 만든 skill discipline을 여러 에이전트에 이식

이 저장소의 가장 실용적인 장점은 같은 skill 라이브러리를 Claude Code / Cursor / Codex / OpenCode / GitHub Copilot CLI / Gemini CLI에 각각 다른 bootstrap 방식으로 연결한다는 점이다.
핵심은 기능을 런타임마다 다시 구현하는 것이 아니라, 공통 skill 집합은 유지하고 host별 adapter만 바꾸는 구조를 취한다는 데 있다.

 

 

Figure 1. 플랫폼별 bootstrap 경로. Claude/Cursor/Copilot은 SessionStart hook, OpenCode는 plugin transform + config mutation, Codex는 native skill discovery + symlink/junction, Gemini는 extension entry 기반으로 같은 skill 집합을 노출한다.

2) 강제된 기본 워크플로우: design-first, review-first, evidence-first

README가 제시하는 기본 흐름은 단순한 “팁 모음”이 아니라, 에이전트가 습관적으로 따르길 기대하는 운영 절차다.
특히 brainstorming, writing-plans, test-driven-development, requesting-code-review, verification-before-completion의 연결은 “코드 생성”보다 프로세스 통제를 우선시한다.

 

 

Figure 2. README의 기본 워크플로우를 재구성한 도해. Superpowers의 핵심은 프롬프트 강화가 아니라, 에이전트를 설계→계획→구현→리뷰→검증 루프로 반복 진입시키는 것이다.

3) Visual Brainstorm Companion: 텍스트만으로 부족한 설계를 브라우저로 끌어올림

brainstorming skill은 단순 대화형 질의응답이 아니라, 필요 시 HTML 화면을 띄우고 사용자 클릭을 다음 턴의 입력으로 되먹임하는 가벼운 브라우저 companion 패턴을 갖는다.
이건 UI mockup, 구조 비교, 옵션 선택, 간단한 다이어그램 시각화에 특히 유용하다.

 

 

Figure 3. 브레인스토밍 companion의 동작 흐름. 에이전트가 HTML을 쓰면 로컬 서버가 브라우저에 렌더링하고, 사용자의 클릭은 이벤트 파일에 기록되어 다음 대화 턴에 다시 읽힌다.

4) Skill library를 “행동 계약(behavior contract)”으로 사용

이 저장소의 본체는 깊은 JS 런타임이 아니라 skills/*/SKILL.md다.
대표 skill은 다음과 같다.

• brainstorming: Socratic design refinement
• writing-plans: 아주 작은 실행 단위 계획 수립
• using-git-worktrees: 격리된 브랜치/작업공간 준비
• subagent-driven-development: task당 fresh subagent + 2단계 리뷰
• test-driven-development: failing test first
• systematic-debugging: root cause 우선
• verification-before-completion: 검증 없는 완료 주장 금지
• requesting-code-review, receiving-code-review
• writing-skills: 새로운 skill 자체를 만드는 meta-skill

여기서 중요한 점은 skill이 “지식”이 아니라 “행동 규약”으로 쓰인다는 것이다.
즉, Superpowers는 “무엇을 아는가”보다 “어떤 순서로, 어떤 기준으로 행동하는가”를 강제한다.

5) 서브에이전트와 리뷰를 1급 개념으로 취급

subagent-driven-development는 구현을 하위 에이전트에 위임하는 데서 끝나지 않고, 그 결과물을 다시 spec compliance review → code quality review 순서로 점검하는 구조를 강조한다.
이는 “병렬화”보다 컨텍스트 격리와 검토 편향 감소에 더 큰 가치가 있다.

6) 테스트 하네스와 문서가 함께 제공됨

이 저장소는 skill을 글로만 설명하지 않고, 다음 같은 경로로 회귀 검증까지 시도한다.

• tests/brainstorm-server/: 브레인스토밍 companion 서버/프로토콜 검증
• tests/opencode/: OpenCode plugin 로딩, tool mapping, skill discovery 점검
• tests/skill-triggering/: 프롬프트에 따라 올바른 skill이 발동하는지 확인
• docs/testing.md: 실제 headless 세션 기반 통합 테스트 절차 문서화

즉, “에이전트 행동 설계”를 테스트 가능한 소프트웨어 자산처럼 다루려는 시도가 있다는 점이 흥미롭다.

---

Tech Stack

핵심 스택 요약

영역	기술	설명	버전/비고
패키지 엔트리	package.json	루트 패키지는 매우 얇고, OpenCode plugin 파일을 main으로 지정	superpowers@5.0.7
주 언어	Shell / JavaScript / HTML / Python / TypeScript / Batchfile	GitHub 언어 통계 기준	Shell 비중이 가장 큼
Claude/Cursor/Copilot 부트스트랩	Bash + JSON hook payload	hooks/session-start, hooks.json, hooks-cursor.json	세션 시작 시 context 주입
OpenCode 어댑터	JavaScript (ESM)	.opencode/plugins/superpowers.js가 config hook + message transform 수행	루트 type: module
브레인스토밍 companion	Node.js + HTML	server.cjs와 HTML 템플릿 기반	런타임 의존성 최소화
테스트	Bash + Node.js	plugin loading, protocol, prompt-triggering, integration 시나리오	문서와 테스트가 함께 존재
테스트 전용 의존성	ws	브레인스토밍 server 테스트용 WebSocket 클라이언트	^8.19.0

구현자가 꼭 알아야 할 점

• 이 repo는 npm 라이브러리라기보다 에이전트 운영 체제에 가까운 프롬프트/skill 레이어다.
• 코드 재사용보다 중요한 것은:
  1. bootstrap 경로
  2. skill discovery 규약
  3. review / verification gate
  4. regression test 패턴
     을 옮기는 것이다.
• OpenCode 쪽은 plugin이 동적으로 skills.paths를 등록하고 첫 user message를 변형한다는 점이 특히 독특하다.
• Codex 쪽은 별도 런타임 코드보다 파일 배치와 symlink/junction 규약이 핵심이다.

---

Architecture

 

Figure 4. 저장소 구조를 계층형으로 재구성한 아키텍처 다이어그램. 상단은 host-specific adapter, 중앙은 bootstrap과 skill library, 하단은 실제 개발 workflow와 시각 companion, 우측 하단은 테스트/품질 게이트다.

1) 큰 구조

이 프로젝트는 네 개의 관점으로 이해하면 쉽다.

A. Platform adapter layer

각 실행 환경에 맞춘 얇은 접속면이다.

• .claude-plugin/
• .cursor-plugin/
• .codex/
• .opencode/plugins/
• gemini-extension.json
• hooks/

B. Bootstrap layer

에이전트가 세션 시작 시 using-superpowers를 이미 알고 있는 상태로 들어오게 만드는 레이어다.
여기서 핵심 철학은 “사용자가 skill 이름을 직접 기억하지 않아도, 에이전트가 먼저 skill을 찾게 만들자”이다.

C. Skill layer

실제 시스템의 핵심 로직은 skills/*/SKILL.md에 있다.
필요에 따라 하위 폴더에는 다음이 붙는다.

• references
• reviewer/implementer prompt
• helper script
• HTML template
• 테스트용 자료

즉, 코드보다 규율이 구조화된 문서 집합이 중심이다.

D. Verification layer

tests/와 docs/testing.md는 “이 방법론이 실제로 발동하는가”를 검증하기 위한 층이다.
이 부분이 존재하기 때문에 Superpowers는 단순한 아이디어 공유보다 한 단계 더 진지한 프레임워크처럼 보인다.

2) 플랫폼별 세부 동작

Claude / Cursor / Copilot CLI

hooks/session-start가 skills/using-superpowers/SKILL.md를 읽어 JSON으로 주입한다.
흥미로운 점은 같은 내용을 넣더라도 플랫폼별로 기대하는 JSON 키가 달라서, 해당 스크립트가 출력 형식을 분기한다는 점이다.

OpenCode

.opencode/plugins/superpowers.js는 두 가지를 동시에 수행한다.

1. config hook으로 skills.paths에 Superpowers skill 경로를 추가
2. 첫 user message 앞에 bootstrap 텍스트를 삽입

즉, symlink 없이도 OpenCode가 skill을 발견하고, 첫 턴부터 Superpowers 행동 규약을 따르게 만든다.

Codex

Codex는 native skill discovery를 사용하므로, ~/.agents/skills/에 superpowers를 symlink/junction으로 노출시키는 방식이 핵심이다.
이 구조는 런타임 코드가 적은 대신, 배치 규약이 정확해야 한다는 특징이 있다.

3) 코드베이스를 읽는 추천 순서

README.md
→ skills/using-superpowers/SKILL.md
→ skills/brainstorming/SKILL.md
→ skills/writing-plans/SKILL.md
→ skills/subagent-driven-development/SKILL.md
→ skills/test-driven-development/SKILL.md
→ hooks/session-start
→ .opencode/plugins/superpowers.js
→ docs/README.codex.md / docs/README.opencode.md
→ tests/

4) 구현 관점의 핵심 해석

내 해석으로는 이 저장소의 진짜 제품은 “code generation features”가 아니라 “workflow discipline”이다.
즉, 여기서 배워야 할 것은 API surface가 아니라 다음 세 가지다.

• Skill을 어떻게 discovery하게 만들 것인가
• 에이전트가 언제 어떤 절차를 강제로 밟게 할 것인가
• 그 행동을 어떻게 회귀 테스트할 것인가

---

Usage & Setup

실제 설치는 host마다 다르다.
즉, “한 개 커맨드로 어디서나 동일하게 설치”되는 프로젝트가 아니라, 플랫폼별 철학과 기능 제약에 맞는 설치 경로가 분기된다.

 

 

Figure 5. README와 플랫폼별 설치 가이드를 터미널 시점으로 요약한 이미지. Claude/Cursor/Copilot은 marketplace 설치, Codex는 symlink/junction, OpenCode는 git plugin, Gemini는 extension install 경로를 쓴다.

1) 가장 짧은 설치 커맨드 요약

Claude Code 공식 마켓플레이스

/plugin install superpowers@claude-plugins-official

Claude Code 커스텀 마켓플레이스

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

Cursor

/add-plugin superpowers

GitHub Copilot CLI

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

Gemini CLI

gemini extensions install https://github.com/obra/superpowers
gemini extensions update superpowers

2) Codex 설치 핵심

빠른 설치

Fetch and follow instructions from
https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md

수동 설치

git clone https://github.com/obra/superpowers.git ~/.codex/superpowers
mkdir -p ~/.agents/skills
ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers

선택 사항: multi-agent

[features]
multi_agent = true

3) OpenCode 설치 핵심

opencode.json의 plugin 배열에 다음을 추가한다.

{
  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]
}

재시작하면 plugin이 자동 설치되고, Superpowers skill들이 자동 등록된다.

4) 설치 확인 방법

새 세션에서 다음 같은 요청을 던져 skill이 자동 발동하는지 본다.

help me plan this feature
let's debug this issue
tell me about your superpowers

기대 동작:

• 곧바로 코드를 쓰지 않음
• 관련 skill을 먼저 찾거나 로드함
• brainstorming / planning / debugging / TDD 흐름으로 유도함

5) 로컬에서 이 repo를 참고 구현하려는 사람에게

내가 추천하는 최소 재현 순서는 다음과 같다.

1. 세션 시작 bootstrap 하나 만들기
2. skills/ 같은 디렉터리 규약 정하기
3. using-superpowers, brainstorming, writing-plans, test-driven-development, verification-before-completion만 먼저 구현
4. prompt-triggering 테스트 몇 개 추가
5. 그 뒤에 subagent / companion UI를 붙이기

이 순서를 추천하는 이유는, Superpowers의 진짜 가치가 host integration + workflow discipline에서 나오기 때문이다.
처음부터 모든 skill을 옮기기보다, 먼저 bootstrap과 핵심 게이트를 옮기는 편이 훨씬 빠르다.

---

Personal Insights

1) 의료 AI 관점

의료 AI에서 이 프로젝트가 주는 가장 큰 영감은 “자유 생성보다 절차를 우선시한다”는 점이다.
예를 들어 다음처럼 바로 응용할 수 있다.

• brainstorming → 케이스 해석 전에 누락된 병력/검사/약물 정보를 먼저 확인하는 triage 단계
• writing-plans → 진단 보조나 리포트 생성 전에 필요한 검토 절차를 단계별로 분해
• verification-before-completion → 근거 없는 완료/확신 표현 금지
• requesting-code-review → clinician-in-the-loop 검토 인터페이스로 변환

의료 도메인에 바로 쓰려면 추가가 필요하다.

• PHI/PII 보호
• structured audit trail
• guideline validator
• 승인권자/책임자 흐름
• 위험도 기반 escalation

즉, Superpowers는 의료 안전 기능을 직접 주지는 않지만, 의료용 agent workflow를 설계하는 메타 프레임으로는 매우 강하다.

2) Bioinformatics 관점

생물정보학 파이프라인은 종종 “도구는 많은데 절차 통제는 약한” 문제가 있다.
Superpowers의 패턴은 여기에 잘 맞는다.

• using-git-worktrees → 파라미터 실험과 branch별 결과를 분리
• writing-plans → QC → trimming → alignment → variant calling → annotation 같은 단계를 작게 쪼갬
• test-driven-development → fixture/synthetic sample 기반 회귀 검증
• verification-before-completion → 산출물 존재 여부만이 아니라 provenance/log/threshold를 함께 확인
• systematic-debugging → 데이터 품질 문제를 ad-hoc fix가 아니라 root-cause investigation으로 전환

Bioinformatics에서 특히 좋은 점은, 이 repo가 “새 툴을 하나 더 붙이는 것”보다 분석 절차를 재실행 가능하고 검증 가능하게 만드는 방향을 보여준다는 것이다.

3) Autonomous Agent 관점

Autonomous agent 설계 측면에서 가장 중요한 아이디어는 세 가지다.

1. Meta-skill bootstrap
   에이전트에게 “먼저 skill부터 찾으라”는 운영 습관을 심는다.
2. Isolated subagents
   task마다 fresh context를 주어 context pollution을 줄인다.
3. Review as a default step
   planner / implementer / validator 구조를 자연스럽게 만든다.

나는 이 저장소를 보며 다음 공식을 떠올린다.

• Skill = portable behavior contract
• Hook / plugin = host-specific bootstrap shim
• Tests = behavior regression harness

즉, 앞으로 agent engineering에서 중요한 것은 도구 개수보다도 행동 규약을 어떻게 이식하고, 어떻게 회귀 테스트할 것인가일 가능성이 크다.
Superpowers는 그 방향을 매우 선명하게 보여준다.

4) 내가 이 repo를 참고해 후속 시스템을 만든다면

가장 먼저 추가할 것은 다음이다.

1. 구조화된 실행 로그
   • reviewer 결과, evidence, approval state를 JSON schema로 저장
2. 도메인 validator
   • 의료 AI용 guideline validator
   • Bioinformatics용 QC / provenance validator
3. 정책/보안 레이어
   • secret redaction
   • PHI handling
   • capability policy
4. 상태 기반 orchestration
   • 단순 텍스트 지침을 넘어, plan / review / verify 단계를 explicit state machine으로 끌어올림

---

Closing Assessment

Superpowers는 “코딩 에이전트용 프롬프트 모음”으로 보기엔 과소평가고, “범용 에이전트 오케스트레이터”로 보기엔 지나치게 가볍다.
가장 정확한 표현은 아마 다음에 가깝다.

여러 agent host에 이식 가능한, skill-driven 개발 운영체제의 초경량 구현

 

이 저장소를 실제 프로젝트에 참고하려면, 코드를 통째로 가져가기보다 아래 세 가지만 먼저 흡수하는 것이 좋다.

• bootstrap 메커니즘
• workflow-gating skill 설계
• behavior regression test 전략

이 세 가지가 바로 Superpowers의 핵심 가치다.