AI 에이전트 스킬 14개가 아니라 훅 1개, superpowers가 증명한 이유 (2026)

AI 코딩 규칙 문서를 아무리 써둬도 자주 무시됩니다. obra superpowers는 스킬 14개가 아니라, 세션마다 규칙을 강제로 주입하는 Claude Code 훅 1개로 그 문제를 풀었습니다.

결론부터 말하면, 문제는 AI 모델의 성실함이 아니라 규칙을 전달하는 방식에 있었습니다. "CLAUDE.md에 분명히 적어뒀는데 왜 자꾸 무시하지?" 팀에 AI 에이전트를 도입해본 분이라면 한 번쯤 던져봤을 질문이에요. 저도 마찬가지였습니다. 오늘은 26만 스타를 받은 오픈소스 obra/superpowers가 이 질문에 어떻게 답했는지, 우리 팀 AI 도입에 어떻게 가져올 수 있는지 짚어보겠습니다.

obra/superpowers, 정체부터 확인해볼게요

GitHub API 기준(2026-08-12 조회) obra/superpowers는 스타 270,921개, 포크 24,206개를 받은 MIT 라이선스 오픈소스입니다. 저장소 생성일은 2025-10-09, 최신 릴리스는 v6.2.0(2026-07-24)입니다. 만든 사람은 Jesse Vincent이고, plugin.json의 author 필드에 이름이 명시돼 있으며, README에는 Prime Radiant사가 함께 개발한다고 적혀 있어요.

obra/superpowers, 정체부터 확인해볼게요

이미지 출처: github.com

정체를 한 문장으로 요약하면 이렇습니다. "코딩 에이전트를 위한 완결형 소프트웨어 개발 방법론이며, 조합 가능한 스킬 묶음과 에이전트가 그것들을 반드시 쓰게 만드는 초기 지시로 구성된다." 스킬 묶음은 재료고, 초기 지시는 그 재료를 강제로 쓰게 만드는 장치예요.

스킬은 14개인데, 진짜 주인공은 하나뿐입니다

git tree를 직접 조회하면 SKILL.md 파일이 정확히 14개 나옵니다. 추정이 아니라 실측입니다. 브레인스토밍, 계획 작성, TDD 자동화(테스트 주도 개발), 체계적 디버깅, 코드리뷰 요청과 응대, 병렬 서브에이전트 운영, 격리 워크스페이스 관리, 브랜치 마무리까지 소프트웨어 개발 한 사이클을 덮어요. 도메인 스킬은 0개라는 점도 흥미롭습니다. "뭘 만들지"가 아니라 "어떻게 일할지"만 다루거든요.

여기까지만 보면 마크다운 파일 14개가 특별해 보이지 않습니다. 지침만 저장소에 적어두는 방식은 이미 많은 팀이 시도했고, 대부분 며칠 못 가 흐지부지됐어요. 이 프로젝트가 다른 지점은 스킬 개수가 아니라 그중 딱 1개를 다루는 방식입니다.

훅 1개가 나머지 13개를 움직이는 구조

14개 스킬 중 using-superpowers 하나만 특별 취급을 받습니다. hooks/hooks.json을 열어보면 SessionStart 이벤트에 startup|clear|compact matcher가 걸려 있어요. 세션이 시작될 때, /clear를 칠 때, 컨텍스트가 압축(compact)될 때, 이 세 순간마다 hooks/session-start 스크립트가 using-superpowers/SKILL.md 전문을 세션 컨텍스트에 밀어 넣습니다.

훅(hook): 특정 이벤트(세션 시작, 대화 압축 등)가 벌어질 때 자동으로 실행되는 스크립트예요. AI에게 "이 순간엔 무조건 이걸 봐라"라고 강제로 끼워 넣는 장치라고 보시면 됩니다.

나머지 13개 스킬은 이름과 설명만 미리 걸어두고, 실제로 관련 있을 때만 전문을 불러옵니다. 이 방식을 progressive disclosure라고 부릅니다.

progressive disclosure: 처음엔 스킬 이름과 설명만 살짝 보여주고, 실제로 필요할 때만 전체 내용을 불러오는 방식이에요. 컨텍스트가 한꺼번에 터지지 않게 아껴 쓰는 절약 장치죠.

