AI 코딩 에이전트를 17번 고장낸 후 마침내 해결책을 찾았다 — Superpowers

5분 만에 읽을 수 있음

지난주 목요일, 오후 11시. 나는 AI 에이전트에게 대시보드의 데이터 시각화 패널을 디자인하도록 요청했습니다. 에이전트는 "완료했습니다"라고 말했습니다.

git diff

로 확인해 보니——12개의 파일이 변경되어 있었습니다. 그중 5개는 모달 컴포넌트 (Modal Component)와 전혀 무관했습니다. 사이드바 레이아웃의 CSS는 통째로 다시 작성되었고, 삭제되지 말았어야 할 유틸리티 함수 파일은 사라져 있었습니다. 3곳에서 스타일 충돌이 발생하고 있었습니다.

화면 앞에서 2분 동안 침묵했습니다. 분노가 아니었습니다. 깊은 피로감이었습니다.

되돌아보며 계산해 보았습니다. 지난 3개월 동안 AI 에이전트에게 컴포넌트 생성, 스타일 수정, 프로토타입 제작——모든 작업을 맡겼습니다. 토큰 비용은 일본 엔화로 약 15,000엔. 그리고 에이전트가 만들어낸 버그를 수정하는 데 소비한 시간——100시간 이상이었습니다.

그러던 중 GitHub Trending에서 발견한 것이 Superpowers입니다. 203,000 Stars, 18,100 Forks, MIT 라이선스. 읽기 시작한 지 10분 후, 나는 자리에서 일어나 방 안을 서성였습니다. 그 강력함에 놀란 것이 아니라——작성자가 나와 완전히 똑같은 고통을 경험했고, 그것을 에이전트에 장착 가능한 "프로세스 외골격 (Process Exoskeleton)"으로 형상화했기 때문입니다.

이 기사는 다음과 같은 분들에게 추천합니다:

AI 코딩 에이전트 (Cursor, Claude Code, GitHub Copilot 등)를 매일의 프로젝트에서 활용하고 있는 분 - 에이전트의 "작성 속도는 빠르지만, 실수도 많다"는 딜레마에 고민하고 있는 분

• TDD나 코드 리뷰 (Code Review)와 같은 소프트웨어 공학의 베스트 프랙티스 (Best Practices)를 AI 에이전트에도 적용하고 싶은 분
• 203k Stars의 주목받는 프로젝트가 실제로 무엇을 해결하는지를 단시간에 이해하고 싶은 분 - Superpowers 도입을 검토 중이지만, 비용이나 트레이드오프 (Trade-off)를 포함하여 판단하고 싶은 분

AI 코딩 에이전트를 깊게 사용할수록, 세 가지 문제에 직면하게 됩니다.

1. 플라잉 (Requirements Skipping - 요구사항 건너뛰기)

대시보드를 "디자인해 줘"라고 한마디 부탁했을 뿐인데——에이전트는 데스크톱인지 모바일인지 묻지도 않고, 디자인 시스템을 확인하지도 않고, 기존 페이지의 컴포넌트 트리 (Component Tree)를 조사하지도 않은 채, 갑자기 수백 줄의 코드를 생성하기 시작합니다. 작성을 시켜보니 우리의 의도와는 완전히 다른 결과물이 되어 있었다——그런 경험은 없으신가요?

2. 일탈 (Context Wandering - 컨텍스트 방황)

AI 에이전트는 작업 중에 "덤으로" 관계없는 모듈을 "최적화"하기 시작합니다. 팝업 간격을 조정해 달라고 했을 뿐인데, 디자인 시스템 전체의 변수 테이블이 다시 작성됩니다. 버튼을 하나 추가했을 뿐인데, 레이아웃 모듈이 통째로 리팩터링 (Refactoring)됩니다. AI가 "열심히 하고 있다"는 점은 부정할 수 없습니다. 하지만 그 노력의 방향이 우리의 의도와 전혀 일치하지 않는 것입니다.

3. 성공의 과잉 선언 (Premature Success - 성급한 성공 선언)

에이전트는 "완료했습니다"라고 말합니다. 출력에는 "태스크 성공"이라고 표시됩니다. 하지만 실제로 실행해 보면 Storybook이 에러를 내뱉고, 단위 테스트 (Unit Test)는 통과하지 못하며, 다크 모드 스타일은 고려되지 않았습니다. "확인 다이얼로그가 포함된 모달 컴포넌트를 구현해 줘"라고 부탁하면 "했습니다"라고 말하지만, 그 컴포넌트가 의존하는 UI 라이브러리가 애초에 프로젝트에 설치되어 있지 않은——그런 일이 일상적으로 일어납니다.

