설치형 하네스 패키지 활용. (Superpowers)

masonfe-hyunsu

🧵 1. 개요.

에이전트한테 일을 맡기면 프롬프트만 손보지 않고, 볼 파일이나 짜는 순서, 테스트까지 환경에 묶어 두고, 그 일을 하네스 엔지니어링이라고 부른다. 최근엔 그걸 직접 만들기보다 설치해서 쓰게 패키지로 묶어 나온 하네스 패키지가 있다.
예를 들면 Superpowers, gstack, BMAD-METHOD, GSD, Spec Kit, OpenSpec이 자주 보이고, 그중 Superpowers는 채팅이 시작될 때 작업 규칙을 먼저 넣어서, 파일부터 고치지 않고 뭘 만들지 묻고 계획한 뒤에 코드를 짜게 한다.
이 포스팅에서는 비슷한 패키지들의 스타 수치를 먼저 놓고, Superpowers가 그 규칙을 어떻게 넣는지 속을 연다.

요약하면, Superpowers는 에이전트가 코드부터 짜지 못하게, 스킬을 먼저 읽게 만드는 하네스 패키지다.

📊 2. 인지도 있는 패키지.

GitHub 스타 수는 품질이 아니다. 다만 지금 이름이 얼마나 알려져 있는지는 스타가 제일 빨리 잡힌다.

숫자는 2026년 8월 17일 GitHub API 기준이다.

Superpowers — 273,047. Jesse Vincent가 Prime Radiant(만든 회사)에서 만든다. 마크다운 스킬에 더해, 세션이 켜질 때 스킬을 넣어서 "스킬을 먼저 써라"를 건너뛰지 못하게 한다.
Spec Kit — 129,693. GitHub. 스펙을 먼저 쓰고, 원칙 문서부터 구현까지 단계를 고정한다.
gstack — 128,344. Garry Tan의 Claude Code 세팅. CEO, 디자이너, QA처럼 역할 명령을 그대로 쓰는 쪽에 가깝다.
OpenSpec — 65,167. 변경 단위로 스펙을 쪼개는 가벼운 SDD(Spec-Driven Development, 스펙을 먼저 고정하고 구현하는 방식). 이미 있는 코드 위에 변경분만 스펙으로 남기는 쪽에 맞춰져 있다.
GSD — 64,686. 스펙과 작업 맥락을 나눠 실행하는 쪽에 가깝다. 원 저장소는 아카이브됐고, 이후 open-gsd/gsd-core(8,353)로 옮겨졌다.
BMAD-METHOD — 51,982. 분석, 기획, 구현을 에이전트 역할로 나누는 애자일 라이프사이클에 가깝다.

숫자만 보면 Superpowers가 한 칸 위에 있고, Spec Kit랑 gstack이 그다음이다. 여섯 개를 하나하나 비교하는 글은 아니고, 아래부터는 Superpowers만 본다.

⚙️ 3. Superpowers가 도는 방식.

설치.

도구마다 설치 명령은 다르다. 대표적으로 Claude Code와 Cursor에 넣는 방법만 정리해 본다.

Claude Code는 공식 플러그인 마켓에서 /plugin install superpowers@claude-plugins-official 로 설치한다.

Cursor는 에이전트 채팅에서 /add-plugin superpowers 를 치거나, 플러그인 마켓에서 superpowers를 찾는다.

둘 다 쓰면 각 환경에 한 번씩 넣는다.

다른 도구는 obra/superpowers README에 명령이 따로 있다.

세션이 켜질 때.

설치가 끝나면 다음 세션부터 규칙이 붙는다. Superpowers의 핵심은 세션이 시작될 때 using-superpowers를 통째로 넣는 일이다.

세션을 열면 SessionStart 훅이 hooks/session-start를 돌린다. 그 스크립트가 skills/using-superpowers/SKILL.md를 읽어서, "이건 중요하다"는 표시와 함께 에이전트가 맨 처음에 읽는 규칙으로 넣는다. 도구마다 넣는 칸 이름만 조금 다를 뿐, 내용은 같다.

그래서 첫 메시지 전에 이미 규칙이 들어가 있다. "로그인 버튼 색만 바꿔줘"를 받아도, 바로 CSS를 고치지 않고 스킬부터 고른다.