using-superpowers만 이 방식을 안 쓰고 매번 상주합니다. "1%라도 스킬이 적용될 가능성이 있으면 반드시 호출해야 한다. 선택권이 없다"는 1% 규칙이 들어 있고, 이게 나머지 13개 스킬을 연쇄적으로 발동시키는 방아쇠 역할을 해요.

더 눈에 띄는 부분은 "Red Flags" 표입니다. 모델이 스킬을 건너뛸 때 쓸 법한 변명을 12개 적어두고 하나씩 반박해요.

모델이 떠올릴 법한 변명	미리 준비된 반박
"이건 그냥 단순한 질문인데"	질문도 작업이다, 스킬부터 확인하라
"코드베이스부터 좀 둘러보자"	스킬이 어떻게 둘러볼지 알려준다, 먼저 확인하라
"일단 이거 하나만 먼저 하고"	무엇이든 하기 전에 먼저 확인하라

프롬프트 설계 관점에서 이건 지시가 아니라 이탈 경로 선차단에 가깝습니다. 모델이 규칙을 어길 때 쓰는 자기합리화 문장에 미리 이름을 붙여 무력화하는 거예요.

CLAUDE.md에 규칙을 써놔도 안 지켜지던 이유, 같은 결론이었습니다

여기서부터가 이 프로젝트가 실제로 증명한 부분이라고 생각해요. TDD가 좋다는 얘기가 핵심이 아닙니다. **"규칙 문서만 써두면 모델이 안 지킨다. 훅으로 매 세션 다시 주입해야 지킨다"**는 게 이 프로젝트가 실증한 전부예요.

Reddit r/ClaudeAI에서 Superpowers를 다루지 않은 독립적인 글 두 편이 같은 결론에 도달한 걸 확인했습니다. 하나는 "모델이 CLAUDE.md를 계속 무시하길래 훅으로 옮겼다"는 경험담, 다른 하나는 "AI에게 규칙을 줬더니 동의하고는 조용히 무시했다, 그래서 규칙 쓰기를 그만뒀다"는 글입니다. Superpowers를 몰라도 사용자들이 각자 같은 문제에 부딪혀 같은 해법을 찾은 셈이에요.

왜 이런 일이 생길까요. 문서는 한 번 읽히고 끝입니다. 대화가 길어지면 초기 지시는 뒤로 밀려나고, 컨텍스트가 압축되는 순간 흐려지기 쉬워요. 훅은 다릅니다. 세션이 시작될 때마다, 컨텍스트가 압축된 직후에도 다시 밀어 넣습니다. 긴 작업일수록 규율이 풀리기 쉬운 지점을 정확히 노린 설계입니다.

토큰 비용, 도입 전에 짚고 가야 할 부분입니다

여기까지만 들으면 무조건 좋아 보이지만, 저자 본인이 인정한 약점이 있습니다. 2026-06-15 발표 글에서 Jesse Vincent는 이렇게 썼어요. "토큰이 비싸고 Superpowers가 토큰을 엄청 쓴다는 게 사용자에게 듣는 가장 흔한 한탄이다. Superpowers로 만드는 건 안 쓸 때보다 느리기도 하다." v6.2.0의 업데이트 헤드라인이 새 기능이 아니라 "최대 50% 빠름, 60% 저렴"이었던 이유가 여기 있습니다. 다만 이 수치는 제작자 측 자체 주장이고, 3자가 재현한 독립 벤치마크는 확인되지 않았습니다.

선택적 비활성화가 어렵다는 지적도 있어요. HN 댓글 중엔 "파일에 한 줄 추가하는 데도 전체 의례가 붙는다, 선택적으로 끌 수 있으면 좋겠다"는 불만이 나옵니다. 1% 규칙이 강력한 만큼 과잉 적용되는 셈이죠. 반대로 "AI 이전엔 손도 못 대던 프로젝트 두 건을 해냈다"는 성공담도 있었어요.

이 지점은 QJC 블로그 도입 4관문 중 세 번째, 비용과 ROI 질문과 맞닿아 있습니다. 절감이 아니라 회수 관점으로 봐야 해요. 사전 계획과 엄격한 TDD, 모든 변경에 대한 2단계 리뷰가 곧 토큰 비용입니다. 이 비용이 레거시 코드 리팩터링처럼 사람이 놓치기 쉬운 작업의 안전망 값이라면 계산이 달라질 수 있습니다. 반대로 한 줄 수정이나 탐색적 프로토타이핑 같은 가벼운 작업에는 과한 비용이고요.