핵심적인 모순: AI 에이전트는 본질적으로 "고처리량 (High-throughput) 코드 텍스트 생성기"이지만, 소프트웨어 공학에 필요한 것은 "저엔트로피 (Low-entropy)의 점진적 인도 (Incremental Delivery)"입니다. 이 두 가지는 본질적으로 상충합니다. 에이전트의 코드 생성 속도가 빠르면 빠를수록, 당신이 빠지는 함정의 빈도도 높아집니다. 속도는 해결책이 아닙니다. 속도는 확대경입니다. 당신의 프로세스에 원래 있었던 문제를 10배로 확대할 뿐입니다.

— Source: 본고 작성자의 실체험으로부터

저도 시도했습니다. 정말로 시도했습니다.

300줄의 프로젝트 인스트럭션 (Instruction) 파일을 작성했습니다. 제약 조건, 실례, 금지 사항을 담았고, 시스템 프롬프트 (System Prompt)도 최적화했습니다.

효과는? 어느 정도 있었습니다. 지속성은? 없었습니다.

에이전트는 간헐적으로 예전의 나쁜 습관으로 돌아갑니다. 마치 "매우 똑똑하지만, 내 말은 전혀 듣지 않는 동료" 같습니다. "관련 없는 파일을 마음대로 변경하지 마"라고 전달해도, 대화가 5턴 정도 진행되면 컨텍스트 윈도우 (Context Window)가 롤링(Rolling)되어 잊어버립니다. "먼저 테스트를 작성해"라고 말하면 "네"라고 대답하고, 실제로는 assert true라고만 적어둡니다.

이것은 에이전트의 잘못이 아닙니다. "프로세스 규율"이라는 아키텍처 레벨에서 보장되어야 할 것을, 텍스트를 통한 "부탁"에 맡겼던 쪽의 문제입니다.

중요한 통찰: Superpowers의 핵심 설계 사상은——에이전트를 논리로 설득하려 하지 않는 것입니다. 프로세스 외골격을 장착시키는 것입니다. 각 단계에는 검증이 있고, 체크포인트가 있으며, 건너뛰기는 허용되지 않습니다.

— Source: Superpowers 공식 문서에서 요약

Superpowers의 제작자는 더 나은 프롬프트 템플릿 (Prompt Template)을 만든 것이 아닙니다. 소프트웨어 공학의 베스트 프랙티스(Best Practices)——요구사항 명확화, 워크스페이스 분리, 태스크 분할, TDD, 코드 리뷰, 브랜치 완료 처리——를 모두 건너뛸 수 없는 단계로 구현한 것입니다.

Superpowers를 장착한 AI 에이전트는 다음의 7단계를 강제받습니다.

Step 1 — 브레인스토밍 (요구사항 확인)

에이전트는 코드를 작성하기 전에 멈춥니다. 그리고 질문을 던집니다: "이 대시보드는 데스크톱용인가요, 모바일용인가요? 사용할 디자인 시스템은 무엇인가요? 기존 페이지의 컴포넌트 트리 구조는 어떻게 되나요? 대응해야 할 브레이크포인트 (Breakpoint)는 무엇인가요?" —— "성급한 실행" 문제는 이 첫 번째 게이트에서 차단됩니다.

Step 2 — 워크트리 (작업 분리)

"먼저 격리된 워크스페이스를 생성합니다" —— 이것이 워크트리 (Worktree)입니다. 메인 브랜치에는 손대지 않습니다. 레이아웃 모듈에도 손대지 않습니다. 글로벌 스타일에도 손대지 않습니다. 에이전트는 완전한 샌드박스 (Sandbox) 내에서 작업합니다. "이탈"이 물리적으로 격리됩니다.

Step 3 — 플래닝 (태스크 분할)

"대시보드를 디자인한다"라는 막연한 한 줄이 아니라, src/components/Modal/index.tsx의 85행 이후에 다크 모드 대응을 추가하고, 기존의 3개 Storybook 테스트를 실행하여 기존 컴포넌트를 파괴하지 않는지 확인한다는 수준까지 구체화합니다. 각 태스크는 2~5분 내에 완료할 수 있는 크기로 분할됩니다.

Step 4 — 서브 에이전트 (병렬 실행)

분할된 각 태스크는 독립된 서브 에이전트 (Sub-agent)에 의해 실행됩니다.

Step 5 — TDD (테스트 주도 개발)

