[Claude 활용 24회 — AI에게 일을 위임하는 법] 11/24화: Claude 서브에이전트 3단계 — AI를 팀으로 일 시키는 법
3줄 요약
- Claude 서브에이전트는 하나의 AI에게 ‘팀’을 짜주는 기능이다. 탐색·구현·검증을 각각 다른 에이전트가 맡으면 컨텍스트 오염 없이 대규모 작업이 가능해진다.
- 2026년 6월 업데이트로 3단계 중첩이 가능해졌다. 이건 프롬프트 기술이 아니라 조직 설계 기술이다.
- 단, 에이전트 하나가 곧 컨텍스트 하나이고 컨텍스트 하나가 곧 비용이다. 비용 상한 없이 쓰면 하루 만에 월 예산이 증발한다.
Anthropic 공식 문서에서는 이 기능을 “Task tool”이라 부른다. 하지만 실무에서 이걸 제대로 쓰려면 문서 한 장보다 실패 경험 한 번이 더 빠르다. 오늘은 내가 실패한 이야기부터 시작한다.
← 10화: MCP 서버 실전 가이드 ｜ 12화: 플러그인 — Skills+서브에이전트+훅+MCP를 하나로 →
파일 300개짜리 버그, 혼자 하다 터졌다
몇 달 전 일이다. 무중단이 기본인 시스템에서 금액 계산 오차가 리포트됐다. 소수점 셋째 자리에서 반올림이 안 맞는 건데, 문제는 이 계산 로직이 코드베이스 전체에 흩어져 있다는 거였다. API 레이어, 도메인 서비스, 정산 배치, 프론트엔드 표시 로직까지. 관련 파일만 대충 훑어도 300개가 넘었다.
Claude Code를 열고 한 세션에서 전부 해결하려 했다. “이 저장소에서 소수점 반올림 관련 로직을 전부 찾아서, 일관된 방식으로 수정해줘.” 전형적인 ‘알아서 잘’ 지시다. 4화에서 내가 직접 경고한 바로 그 패턴을 내가 밟았다.
처음 20분은 나쁘지 않았다. 에이전트가 파일을 읽고, 패턴을 분류하고, 수정 계획을 세웠다. 그런데 50개쯤 파일을 지나니까 이상한 일이 벌어졌다. 앞에서 이미 수정한 패턴을 다시 찾아서 “이것도 수정해야 합니다”라고 보고하기 시작한 것이다. 7화에서 다룬 컨텍스트 오염이 정확히 터진 거다. 탐색 과정에서 쌓인 수백 개 파일의 맥락이 구현 판단을 흐리고 있었다.
세션을 리셋하고 다시 시작했다. 이번엔 파일 목록을 먼저 뽑고, 그 목록을 기반으로 수정했다. 그래도 검증 단계에서 테스트를 돌리니 앞의 수정이 뒤의 테스트를 깨뜨리고, 깨진 테스트를 고치면 또 다른 데서 문제가 나왔다. 하나의 머리로 탐색·구현·검증을 동시에 하는 건 사람이든 AI든 한계가 있다.
사람 조직에서는 이걸 어떻게 해결하는가? 분업한다. 한 사람이 원인을 찾고, 다른 사람이 코드를 고치고, 또 다른 사람이 리뷰한다. 에이전트도 똑같다. 이게 Claude 서브에이전트의 핵심이다.
서브에이전트 — AI에게 조직도를 짜주는 일
서브에이전트가 뭔가
서브에이전트(Sub-agent)는 메인 에이전트가 특정 작업을 수행하기 위해 별도의 컨텍스트 창을 가진 하위 에이전트를 생성하는 기능이다. Claude Code에서는 이를 내부적으로 “Task tool”이라 부른다. 핵심은 세 가지다.
- 격리된 컨텍스트: 서브에이전트는 부모 에이전트와 완전히 분리된 컨텍스트 창을 갖는다. 탐색 에이전트가 300개 파일을 읽어도 구현 에이전트의 컨텍스트는 깨끗하다.
- 최소 권한: 서브에이전트에게 허용할 도구(파일 읽기만, 또는 편집까지)와 접근 가능한 디렉터리를 제한할 수 있다. 6화에서 다룬 권한 원칙의 연장이다.
- 결과 반환: 서브에이전트는 작업을 마치면 결과를 부모에게 텍스트로 보고한다. 부모는 이 보고를 기반으로 다음 판단을 내린다.
비유하자면, 혼자서 보고서를 쓰는 게 아니라 팀장이 되어 지시를 내리는 것이다. AI가 코드를 짜주는 시대가 아니라 AI에게 일을 위임하는 시대다. 위임할 줄 아는 사람이 하나의 회사가 된다 — 이 시리즈의 약속이 서브에이전트에서 가장 문자 그대로 실현된다.
3단계 중첩 — 부장·과장·사원 구조
2026년 6월 업데이트 전까지 서브에이전트는 1단계만 가능했다. 메인 에이전트가 서브에이전트를 부르면 끝. 이제는 3단계까지 중첩할 수 있다.
Level 0 오케스트레이터 (메인 에이전트)
├── Level 1 탐색 에이전트
│ ├── Level 2 API 레이어 스캐너
│ └── Level 2 도메인 레이어 스캐너
├── Level 1 구현 에이전트
│ ├── Level 2 백엔드 수정자
│ └── Level 2 프론트엔드 수정자
└── Level 1 검증 에이전트
└── Level 2 테스트 러너
이건 기술 기능이 아니라 조직 설계다. 어떤 역할이 필요한지, 각 역할에 어떤 권한을 줄지, 보고 라인은 어떻게 될지를 결정하는 일이다. 20년 동안 팀을 꾸리고 프로젝트를 운영한 경험이 여기서 그대로 적용된다. 주니어 개발자에게 “이 폴더만 보고 결과 알려줘”라고 지시하는 것과 완전히 같은 구조다.
왜 하나의 세션으로 안 되는가
7화에서 컨텍스트 관리를 다루면서, 100만 토큰 시대에도 절약이 필요한 이유를 설명했다. 서브에이전트는 그 문제의 구조적 해법이다.
하나의 세션이 탐색+구현+검증을 모두 하면 이런 일이 벌어진다.
- 탐색 잔류물: 수백 개 파일의 내용이 컨텍스트에 쌓여서, 실제 수정에 필요한 핵심 정보가 묻힌다.
- 역할 혼란: 방금까지 “모든 경우를 빠짐없이 찾아라”라는 탐색 모드였다가 갑자기 “최소한으로 정확하게 고쳐라”는 구현 모드로 전환해야 한다. 같은 컨텍스트 안에서 이 전환은 생각보다 잘 안 된다.
- 검증 편향: 자기가 짠 코드를 자기가 리뷰하면 놓치는 부분이 생긴다. 이건 사람도 마찬가지다. 격리된 컨텍스트의 검증 에이전트는 ‘수정 의도’를 모르기 때문에 오히려 냉정하게 평가할 수 있다.
정리하면 이렇다. 서브에이전트 = 강제 분업 + 강제 컨텍스트 격리. 사람 조직에서 코드 리뷰를 작성자 본인이 아닌 다른 사람이 하는 이유와 정확히 같다.
멀티 리포지토리 오케스트레이션 (베타)
아직 베타 단계이지만, 메인 에이전트가 여러 Git 저장소에 걸친 작업을 조율하는 기능도 생겼다. 예를 들어 백엔드 API 저장소의 응답 스키마를 바꾸면, 프론트엔드 저장소의 타입 정의와 통합 테스트 저장소의 픽스처도 함께 수정해야 하는 경우가 있다. 이전에는 세 저장소를 오가며 수동으로 맥락을 전달해야 했지만, 이제는 오케스트레이터가 각 저장소 전담 서브에이전트를 띄우고 결과를 모아서 정합성을 확인한다.
단, 베타인 만큼 주의할 게 있다. 각 저장소의 CLAUDE.md가 충돌하는 규칙을 담고 있으면 서브에이전트가 혼란에 빠진다. 5화에서 CLAUDE.md를 ‘저장소의 헌법’이라 불렀는데, 멀티 리포 환경에서는 헌법 간의 조약까지 필요한 셈이다. 현재로서는 오케스트레이터의 지시에 각 저장소의 컨벤션을 명시적으로 적어주는 게 가장 안정적이다.
실습 — 탐색자·구현자·검증자 3역할로 버그 하나 잡기
가상의 쇼핑몰 프로젝트를 예시로 들겠다. 주문 금액 합산에서 소수점 처리가 일관되지 않아 정산 불일치가 발생하는 버그다. 프로젝트 구조는 대략 이렇다고 가정한다.
my-shop/
├── backend/
│ ├── orders/ # 주문 생성·수정
│ ├── payments/ # 결제 처리
│ ├── settlements/ # 정산 배치
│ └── shared/ # 공통 유틸리티
├── frontend/
│ └── cart/ # 장바구니 표시
└── tests/
├── unit/
└── integration/
Step 1: CLAUDE.md에 역할 정의 추가
서브에이전트가 잘 작동하려면, 각 역할이 뭘 해야 하는지 CLAUDE.md에 명시하는 게 가장 확실하다. 9화에서 다룬 Skills과 결합하면 더 강력해지지만, 오늘은 CLAUDE.md만으로 해결하는 방법을 보겠다.
# CLAUDE.md (프로젝트 루트)
## 서브에이전트 역할 정의
### 탐색자 (Explorer)
- 목적: 버그의 근본 원인과 영향 범위를 파악한다.
- 허용 도구: 파일 읽기, 검색(Grep/Glob), 터미널(읽기 전용 명령만).
- 금지: 파일 수정, 테스트 실행.
- 출력 형식: 마크다운 보고서 — 원인 요약, 영향받는 파일 목록, 수정 방향 제안.
### 구현자 (Implementer)
- 목적: 탐색자의 보고서를 기반으로 코드를 수정한다.
- 허용 도구: 파일 읽기/쓰기, 터미널(빌드·린트만).
- 금지: 테스트 실행(검증자의 영역), 탐색자 보고서에 없는 파일 수정.
- 원칙: 최소 변경. 리팩터링 욕구를 참는다.
### 검증자 (Verifier)
- 목적: 수정된 코드가 올바른지 독립적으로 검증한다.
- 허용 도구: 파일 읽기, 터미널(테스트 실행, 타입체크).
- 금지: 파일 수정.
- 출력 형식: 합격/불합격 + 불합격 시 구체적 실패 내역.
이 정의가 있으면 Claude Code는 서브에이전트를 생성할 때 해당 역할의 규칙을 지시문으로 주입한다. CLAUDE.md는 사람에게 읽히는 문서인 동시에 에이전트에게 읽히는 지시서라는 걸 다시 한번 실감하게 된다.
Step 2: 오케스트레이터에게 작업 지시
이제 Claude Code에 다음과 같이 지시한다. 4화에서 배운 4요소(맥락·제약·완료조건·검증방법)를 넣는다.
맥락: my-shop 프로젝트에서 주문 금액 소수점 반올림이 일관되지 않아
정산 불일치가 발생하고 있다. backend/orders, backend/payments,
backend/settlements, frontend/cart 전체가 영향 범위일 수 있다.
제약: 서브에이전트 3역할(탐색자→구현자→검증자) 순서로 진행할 것.
각 역할은 CLAUDE.md의 '서브에이전트 역할 정의'를 따른다.
완료조건:
1. 소수점 처리가 Decimal 기반으로 통일
2. 기존 테스트 전체 통과
3. 검증자가 '합격' 판정
검증방법: pytest tests/ 전체 실행 + 검증자의 독립 리뷰
Step 3: 실행 과정 관찰
이 지시를 받은 메인 에이전트(오케스트레이터)는 다음과 같은 흐름으로 동작한다. 실제 터미널에서 보이는 흐름을 재현하면 이렇다.
╭─────────────────────────────────────────────────────╮
│ Main Agent (Orchestrator) │
│ "서브에이전트 3역할로 소수점 버그를 수정합니다." │
╰─────────────────────────────────────────────────────╯
⏳ Spawning sub-agent: Explorer
╭─────────────────────────────────────────────────────╮
│ Sub-agent L1: Explorer │
│ Searching for decimal/rounding patterns... │
│ │
│ Found 47 files with float arithmetic: │
│ - backend/orders/price_calc.py (L23, L45, L89) │
│ - backend/payments/charge.py (L12, L67) │
│ - backend/settlements/batch.py (L34, L56, L78) │
│ - frontend/cart/display.js (L15, L42) │
│ - backend/shared/math_utils.py (L5) ← 여기가 핵심 │
│ │
│ Root cause: math_utils.round_price()가 float 기반. │
│ 모든 호출처가 이 함수를 쓰지만, settlements만 │
│ 자체 반올림 로직을 별도로 가지고 있어 불일치 발생. │
│ │
│ Recommendation: math_utils.round_price()를 │
│ Decimal 기반으로 교체하고, settlements의 중복 │
│ 로직을 제거. │
│ │
│ Affected files: 47 (reading) / 5 (modification) │
╰─────────────────────────────────────────────────────╯
✅ Explorer complete. Report received.
⏳ Spawning sub-agent: Implementer
╭─────────────────────────────────────────────────────╮
│ Sub-agent L1: Implementer │
│ Reading Explorer report... │
│ │
│ Modifying 5 files: │
│ ✓ backend/shared/math_utils.py — Decimal 전환 │
│ ✓ backend/orders/price_calc.py — 호출부 정리 │
│ ✓ backend/payments/charge.py — 호출부 정리 │
│ ✓ backend/settlements/batch.py — 중복 로직 제거 │
│ ✓ frontend/cart/display.js — 표시 로직 정렬 │
│ │
│ Lint: ✅ pass │
│ Build: ✅ pass │
╰─────────────────────────────────────────────────────╯
✅ Implementer complete. Changes applied.
⏳ Spawning sub-agent: Verifier
╭─────────────────────────────────────────────────────╮
│ Sub-agent L1: Verifier │
│ Running test suite... │
│ │
│ pytest tests/unit/ — 142 passed, 0 failed │
│ pytest tests/integration/ — 38 passed, 0 failed │
│ │
│ Code review: │
│ - math_utils.round_price(): Decimal 변환 정상 │
│ - settlements/batch.py: 중복 제거 확인 │
│ - 경계값(0원, 음수, 매우 큰 금액) 테스트 존재 확인 │
│ │
│ Verdict: ✅ 합격 │
╰─────────────────────────────────────────────────────╯
✅ Verifier complete. All checks passed.
╭─────────────────────────────────────────────────────╮
│ Main Agent (Orchestrator) │
│ 3개 역할 모두 완료. 수정 요약: │
│ - 근본 원인: float 기반 반올림 (math_utils) │
│ - 수정: Decimal 전환 + 중복 로직 제거 │
│ - 영향: 5개 파일 수정, 180개 테스트 전체 통과 │
╰─────────────────────────────────────────────────────╯
주목할 점이 있다. 탐색자가 47개 파일을 읽었지만, 구현자의 컨텍스트에는 그 47개 파일 내용이 없다. 탐색자의 ‘보고서’만 전달됐다. 구현자는 보고서에 명시된 5개 파일만 열어서 수정했다. 이게 컨텍스트 격리의 위력이다.
마찬가지로 검증자는 구현자가 ‘왜’ 그렇게 고쳤는지 모른다. 코드 변경 사실만 보고 테스트를 돌리고 리뷰한다. 수정 의도를 모르기 때문에 “이 수정이 맞겠지”라는 확증 편향이 끼어들 여지가 없다.
Step 4: 더 복잡한 경우 — 2단계 중첩
파일이 수백 개이고 레이어별로 컨벤션이 다르다면, 탐색자 아래에 하위 에이전트를 두는 것도 가능하다.
맥락: (동일)
제약: 서브에이전트 구조를 다음과 같이 운영할 것.
- 탐색자
- API 레이어 스캐너 (backend/orders, backend/payments)
- 도메인 레이어 스캐너 (backend/settlements, backend/shared)
- 프론트 스캐너 (frontend/)
- 구현자
- 검증자
이러면 탐색자가 3개의 하위 스캐너를 병렬로 띄우고, 각 스캐너의 보고를 취합해서 구현자에게 전달한다. 이게 2단계 중첩(Level 0 → Level 1 → Level 2)이다. 3단계까지 가능하지만, 실무에서 3단계가 필요한 경우는 드물다. 2단계면 대부분의 대규모 작업을 커버할 수 있다.
서브에이전트 없이도 되는 경우
모든 작업에 서브에이전트를 쓸 필요는 없다. 다음 기준으로 판단한다.
- 파일 10개 이하, 단일 관심사: 서브에이전트 불필요. 메인 에이전트 단독이 더 빠르고 저렴하다.
- 파일 10~50개, 복수 관심사: 탐색자+구현자 2역할이면 충분. 검증은 메인이 직접.
- 파일 50개 이상, 또는 복수 저장소: 3역할 + 필요시 2단계 중첩.
서브에이전트를 남용하면 오히려 느려진다. 에이전트 하나를 띄우는 데도 초기 컨텍스트 로딩 시간이 걸린다. 간단한 일에 팀을 꾸리면 회의 시간이 작업 시간을 넘는 것과 같은 이치다.
도구와 디렉터리 — 최소 권한으로 격리하기
서브에이전트의 진정한 힘은 도구와 디렉터리 수준의 격리에 있다. Claude Code에서 서브에이전트를 생성할 때 다음을 제한할 수 있다.
도구 제한
# 오케스트레이터의 지시 예시
탐색자에게는 Read, Glob, Grep, Bash(읽기 전용) 도구만 허용.
구현자에게는 Read, Edit, Write, Bash(빌드·린트) 도구 허용.
검증자에게는 Read, Bash(테스트 실행) 도구만 허용.
6화에서 “프롬프트로 ‘하지 마’는 통제가 아니다”라고 했다. 서브에이전트의 도구 제한은 프롬프트 수준이 아니라 시스템 수준의 통제다. 검증자에게 Edit 도구를 주지 않으면, 아무리 “이 코드를 고쳐야 할 것 같다”고 판단해도 물리적으로 수정할 수 없다. 이게 진짜 최소 권한이다.
디렉터리 제한
# 각 스캐너의 접근 범위
API 레이어 스캐너: backend/orders/, backend/payments/ 만
도메인 레이어 스캐너: backend/settlements/, backend/shared/ 만
프론트 스캐너: frontend/ 만
디렉터리를 제한하면 불필요한 파일을 읽지 않으므로 컨텍스트가 절약된다. 동시에 의도치 않은 파일 수정도 방지된다. 감사 이력이 남아야 하는 조직에서는 이 격리가 필수다. “누가 어떤 범위를 건드렸는가”를 에이전트 단위로 추적할 수 있기 때문이다.
보고 형식 표준화
서브에이전트가 부모에게 돌려주는 보고가 일관되지 않으면 오케스트레이터가 혼란에 빠진다. CLAUDE.md에 보고 형식을 표준화해두면 이 문제를 예방할 수 있다.
# 서브에이전트 보고 형식
## 탐색 보고서 템플릿
- 근본 원인: (한 줄)
- 영향 범위: (파일 경로 목록)
- 수정 방향: (구현자가 바로 착수할 수 있는 수준)
- 위험 요소: (수정 시 부작용 가능성)
## 검증 보고서 템플릿
- 판정: 합격 / 불합격
- 테스트 결과: (통과/실패 수)
- 코드 리뷰 소견: (수정의 정확성, 누락된 경우)
- 불합격 시 구체적 실패: (파일:라인 + 증상)
이 템플릿이 있으면 오케스트레이터가 보고를 파싱하기 쉽고, 다음 에이전트에게 넘길 때도 정보 손실이 줄어든다. 9화에서 배운 Skills의 description 원칙과 동일하다 — 명확한 인터페이스 정의가 자동화의 핵심이다.
함정 3가지 — 서브에이전트를 쓰면서 반드시 피해야 할 것
함정 1: 에이전트 수 = 비용
이건 가장 중요하고 가장 간과하기 쉬운 함정이다. 서브에이전트 하나가 새 컨텍스트 창 하나다. 컨텍스트 창 하나는 입력 토큰 + 출력 토큰 비용이다. 3역할 구조에서 각 에이전트가 평균 50K 토큰을 쓴다면, 메인 에이전트 포함 총 4개 × 50K = 200K 토큰이다.
2단계 중첩으로 탐색자 아래 3개 스캐너를 띄우면? 총 7개 에이전트. 같은 계산으로 350K 토큰. MAX 구독이 아닌 API 과금이라면 작업 하나에 수 달러가 날아간다. Anthropic의 API 가격 페이지를 보면 이 계산이 왜 중요한지 체감된다.
MAX 구독 사용자라면 토큰 비용 자체는 고정이지만, 속도 제한(rate limit)에 걸릴 수 있다. 서브에이전트 7개가 동시에 추론 요청을 보내면 분당 요청 한도에 빠르게 도달한다.
함정 2: 비용 상한 없이 쓰면 하루 만에 월 예산 증발
Claude Code에는 세션별 비용 상한을 설정할 수 있다. 서브에이전트를 쓸 때는 이 설정이 선택이 아니라 필수다.
# ~/.claude/settings.json 또는 프로젝트 .claude/settings.json
{
"costThreshold": {
"warningUSD": 2.0,
"hardLimitUSD": 5.0
}
}
이 설정이 없으면 오케스트레이터가 “탐색이 부족하다”고 판단해서 추가 스캐너를 계속 띄우는 경우가 생긴다. 한번은 감사 이력이 남아야 하는 환경의 대규모 정산 코드를 분석하다가, 탐색 에이전트가 하위 스캐너를 8개나 만든 적이 있다. 다행히 MAX 구독이라 금전 피해는 없었지만, 속도 제한에 걸려서 30분 동안 아무것도 못 했다.
/effort 조절도 함께 쓴다. 탐색은 /effort low로 빠르게, 구현은 /effort high로 정밀하게. 이렇게 역할별로 노력 수준을 다르게 가져가면 전체 비용을 20~30% 절약할 수 있다.
함정 3: 역할 정의가 모호하면 중복 작업이 터진다
가장 흔한 실수다. 탐색자에게 “관련 파일을 찾고 수정 방향을 제안해”라고 했는데, 구현자에게도 “코드를 분석하고 수정해”라고 하면 어떻게 될까? 구현자가 탐색자의 보고를 무시하고 자기가 다시 분석을 시작한다. 결국 같은 일을 두 번 하고, 분석 결론이 달라서 수정 방향이 꼬인다.
해결책은 명확하다.
- 탐색자: “무엇이 문제인가”만 보고. 해결 방법은 제안까지만.
- 구현자: 탐색자의 보고서를 입력으로 받아서 코드만 수정. 자체 분석 금지.
- 검증자: 수정된 코드만 보고 테스트+리뷰. 수정 이유에 대한 추론 금지.
이건 소프트웨어 설계에서 말하는 단일 책임 원칙(SRP)과 같다. 각 에이전트가 하나의 책임만 지면 중복이 사라지고, 실패 시 어디서 문제가 생겼는지 즉시 파악할 수 있다.
추가 주의: 서브에이전트 간 순환 의존
간혹 오케스트레이터가 이런 흐름을 만들 때가 있다: 탐색자 → 구현자 → 검증자 → (실패) → 다시 탐색자. 이 순환이 3~4바퀴 돌면 전체 비용이 선형이 아니라 곱셈으로 늘어난다.
순환을 막는 가장 간단한 방법은 최대 반복 횟수를 지시에 명시하는 것이다.
제약: 탐색→구현→검증 사이클은 최대 2회 반복.
2회째 검증에서도 불합격이면 실패 보고서와 함께 멈출 것.
사람 팀에서도 무한 수정 루프를 방지하기 위해 리뷰 라운드 제한을 두는 것과 같다.
실전 패턴 — 이런 경우에 이렇게 쓴다
패턴 A: 대규모 리팩터링
오케스트레이터
├── 탐색자: 변경 대상 전수 조사 + 의존성 그래프
├── 구현자: 탐색자 보고서 기반 코드 수정
└── 검증자: 전체 테스트 + 타입체크 + 린트
가장 기본적인 패턴. 위에서 실습한 그대로다.
패턴 B: 신규 기능 추가
오케스트레이터
├── 설계자: 기존 코드 구조 파악 + 새 기능 설계 초안
├── 구현자: 설계 초안 기반 코드 작성
└── 검증자: 테스트 + 기존 기능 회귀 확인
탐색자 대신 ‘설계자’를 두는 변형. 설계자는 기존 코드의 패턴을 학습해서 “새 기능을 어떤 구조로 넣어야 기존 코드와 일관되는가”를 판단한다.
패턴 C: 코드 리뷰 자동화
오케스트레이터
├── 보안 검토자: OWASP Top 10 관점 검토
├── 성능 검토자: N+1 쿼리, 불필요한 루프 등
└── 스타일 검토자: 프로젝트 컨벤션 준수 여부
리뷰 관점을 에이전트별로 분리하면 각 관점이 서로 간섭하지 않아 리뷰 품질이 올라간다. 사람 리뷰어도 “보안은 김 선임, 성능은 박 선임”으로 나누는 게 효과적인 것과 같다.
패턴 D: 멀티 리포지토리 변경 (베타)
오케스트레이터
├── API 서버 에이전트: 응답 스키마 수정
├── 프론트엔드 에이전트: 타입 정의 동기화
└── 통합 테스트 에이전트: 픽스처 갱신 + 전체 테스트
각 에이전트가 다른 저장소를 담당한다. 오케스트레이터가 API 변경 사항을 프론트엔드 에이전트에게 전달하는 식으로 정보가 흐른다. 아직 베타이므로 프로덕션보다는 개인 프로젝트에서 먼저 시도해보길 권한다.
실무 팁 — 서브에이전트를 더 잘 쓰는 5가지
1. 보고서를 짧게 유지하라
탐색자가 100줄짜리 보고서를 쓰면 구현자가 그걸 해석하느라 토큰을 낭비한다. “수정 대상 파일 목록 + 각 파일에서 고쳐야 할 한 줄 설명” 정도면 충분하다. 긴 분석은 탐색자 내부에서 소화하고, 부모에게는 결론만 올린다.
2. 검증자에게는 명확한 합격 기준을 줘라
“코드가 좋아 보이면 합격”은 기준이 아니다. “pytest 전체 통과 + mypy –strict 에러 0 + 변경 파일에서 새로운 TODO 없음”처럼 기계적으로 판단 가능한 기준을 준다.
3. 오케스트레이터의 개입을 설계하라
서브에이전트에게 다 맡기고 끝까지 기다리는 게 항상 정답은 아니다. 탐색자 보고서를 받은 시점에서 오케스트레이터(또는 사용자)가 방향을 확인하고, 맞으면 구현으로 넘기는 게 더 안전하다. Claude Code에서는 탐색자가 끝나면 메인 에이전트가 “이 보고서가 맞는지 확인하겠습니다”라고 중간 보고를 할 수 있다.
4. 실패 경로를 미리 정의하라
검증자가 불합격 판정을 내리면 어떻게 할 것인가? 이걸 지시에 미리 넣어두지 않으면 오케스트레이터가 “다시 처음부터”를 선택해서 비용이 배로 뛴다.
실패 시 행동:
- 검증자 불합격 → 불합격 상세를 구현자에게 전달 → 구현자가 재수정 (1회만)
- 2차 검증도 불합격 → 전체 보고서를 사용자에게 반환하고 멈춤
5. 단순한 작업에는 쓰지 마라
반복하지만 중요하다. 함수 하나 리네이밍하는 데 서브에이전트 3개를 띄우면 회의 시간이 코딩 시간을 넘는다. “이 작업에 사람 팀원이 3명 필요한가?”를 자문하라. 아니라면 서브에이전트도 필요 없다.
이번 회차의 수익화 지점
서브에이전트 패턴은 팀 단위의 표준 워크플로를 설계해서 판매할 수 있는 형태다. “버그 수정 3역할 템플릿”, “코드 리뷰 3관점 자동화 설정”, “멀티 리포 변경 오케스트레이션 가이드” 같은 것들이다. 9화에서 만든 Skills에 서브에이전트 역할 정의를 포함시키면 복붙 한 번으로 팀 전체가 같은 구조로 작업하게 만들 수 있다. 규제가 강한 환경이나 감사 이력이 필요한 조직은 이런 표준 워크플로에 기꺼이 비용을 지불한다. “탐색-구현-검증이 분리되어 있고, 각 단계의 권한과 산출물이 명확하다”는 것 자체가 컴플라이언스 근거가 되기 때문이다. 컨설팅이든 템플릿 판매든, 핵심은 역할 정의와 보고 형식의 표준화에 있다.
다음 12화에서는 9~11화에서 만든 Skills, MCP 서버, 서브에이전트 패턴을 하나의 플러그인으로 묶어서 배포 가능한 형태로 패키징하는 방법을 다룬다. 만든 것을 쓰는 단계에서 파는 단계로 넘어간다.
← 10화: MCP 서버 실전 가이드 ｜ 12화: 플러그인 패키징 — 만든 걸 파는 형태로 →
관련 회차: 7화: 컨텍스트 관리 5단계 ｜ 9화: Claude Skills 3단계
◀ 이전 10화 (다음 차수는 아직 게시되지 않았습니다)
자주 묻는 질문
Claude 서브에이전트란 무엇이고 왜 필요한가요?
서브에이전트는 메인 에이전트가 별도의 컨텍스트 창을 가진 하위 에이전트를 생성하는 기능으로, Claude Code에서는 내부적으로 “Task tool”이라 부릅니다. 하나의 에이전트가 탐색·구현·검증을 동시에 처리하면 컨텍스트 오염이 발생하는데, 서브에이전트로 역할을 분리하면 각 에이전트가 격리된 컨텍스트에서 작업하므로 대규모 작업도 안정적으로 수행할 수 있습니다.
Claude 서브에이전트 3단계 중첩은 어떻게 작동하나요?
2026년 6월 업데이트로 서브에이전트가 기존 1단계에서 3단계까지 중첩 가능해졌습니다. Level 0 오케스트레이터(메인 에이전트) 아래에 Level 1 에이전트(탐색, 구현 등)를 두고, 각 Level 1 에이전트가 다시 Level 2 에이전트(API 스캐너, 도메인 스캐너 등)를 생성하는 부장·과장·사원 구조로 동작합니다.
Claude 서브에이전트를 쓸 때 비용 관리는 어떻게 해야 하나요?
에이전트 하나가 곧 하나의 컨텍스트이고, 컨텍스트 하나가 곧 비용입니다. 비용 상한 없이 서브에이전트를 사용하면 하루 만에 월 예산이 증발할 수 있으므로, 반드시 비용 상한을 설정하고 사용해야 합니다.