신뢰성 문제, 즉 AI가 틀린 결과물을 완료됐다고 우기는 문제는 verification-before-completion 스킬이 담당합니다. 완료를 선언하기 전에 실제로 고쳐졌다는 증거를 확인하는 절차예요. 이 효과를 검증한 3자 벤치마크는 이번 조사에서 확인하지 못했습니다.

그대로 설치할까요, 원리만 가져올까요

Claude Code라면 설치는 명령어 한 줄입니다.

/plugin install superpowers@claude-plugins-official

Claude Code 전용도 아니에요. Codex, Cursor, Gemini CLI, Kimi Code를 포함해 11개 하네스를 지원합니다. 저장소 안에 하네스별 플러그인 디렉토리가 나란히 들어 있고, 훅 스크립트가 하네스마다 다른 JSON 형식으로 출력됩니다. "우리 도구에선 안 되지 않을까"라는 걱정은 대부분의 주요 도구에서 이미 해소된 셈입니다.

다만 통째로 설치하지 않아도 됩니다. 14개 SKILL.md는 전부 마크다운이고 MIT 라이선스라, 읽어보는 것만으로도 얻을 게 있어요. TDD 자동화가 궁금하다면 test-driven-development 스킬 하나만 읽어도 충분합니다. Red Flags 기법은 여러분 프로젝트의 CLAUDE.md나 AGENTS.md에 그대로 옮겨 적을 수 있고요.

팀 AI 도입을 고민하는 단계라면 판단 기준은 이렇습니다. 레거시 리팩터링, 테스트 없는 코드베이스에 안전망을 깔아야 하는 경우, 여러 시간 자율 실행이 필요한 작업에는 잘 맞습니다. 반대로 한 줄 수정, 탐색적 작업, 자체 개발 프로세스가 있는 팀에는 겹치는 규칙이 두 벌이 될 수 있어요. 자체 규칙을 운영 중이라면 방법론의 기준점을 어느 쪽에 둘지 먼저 정하는 게 순서입니다.

마무리

이 글에서 가져가실 한 가지가 있다면 이겁니다. AI 코딩 규칙은 문서에 적어두는 것과 훅으로 강제하는 것이 전혀 다른 결과를 만듭니다. obra/superpowers는 스킬 14개가 아니라 그 원리를 증명한 훅 1개짜리 프로젝트였어요. 우리 팀 상황에 맞는지부터 따져보셔도 충분합니다. 판단에 필요한 기준은 위에 정리해 뒀어요.

자주 묻는 질문 (FAQ)

Q: 토큰을 너무 많이 쓰고 속도가 느리다는데 사실인가요?

저자 본인이 2026-06-15 발표 글에서 직접 인정한 부분입니다. "토큰이 비싸고 안 쓸 때보다 느리다"고 명시했고, v6.2.0에서 최대 50% 속도 개선과 60% 비용 절감을 주장했어요. 다만 이 수치는 제작자 측 자체 주장이고 3자 벤치마크는 확인되지 않았습니다.

Q: 일부 스킬만 선택적으로 켤 수 있나요?

기본적으로는 어렵습니다. 1% 규칙이 관련 가능성이 조금이라도 있으면 스킬을 호출하도록 강제하기 때문에, 파일 한 줄 추가처럼 가벼운 작업에도 전체 의례가 따라붙는다는 불만이 커뮤니티에 있어요. 우회하려면 사용자가 명시적으로 건너뛰라고 지시해야 하는데, SKILL.md 자체가 사용자 지시를 스킬보다 우선한다고 못 박아 뒀습니다.

Q: Claude Code에서만 쓸 수 있나요?

아니요. Codex App, Codex CLI, Cursor, Gemini CLI, Kimi Code, OpenCode 등 총 11개 하네스를 README에서 각각 안내하고 있습니다. Claude Code용 AI 에이전트 스킬 프레임워크로 시작했지만 특정 도구에 묶여 있지 않아요.

AI 에이전트 스킬 14개가 아니라 훅 1개, superpowers가 증명한 이유 (2026)

별 26만 개 받은 AI 습관 설계법, 5분 요약: 비개발자를 위한 쉬운 가이드