이것은 가장 강력한 단계입니다. 에이전트는 먼저 반드시 실패하는 테스트를 작성합니다. 레드 신호 (Red signal, 테스트 실패)를 확인한 후에야 비로소 이를 통과시키는 코드를 작성하는 것이 허용됩니다. 그린 신호 (Green signal, 테스트 통과)를 확인한 후 리팩터링 (Refactoring)할 수 있습니다. 테스트를 건너뛴다? 프로세스는 다음으로 진행되지 않습니다. "성공의 과잉 선언"은, TDD의 레드 신호도 그린 신호도 한 번도 점등하지 않은 에이전트가 "완료했다"라고 말할 수 없는 구조를 통해 방지됩니다.

Step 6 — 코드 리뷰

보안 취약점? 즉시 반려. 논리적 결함? 머지 (Merge) 차단. 스타일 문제? 마크는 남기되 차단은 하지 않음.

Step 7 — 피니싱 (완료 처리)

완전한 검증을 수행한 후, 4가지 선택지가 제시됩니다: 머지 (Merge) / PR / 저장 / 폐기. 당신이 선택합니다.

한마디로 말하자면: Superpowers는 "소프트웨어 공학적 규율"을 인간의 체크리스트에서 에이전트의 실행 경로로 변환한 것입니다. 에이전트가 따르지 않는다? 다음 단계로 넘어갈 수 없습니다. 그것뿐입니다.

Superpowers는 단순한 폴더 구조가 아닙니다. 4개의 계층으로 설계되어 있습니다.

계층	역할
배포층 (Distribution)	스킬을 서로 다른 에이전트에 탑재. 여러 플랫폼에 동일한 스킬을 배포
강제층 (Enforcement)	에이전트 기동 시 프로젝트 인스트럭션 (Project Instruction)을 직접 주입. 첫 번째 지시는 "규칙을 준수하라"
실행층 (Execution)	브레인스토밍 (Brainstorming), TDD, 워크트리 (Worktree), 서브 에이전트 (Sub-agent), 코드 리뷰 (Code Review) — 모두 호출 가능한 스킬 파일로 구현
검증층 (Verification)	훅 (Hooks)과 테스트를 통해 각 스킬이 실제 에이전트 세션에서 준수되고 있는지 확인

기존의 스킬 시스템은 "공구함이 구석에 놓여 있다. 에이전트는 사용해도 되고, 사용하지 않아도 된다"는 식이었습니다. Superpowers는 "공구함을 현관에 두고, '여기서 도구를 꺼내지 않으면 문은 열리지 않는다'라고 써 붙여 놓은" 상태를 만들어냅니다.

더욱 주목할 점은 **메타 스킬 루프 (Meta-skill loop)**의 존재입니다. Superpowers에는 writing-skills라는 스킬이 포함되어 있으며, 이를 사용하여 새로운 Superpowers 스킬을 작성하는 법을 배울 수 있습니다. "보안 체크 단계가 부족하다"고 느껴지면, 직접 스킬을 작성하여 워크플로우에 추가할 수 있습니다. 이 프레임워크는 스스로 진화할 수 있습니다.

저 자신도 Superpowers의 지지자입니다. 하지만 그 완벽함을 찬양할 생각은 없습니다.

토큰 소비가 2~3배 증가

7개의 단계가 있으며, 각 단계에서 에이전트가 방대한 컨텍스트 (Context) 정보를 처리합니다. 브레인스토밍에서 수백 줄, 플래닝 (Planning)에서 추가로 수백 줄, TDD 사이클 (Red $\rightarrow$ Green $\rightarrow$ Refactoring)에서 최소 3회 왕복합니다. 기존에 1,000 토큰으로 끝나던 작업이 3,000 토큰이 됩니다. API 비용은 2~3배가 됩니다. 이는 상당한 비용 부담입니다.

프로세스 마찰이 현저함

단지 코드 3줄을 추가하고 싶을 때도 있습니다. 단순한 if 판정 추가일 뿐입니다. 하지만 Superpowers는 브레인스토밍 $\rightarrow$ 플래닝 $\rightarrow$ 서브 에이전트 $\rightarrow$ TDD $\rightarrow$ 코드 리뷰 $\rightarrow$ 피니싱 (Finishing) 과정을 거치게 합니다. 벽에 못 하나를 박아 그림을 걸고 싶을 뿐인데, Superpowers는 "먼저 지질 조사를 하고, 다음으로 구조 계산을 한 뒤, 건설 허가를 받고, 마지막으로 관리 감독 검사를 받으시오"라고 말하는 것과 같습니다.

설치 장벽이 낮지 않음

npm install로 끝나는 것이 아닙니다. 4층 아키텍처에 대한 이해, 각 플랫폼용 하네스 (Harness) 설정, 프로젝트 인스트럭션의 우선순위 조정, 훅 (Hook)의 정상 작동 확인 등 — 문제가 발생했을 때 원인을 파악하는 데 시간이 걸립니다.