그 스킬이 말하는 규칙은 짧다.

스킬이 맞을 가능성이 1%라도 있으면, 답하기 전에 스킬을 호출하고, 사용자에게 묻기 전에도 스킬을 먼저 연다.
프로세스 스킬이 구현 스킬보다 앞이다. "이거 만들어"면 brainstorming이 먼저고, "버그 고쳐"면 원인을 찾기 전에 고치지 말라는 systematic-debugging이 먼저다.
사용자 문서(CLAUDE.md, AGENTS.md)가 스킬보다 우선한다. 스킬이 기본 동작을 덮고, 사람이 명시한 지시가 그걸 또 덮는다.

스킬이 맞으면 선택이 아니다. 써야 한다.

Jesse의 README도 같다. 에이전트가 코딩을 시작하기 전에 한 발 물러서서, 뭘 만들려는지를 먼저 물어보게 만든다.

서브에이전트로 일을 나눠 받은 쪽은 이 시작 규칙을 무시하라고 적혀 있다. 한 태스크만 실행하면 되고, 세션 전체 규칙을 다시 읽으면 흐름이 끊긴다.

🧩 4. 구성.

저장소를 열어 보면 역할이 셋으로 나뉜다. 세션이 켜질 때 도는 훅, 에이전트가 읽는 skills/ 파일, 도구마다 다른 플러그인 껍데기다.

세션 훅.

hooks/session-start는 세션이 시작되거나, 대화를 비우거나, 긴 대화를 줄일 때 돈다. 하는 일은 using-superpowers를 다시 넣는 것이다.

훅이 안 돌면 스킬 폴더는 있어도 에이전트는 그걸 안 본다. 설치가 됐는지보다, 세션 시작에 규칙이 들어갔는지가 먼저다.

스킬 파일.

각 스킬은 skills/{이름}/SKILL.md 하나다. 맨 위에 "언제 쓰나"가 있고, 아래에 "어떻게 하나"가 있다. 에이전트는 이 설명을 보고 스킬을 고르고, 고르면 본문을 그대로 따른다.

폴더는 14개고, 하는 일로 묶으면 아래다.

시작: using-superpowers. 다른 스킬을 언제 여는지 정한다.
설계: brainstorming. 코드 전에 의도를 묻고, 사람 승인을 받는다.
계획: writing-plans. 2~5분짜리 태스크로 쪼개고, 파일 경로와 테스트까지 적는다.
실행: subagent-driven-development 또는 executing-plans. 계획대로 돌린다. 병렬로 나눠야 하면 dispatching-parallel-agents다.
품질: test-driven-development, systematic-debugging, verification-before-completion. 테스트 먼저, 원인 먼저, 끝났다고 말하기 전에 확인한다.
작업 공간: using-git-worktrees, finishing-a-development-branch. 지금 브랜치를 안 건드리고, 끝나면 머지, PR, 유지를 고른다.
리뷰: requesting-code-review, receiving-code-review.
확장: writing-skills. 새 스킬을 이 형식에 맞춰 만든다.

플러그인 메타는 .claude-plugin/plugin.json이고, 이 포스팅을 쓸 때 버전은 6.3.0이다. 저자는 Jesse Vincent고, 라이선스는 MIT다.

플러그인 껍데기.

스킬 본문은 공유하고, .claude-plugin, .cursor-plugin, .codex-plugin, .opencode처럼 도구별 폴더만 갈라 둔다. 같은 규칙을 Claude Code랑 Cursor에 각각 얹는 형태고, 설치는 앞에서 적은 명령대로 환경마다 한 번씩 한다.

그래서 구성은 세션 훅이 스킬을 넣고, 스킬이 본문이고, plugin.json은 설치 메타인 세 층이다.

🗺️ 5. 기본 워크플로.

README에 적힌 기본 흐름은 브레인스토밍, 계획, TDD, 리뷰로 이어진다.

그림의 네 칸이 전체 줄이다. 아래는 그 줄을 장면으로 풀어 본 것이다.

브레인스토밍.

