Superpowers: 클로드 코드에 소프트웨어 엔지니어링 원칙을 심다

클로드 코드에게 “이 기능 만들어줘”라고 하면 곧바로 코드를 쓰기 시작합니다. 빠르긴 한데, 가끔 불안할 때가 있어요. 테스트는 나중에 추가하려나? 설계는 괜찮은 건가? 파일이 너무 커지는 거 아닌가? 사람이 개발할 때는 자연스럽게 거치는 고민들인데, AI한테는 명시적으로 시키지 않으면 넘어가 버리는 부분이죠.

Superpowers는 이런 고민을 플러그인 하나로 해결하려는 시도입니다. Jesse Vincent가 만든 이 클로드 코드 플러그인은 TDD, 체계적 디버깅, 브레인스토밍 같은 소프트웨어 엔지니어링 방법론을 Claude의 워크플로우에 직접 녹여넣었는데요. 14만 회 이상 설치될 만큼 커뮤니티에서 큰 호응을 얻고 있습니다.

설치하기

클로드 코드 플러그인 시스템을 이용하면 한 줄이면 됩니다.

/plugin install superpowers@claude-plugins-official

설치하고 나면 /help를 입력했을 때 superpowers:로 시작하는 슬래시 커맨드가 보입니다. 이 커맨드들이 Superpowers가 제공하는 워크플로우의 진입점이에요.

브레인스토밍부터 시작하기

코드부터 쓰는 대신 요구사항을 정리하는 것부터 시작하자는 게 Superpowers의 철학입니다. /superpowers:brainstorming을 실행하면 Claude가 소크라테스식 대화를 시작합니다.

/superpowers:brainstorming 사용자 인증 시스템을 만들고 싶어

Claude가 바로 JWT 토큰 구현에 들어가는 대신 질문을 던지기 시작합니다. “세션 기반과 토큰 기반 중 어떤 방식을 선호하세요?”, “소셜 로그인도 지원해야 하나요?”, “비밀번호 재설정 플로우가 필요한가요?” 이런 식으로 요구사항의 빈 곳을 채워나가죠.

Plan 모드와 비슷해 보일 수 있는데 차이가 있습니다. Plan 모드는 코드베이스를 분석해서 구현 계획을 세우는 데 초점이 맞춰져 있어요. 반면 Superpowers의 브레인스토밍은 코드베이스에 들어가기 전 단계, 그러니까 “무엇을 만들 것인가”를 명확히 하는 데 집중합니다. 브레인스토밍으로 요구사항을 확정한 다음 Plan 모드로 넘어가면 더 단단한 설계가 나오겠죠.

비주얼 브레인스토밍

Superpowers 5에서 가장 눈길을 끄는 기능은 비주얼 브레인스토밍입니다. 기존에는 아키텍처 다이어그램이나 UI 목업을 설명하려면 ASCII 아트에 의존해야 했는데, 솔직히 복잡한 구조를 ASCII로 그리면 이해하기 더 어려울 때가 많았습니다.

비주얼 브레인스토밍을 사용하면 Claude가 HTML 파일을 생성해서 로컬 브라우저에서 보여줍니다. 컴포넌트 간의 관계, 데이터 흐름, UI 레이아웃 같은 것들을 인터랙티브한 다이어그램으로 보여주니까 한눈에 파악할 수 있죠.

Claude가 시각적 설명이 도움이 되겠다고 판단하면 “브라우저에서 보여드릴까요?”라고 먼저 제안합니다. 웹페이지 리디자인이나 대규모 리팩토링처럼 구조를 머릿속으로 그리기 어려운 작업에서 특히 유용해요.

TDD 워크플로우

Superpowers의 핵심은 TDD(Test-Driven Development) 워크플로우입니다. 실행 계획을 세우고 나면 red-green-refactor 사이클을 따라서 개발을 진행하는데요.

먼저 Red 단계에서 실패하는 테스트를 작성합니다. 아직 구현이 없으니 당연히 테스트가 실패하겠죠. 여기서 중요한 건 테스트가 반드시 실패해야 한다는 겁니다. 테스트를 먼저 작성했는데 통과해버리면 Superpowers가 멈추고 왜 통과했는지 확인하라고 합니다. 이미 구현이 있거나 테스트가 잘못 작성된 경우를 잡아내는 거죠.

Green 단계에서는 테스트를 통과하기 위한 최소한의 코드를 작성합니다. 필요한 것만 딱 만들고 넘어가는 거예요.

마지막으로 Refactor 단계에서 코드를 정리합니다. 중복을 제거하고, 이름을 개선하고, 구조를 다듬죠. 테스트가 여전히 통과하는지 확인하면서요.

사람이 혼자 TDD를 하면 귀찮다는 이유로 Red 단계를 건너뛰거나 Refactor를 미루기 쉬운데, Superpowers는 이걸 강제하니까 규율이 유지됩니다.

스펙 리뷰 루프

실행 계획을 세웠다고 바로 구현에 들어가는 게 아닙니다. Superpowers 5부터는 적대적 리뷰 루프(adversarial review loop)가 추가되었습니다.

별도의 서브 에이전트가 계획 문서를 검토해서 빈 곳을 찾아냅니다. “TBD”라고 적어둔 섹션, 에러 처리가 빠진 부분, 모호한 인터페이스 정의 같은 것들을 잡아내죠. 실제 코드를 쓰기 전에 스펙의 완성도를 끌어올리는 과정입니다.

코드 리뷰를 구현 후에 하는 건 당연하지만, 스펙 리뷰를 구현 전에 하는 건 의외로 많은 팀이 놓치는 부분이에요. 스펙에서 구멍을 발견하면 코드 한 줄 안 쓰고도 문제를 해결할 수 있으니까요.