TDD는 필수 — 피할 수 없음

TDD를 사용하지 않는 개발 스타일의 경우, Superpowers는 매우 사용하기 어려울 것입니다. 이것은 "옵션"이 아닙니다. 핵심 프로세스의 강제적인 제약 사항입니다.

PR 기여 장벽이 극도로 높음

PR의 94%가 거절되고 있습니다. 이 수치는 언뜻 무서워 보이지만, 다른 관점에서 보면 — 프로젝트가 방법론의 순수성을 유지하기 위한 대가입니다. "프로세스 프레임워크"가 타협을 너무 많이 허용하면, 어느샌가 단순한 "추천 모음집"이 되어버리고 맙니다.

맞지 않는 시나리오: 일회성 스크립트, 프로토타입의 빠른 검증, 단순한 채팅 수준의 태스크, Git이나 테스트 습관이 없는 팀, 토큰 예산이 극도로 제한적인 경우.

비교 축	Superpowers	Microsoft Amplifier	GitHub Speckit
핵심적인 위치づけ	실행 규율 + TDD 프로세스 프레임워크	개발 보조 프레임워크	요구사항 주도 개발 (Requirement-driven development)
제약의 강도	강함 (스킵 불가)	부분적	강함
대응 플랫폼	11개 플랫폼	주로 Microsoft 에코시스템	주로 GitHub 에코시스템
TDD 강제	예 — 핵심 프로세스	권장하지만 강제는 아님	대상 외
커뮤니티 규모	203k Stars	소규모	소규모
설치 복잡도	중~고	저	중
메타 스킬	있음 (자기 진화 가능)	없음	없음
토큰 소비	2~3배	약 1.5배	1.5~2배

한마디로 요약하자면: Amplifier는 Microsoft 생태계의 개발 어시스턴트, Speckit은 GitHub 생태계의 요구사항 주도 (Requirement-driven) 도구, Superpowers는 현재로서 유일하게 TDD (테스트 주도 개발)와 코드 리뷰 (Code Review)를 에이전트의 실행 경로 (Execution path)에 내장한 크로스 플랫폼 (Cross-platform) 프레임워크입니다.

지금 바로 설치해야 하는 사람:

• 매일 본격적인 프로젝트에서 AI 에이전트를 사용하고 있는 사람
• 에이전트가 "작성 속도는 빠르지만 실수가 많다"는 문제로 진심으로 고민하고 있는 사람
• TDD, 코드 리뷰, 브랜치 관리 (Branch management)와 같은 공학적 규율을 존중하는 사람
• 프로젝트의 복잡도가 중간 단계 이상인 사람
• 토큰 비용이 2~3배 증가하더라도, "모든 변경 사항을 직접 리뷰할 필요가 없는 상태"를 선택하고 싶은 사람

먼저 도입을 미뤄야 하는 사람:

• 가끔 소규모 스크립트를 AI에게 작성하게 하는 정도인 사람
• 토큰 예산이 엄격하게 제한되어 있는 사람
• Git이나 테스트 습관이 아직 없는 사람 — 우선 이러한 기초를 다지는 것이 먼저입니다
• AI를 단순히 "더 빠른 타이피스트"로 취급하는 사람

최종 조언: 일주일에 2회 이상 "에이전트가 작성을 마쳤지만, 결국 내가 수정해야만 한다"는 경험을 하고 있다면, Superpowers를 도입할 가치가 있습니다. 그 비용은 현실적입니다. 하지만 도입하지 않음으로써 발생하는 비용은 그보다 더 클지도 모릅니다.

저는 Superpowers를 도입했습니다. 도입 3일 차.

AI 에이전트가 컴포넌트 (Component)를 설계하기 전에, 처음으로 질문을 던져왔습니다——

"이 요구사항의 범위는 모달 컴포넌트 (Modal component)에만 국한되며, 글로벌 레이아웃 (Global layout)에는 영향을 주지 않습니까?"

저는 이 한 줄을 5초 동안 멍하니 바라보았습니다.

그것이 단순히 똑똑해서가 아닙니다. 제약 조건을 부여받은 에이전트가 마침내 진정한 엔지니어처럼 작동하기 시작했기 때문입니다.

Superpowers는 에이전트를 더 똑똑하게 만드는 도구가 아닙니다. 에이전트에게 규율을 부여하는 프레임워크입니다. 만약 당신이 "에이전트에게 휘둘리고 있다"고 느낀다면 — 일단 한 번 시도해 보세요.