코드보다 brainstorming이 먼저 켜진다. 요청을 Spike(탐침), Bounded(작은 변경), Architectural(구조 변경) 셋 중 하나로 분류하고, 그 분류를 먼저 말한다.

Spike는 "이 API 쓸 수 있어?"처럼 가능 여부만 싸게 확인한다. 남는 건 답이고, 코드는 버려도 된다.
Bounded는 "로그인 버튼 색만 바꿔줘"처럼 이미 있는 흐름을 조금 고친다. 채팅에 짧은 설계만 보여주고 승인을 기다린다. 스펙 파일은 안 만든다.
Architectural은 결제처럼 구조가 바뀌는 일이다. 스펙을 docs/superpowers/specs/에 쓰고, writing-plans로 넘어간다.

승인 게이트는 안 줄어들고, 간단한 일은 남는 파일만 짧아진다. 중간에 일이 커지면 분류를 한 단계 올리고, 반대로 줄이지는 않는다.

계획과 작업 공간.

설계가 끝나면 using-git-worktrees로 지금 브랜치를 안 건드리는 작업용 복사본을 만든다. 메인에서 바로 짜지 말라는 뜻이다.

계획은 docs/superpowers/plans/에 두고, 태스크를 2~5분 단위로 쪼갠다. 각 칸에는 손댈 파일 경로, 실패하는 테스트, 최소 구현, 커밋까지 적힌다. "나중에 채운다" 같은 빈칸은 계획 실패로 본다.

실행 두 갈래.

실행은 두 갈래다.

권장하는 쪽은 태스크마다 새 서브에이전트를 띄우는 subagent-driven-development다. 한 에이전트가 한 칸만 보고, 끝나면 스펙을 지켰는지와 코드 품질을 순서대로 리뷰한다. 긴 세션에서 앞 맥락이 섞이는 걸 줄이려는 구성이다.

같은 세션에서 묶음 단위로 멈추고 확인하는 쪽은 executing-plans다. 서브에이전트가 없는 하네스용이고, 막히면 추측해서 밀지 말고 사람에게 물어보라고 적혀 있다.

TDD와 리뷰.

구현 중에는 TDD가 철칙이다. 실패하는 테스트를 먼저 보고, 그다음에 최소 코드를 넣는다. 테스트를 안 보고 짠 코드는 지우라고 적혀 있다. 버그 수정도 같다. 재현 테스트 없이 고치지 않는다.

태스크 사이에는 requesting-code-review로 계획 대비를 보고, 치명적인 이슈면 다음으로 안 넘어간다.

브랜치를 닫을 때는 테스트를 다시 돌리고, 머지, PR, 유지 중 하나를 고른다. 폐기는 사람이 "discard"라고 명시할 때만이다.

🎯 6. 잘 쓰려면.

브레인스토밍을 건너뛰고 "그냥 짜줘"로 구현부터 시키면, Superpowers가 아니라 일반 에이전트다.
프로세스 스킬이 먼저다. 구현부터 들어가는 스킬보다 brainstorming, debugging이 앞이다.
CLAUDE.md가 이긴다. 이 레포에서 TDD를 빼려면 사람이 명시해야 한다. 스킬이 사람 지시를 덮지 않는다.
훅이 안 돌면 using-superpowers가 안 들어간다. 설치만 되고 세션 훅이 빠진 하네스는 스킬이 장식이다.
작은 일은 Bounded로 짧게 끝내는 게 맞다. 모든 요청을 Architectural 스펙 파일로 키울 필요는 없다.

⚖️ 7. 한계.

절차가 크다. 작은 수정에도 설계 승인을 받으라고 해서, 답답할 수 있다.
TDD를 글자 그대로 지키면, UI 스케치나 설정 파일에서 마찰이 난다. 예외는 사람과 합의하라고 적혀 있다.
브레인스토밍 때 선택하는 미리보기 화면이 회사 로고를 불러오면서, 대략적인 사용량 텔레메트리가 나간다. SUPERPOWERS_DISABLE_TELEMETRY로 끈다.
스타 273,047은 인지도지, 우리 레포에 맞다는 뜻은 아니다. 역할 명령이 필요하면 gstack, 변경 단위 스펙이면 OpenSpec 쪽이 더 가깝다.