서브에이전트 기반 개발

Superpowers 5는 서브 에이전트를 기본 워크플로우로 채택했습니다. 실행 계획이 충분히 상세하면 각 구현 단위를 서브 에이전트에게 넘기는 방식이에요.

여기서 영리한 점은 모델 선택입니다. 상세한 계획이 있으면 구현 자체는 비교적 단순한 작업이 되거든요. 그래서 Superpowers는 상황에 따라 Haiku 같은 가벼운 모델을 구현에 투입합니다. 비용이 절감되는 건 물론이고, 메인 컨텍스트 윈도우도 깔끔하게 유지됩니다. 구현 과정에서 쌓이는 수많은 중간 결과물이 서브 에이전트 쪽에만 남고, 메인 대화에는 결과 요약만 돌아오니까요.

각 서브 에이전트가 구현을 마치면 코드 리뷰 에이전트가 자동으로 실행됩니다. 계획 대비 구현이 맞는지, 코딩 표준을 따르는지, 아키텍처 원칙에 어긋나지 않는지를 검토하죠. 사람이 PR 리뷰를 하는 것처럼 자동화된 품질 게이트를 거치는 겁니다.

체계적 디버깅

버그를 만나면 Claude에게 “이거 고쳐줘”라고 하기 쉬운데, Superpowers는 4단계 디버깅 방법론을 따릅니다.

첫 번째는 증상 관찰입니다. 에러 메시지, 재현 조건, 영향 범위를 파악하는 단계예요. 두 번째는 원인 조사입니다. 코드를 따라가면서 왜 이런 일이 벌어지는지 근본 원인을 찾죠. 세 번째가 수정인데, 여기서도 TDD를 따릅니다. 버그를 재현하는 테스트를 먼저 작성하고 나서 수정하는 거예요. 네 번째는 검증입니다. 수정이 다른 곳에 영향을 주지 않는지 확인합니다.

여기에 안전장치도 있습니다. 같은 문제를 세 번 연속 수정에 실패하면 Superpowers가 자동으로 아키텍처 리뷰를 트리거합니다. “이 정도면 단순 버그가 아니라 설계에 문제가 있을 수 있다”는 판단인데요. 사람도 같은 버그를 계속 못 고치면 한 발짝 물러나서 전체 구조를 다시 보잖아요. 그걸 자동으로 해주는 거죠.

소프트웨어 설계 원칙

Superpowers는 코드를 쓰는 방식에도 원칙을 적용합니다.

유닛 분해를 강조합니다. 하나의 함수나 모듈이 하나의 명확한 목적을 가지고, 테스트 가능한 인터페이스를 제공해야 한다는 원칙이에요. 구현에 들어가기 전에 파일 구조를 먼저 계획하도록 유도하는 것도 특징입니다. 어디에 어떤 파일이 들어가고, 파일 간 의존관계가 어떤지를 미리 잡고 시작하는 거죠.

인터페이스 중심 설계도 빼놓을 수 없습니다. 스펙 작성 단계부터 구현 단계까지 일관되게 인터페이스를 먼저 정의하고 구현은 그 뒤에 합니다. 프로젝트가 너무 크다고 판단되면 Claude가 먼저 분할을 제안하기도 해요. “이건 한 번에 하기엔 범위가 큽니다. 이렇게 나눠서 진행하는 건 어떨까요?”라는 식으로요.

설정과 커스터마이징

Superpowers는 프로젝트의 기존 설정을 존중합니다. CLAUDE.md나 AGENTS.md에 정의된 규칙이 Superpowers 내부 설정보다 우선적으로 적용되거든요. 예를 들어 CLAUDE.md에 “테스트 프레임워크는 Vitest를 사용한다”라고 적어뒀으면, Superpowers의 TDD 워크플로우가 Jest 대신 Vitest로 테스트를 작성합니다.

스펙과 계획 문서는 프로젝트의 docs/superpowers/ 디렉토리에 저장됩니다. Git으로 관리할 수 있으니 팀원과 공유하거나 나중에 참고하기에도 좋아요. 이전 버전에서는 docs/plans/에 저장했는데, Superpowers 5에서 경로가 변경되었습니다.

기존의 슬래시 커맨드(/brainstorming, /execute-plan 등)는 네이티브 스킬 시스템과 통합되면서 superpowers: 네임스페이스로 이동했습니다. 더 이상 다른 플러그인의 커맨드와 이름이 충돌할 걱정이 없죠.

마치며

Superpowers가 하는 일을 한마디로 정리하면, 숙련된 개발자가 습관적으로 하는 행동들을 AI에게 체계적으로 가르치는 겁니다. 테스트부터 쓰고, 계획을 검토받고, 설계 원칙을 따르고, 막히면 한 발 물러서서 생각하는 것들이요.

물론 이런 걸 매번 프롬프트로 직접 지시할 수도 있습니다. 하지만 매번 “테스트 먼저 써, TDD로 해, 실패 확인해”라고 반복하는 건 현실적이지 않죠. Superpowers는 이걸 플러그인 하나로 자동화합니다.

설치는 간단하니 한번 써보시고, 작동 방식이 마음에 드시면 소스 코드를 들여다보는 것도 추천합니다. 어떤 프롬프트로 Claude에게 TDD를 가르치는지, 서브 에이전트에게 어떻게 작업을 분배하는지 보면 직접 스킬을 만들 때도 참고가 될 거예요.

클로드 코드 자체가 궁금하다면 클로드 코드를, 플러그인 시스템이 궁금하다면 클로드 코드 플러그인 사용법을 참고해보세요. 서브 에이전트의 동작 원리가 궁금하다면 클로드 코드 서브 에이전트도 도움이 됩니다.