9 장. Superpowers — 시각적 컴패니언 · 서브에이전트 · 2 단계 리뷰
"설계가 없는 AI 는 폭주하고, 하네스가 있는 AI 는 자기 검증 을 한다."
도입 — 추상 표 → 손에 잡히는 도구
8 장이 4 계층 아키텍처 의 지도 였다면, 9 장은 *그 지도 위에 실제로 도시를 짓는 도구 * 다.
이 도구의 이름은 Superpowers. 과장된 마케팅 단어처럼 들릴 수 있지만 — 실제 GitHub 에 있는 플러그인 패키지 의 이름 이다 (obra/superpowers). 이 책에서는 *Superpowers = 하네스 엔지니어링의 대표 구현체 * 로 다룬다.
3 대 핵심 개념을 미리 기록한다.
| # | 개념 | 무엇을 하는가 |
|---|---|---|
| 1 | 시각적 컴패니언 (Visual Companion) | 코드 전 에 브라우저에 목업 보여주고 사용자 승인 |
| 2 | 서브에이전트 주도 개발 (Subagent-Driven Development) | 마이크로 태스크마다 신선한 서브 에이전트 파견 |
| 3 | 2 단계 리뷰 (Two-Stage Review) | 스펙 준수 + 코드 품질 두 단계 자동 검증 |
이 셋이 합쳐서 Design → Planning → Execution 의 3 단계 파이프라인을 시스템 레벨에서 강제 한다. *플러그인 자체가 설계 우선을 못 어기게 * 만든다는 뜻이다.
Superpowers 의 정의
저자의 표현으로 — "컨텍스트 오염과 요구사항 표류를 시스템적으로 차단."
이 한 문장이 7 장의 두 메커니즘 (Context Rot + Requirements Drift) 을 그대로 인용한다. *7 장에서 진단한 두 질병을 치료하는 약 * 이 Superpowers 라는 뜻.
치료 방식은 시스템 레벨 에서다. 즉 — *개발자의 의지에만 의존하지 않는다. 파이프라인 자체 가 우회를 막는다. 이게 하네스 엔지니어링 의 핵심 — 경험·규율을 시스템으로 외재화 (8 장 마지막).
1 — 시각적 컴패니언 (Visual Companion)
첫 번째 개념. 문제의식부터.
AI 가 코드를 짜고 나서야 "아 이게 아니었네" 라고 깨닫는 일이 너무 자주 일어난다.
이걸 코드를 짜기 전에 깨닫게 하면 어떨까? 그게 시각적 컴패니언 이다.
작동 방식:
1. 사용자: "관리자 대시보드 만들어 줘"
↓
2. 에이전트: 코드 짜기 *전* 에 →
목업·아키텍처 다이어그램·UI 와이어프레임을
`screen_dir` 폴더에 HTML 프래그먼트로 저장
↓
3. 로컬 HTTP 서버가 CSS 테마와 결합해
브라우저에 렌더링
↓
4. [★ 사용자 검토 ★]
브라우저에서 "이거 아닌데" 라고 클릭/선택
↓
5. 클릭 이벤트가 `state_dir/events` 로깅 →
*다음 프롬프트에 역주입*
↓
6. 에이전트: 수정된 의도로 다시 시도
이 패턴의 강점은 세 가지 다.
- 비용 비대칭 차단 (8 장의 저장소 영향 지도 와 같은 원리). 목업 단계 수정 = 매우 쉬움. 코드 수정 = 매우 어려움.
- 시각적 피드백이 언어로 표현 안 되는 의도 를 잡는다. 학생이 "이거 아냐" 라고 말은 못 해도 손으로 가리킬 수는 있다.
- *비개발자 사용자도 함께 검토 * 가능. 코드를 못 봐도 화면은 본다.
이게 Requirements Drift (요구사항 표류) 의 답이다 — 이미지에 기록된 요구사항은 표류하지 않는다.
2 — 서브에이전트 주도 개발 (Subagent-Driven Development)
두 번째 개념. 문제의식.
AI 가 1 시간 동안 한 세션을 끌면 — 판단력이 떨어진다. 사람과 똑같이.
이건 7 장의 Context Rot 메커니즘이다. 단일 세션 장시간 → 컨텍스트 오염 필연. AI 모델이 기억 하는 것이 너무 많아지면 — 과거의 잘못된 결정 까지 현재의 맥락에 섞여 들어간다.
해결책은 조직론 에서 가져왔다.
메인 에이전트 = 오케스트레이터 (지휘자)
- 전체 계획을 본다
- 마이크로 태스크로 분해 (5 분 단위)
서브 에이전트들 = 신선한 일꾼
- 마이크로 태스크 *하나씩 새로 * 받아 실행
- 이전 대화 없음 — 명세서만 들고 일한다
- 끝나면 결과만 메인에 반환 후 사라진다
이 구조가 강력한 이유 — 각 서브 에이전트의 컨텍스트 는 깨끗 하다. 이전 작업의 잘못된 가정이 묻지 않는다. 메인 에이전트는 전체 그림만 들고 있고 세부 작업의 컨텍스트 는 갖지 않는다.
여러분의 학기 팀 프로젝트 비유로 — 팀장 (메인) 이 5 명 팀원에게 각각 명확한 업무를 주고, 팀원은 자기 일만 한 뒤 결과를 가져온다. 팀장이 모든 세부를 알 필요 없다. 팀원이 옆 팀원의 코드 를 알 필요 없다. 명확한 업무 분담 이 컨텍스트 오염을 막는다.
dispatching-parallel-agents 라는 스킬이 *서브 에이전트 병렬 실행 * 을 가능하게 한다. 즉 — 5 명 팀원이 동시에 일하고 결과만 모인다. 시간 압축의 또 다른 비결.
3 — 2 단계 리뷰 (Two-Stage Review)
세 번째 개념. 문제의식.
AI 가 자기 코드를 스스로 검토 하면 — 자기 편을 든다.
이건 인간도 마찬가지다. *자기 코드의 버그가 자기 눈에는 안 보인다. 그래서 코드 리뷰 문화가 생겼다 — 다른 사람이 본다.
AI 시대의 코드 리뷰 문화 가 2 단계 리뷰다.
1 단계: 스펙 준수 리뷰어
- 역할: 구현 코드 vs 초기 계획 대조
- 체크: 누락된 기능 / 의도치 않은 추가 / 명세 위반
- 심사 결과: Critical 발견 시 즉시 중단 → 재작업 → 재심사
2 단계: 코드 품질 리뷰어
- 역할: 아키텍처 / 성능 / 안티패턴 심사
- 체크: 가독성 / 모듈성 / 컨벤션 준수 / 성능 함정
- 심사 결과: 동일 — Critical 시 재작업
이 두 리뷰어는 서로 다른 컨텍스트 에서 동작한다. 1 단계는 명세 컨텍스트만, 2 단계는 코드 컨벤션 컨텍스트만 — *두 시각이 각각 독립적으로 검토 * 한다.
이걸 GAN (Generative Adversarial Network) 영감 이라고 부른다. 생성하는 쪽 (작가) 과 반대편 에서 비판하는 쪽 (비평가) 이 서로 적대적 으로 작동 — 그 적대 가 결과를 자가 정제 한다. (GAN 모르는 학생은 "이중 심사 위원회" 정도로 이해하면 된다.)
TDD 철칙 — 테스트 없이 코드 없다
이 셋과 함께 작동하는 철칙 이 하나 있다. 영어 그대로 인용한다.
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST — 실패하는 테스트 없이는 프로덕션 코드 없다.
Test-Driven Development (TDD) 의 Red-Green-Refactor 사이클이다.
1. RED: 실패하는 테스트를 *먼저* 작성
──── 실행 → 빨간색 (실패) ────
2. GREEN: 테스트가 *통과할 *최소한의 코드* 작성
──── 실행 → 초록색 (통과) ────
3. REFACTOR: 통과한 상태에서 *코드 정제*
──── 테스트가 안전망 ────
이 사이클이 AI 협업 에 적용되면 — AI 가 테스트 없이 프로덕션 코드 작성하면 시스템 훅이 즉각 삭제 *. 매우 강한 규율이다. 철칙 수준의 강도.
이게 너무 강해 보일 수 있다. 실제로 그렇다. Superpowers 가 의도적으로 이렇게 강하게 만든 이유 — AI 의 "이번 한 번만" 을 시스템이 거부하기 위해서. 인간은 피곤할 때 TDD 를 건너뛴다. 시스템은 피곤하지 않다.
3 레이어 다층 아키텍처
위 3 개념 + TDD 가 어디에 어떻게 박히는가 를 3 레이어 로 정리.
| 레이어 | 무엇 | 무엇을 막는가 |
|---|---|---|
| L1. 실행 격리 | Git Worktree (격리 브랜치) | 메인 시스템 훼손 |
| L2. 시각적 검증 | 로컬 HTTP 서버 + 브라우저 승인 | 언어로 안 잡히는 의도 오류 |
| L3. TDD 샌드박스 | 단위 테스트 + 정적 분석 + 시스템 훅 | 코드 품질 미달 |
이 3 레이어가 동시에 작동한다. L1 이 격리해 주니 과감한 시도가 가능. L2 가 시각적으로 검증 하니 의도 어긋남이 코드 전에 잡힘. L3 가 기술적으로 검증 하니 Accept All 의 위험이 차단.
5 단계 워크플로 플레이북 — 손에 잡히는 순서
마지막으로 Superpowers 를 실제로 어떻게 굴리는가 의 5 단계.
1. brainstorming
→ 요구사항 명세서 + 시각적 컴패니언
↓
2. using-git-worktrees
→ 격리 브랜치 (L1)
↓
3. writing-plans
→ 5 분 단위 마이크로 태스크 분해
↓
4. subagent-driven-development
→ 태스크마다 새 서브 에이전트 + TDD (L3)
↓
5. requesting-code-review
→ 2 단계 리뷰 (스펙 준수 + 코드 품질)
이 5 단계가 15 장 약국 마케팅 에이전트 시연 에서 실제 작동하는 모습 을 본다. 이 책에서 가장 손에 잡히는 순간이다.
그래서 어떻게 시작하나 — 학생 시각
이 9 장을 읽으면 학생이 "이거 다 어디서 다운로드 받나" 라고 묻고 싶어진다. 답을 기록한다.
- GitHub:
obra/superpowers(검색 가능) - YouTube 데모: 저자 영상 (
youtu.be/4ZYIBTB-Bxk) - 로컬 설치: Claude Code 플러그인 시스템
여기서 한 가지 안내를 기록한다. 오늘 다운로드 받지 마라. 이 책 16 장의 5 종 체크리스트 부터 손에 익힌 뒤에 — 그 다음에 Superpowers 를 도입하라.
이유는 — *Superpowers 는 5 종 체크리스트가 시스템화된 형태 *. 체크리스트도 손에 안 익은 사람이 시스템부터 도입하면 — 시스템에 종속되어 왜 그렇게 작동하는지 모르는 채 쓰게 된다. 원리부터 손에 익히고 시스템으로 옮겨가는 것 이 정확한 순서.
이 책 전체가 그 순서에 정렬돼 있다. 원리 (1~12 장) → 시연 (15 장) → 행동 (16 장 5 종 체크리스트) → 시스템화 (졸업 후 Superpowers 도입).
9 장 정리 — 기술이 갖춰진다
8 장의 추상 4 계층 이 9 장에서 손에 잡히는 도구 로 바뀌었다.
- 시각적 컴패니언 — Requirements Drift 의 답
- 서브에이전트 — Context Rot 의 답
- 2 단계 리뷰 — Accept All 의 답
- TDD 철칙 — 코드 품질 미달 의 답
- Git Worktree — 메인 시스템 훼손 의 답
이 다섯이 합쳐서 3 부 8 장의 4 계층 아키텍처 의 3 계층 (하네스) 을 실제로 채우는 것 *.
표어로 닫는다.
AI-Native Vibe Coding: No Design, No Code. — Superpowers = No Design 함정을 시스템이 강제로 막는 도구. 그래서 작동한다.
다음 10 장에서 — *이 모든 것이 왜 작동하는가 의 원리 * 를 본다. Boris Cherny (Anthropic Claude Code 책임자) 가 정의한 검증 루프 의 한 줄. 이 책에서 가장 *짧지만 깊은 * 한 장이다.
"LLM 의 핵심은 인간이 검증을 얼마나 빠르게 할 수 있느냐다."