Claude Code 서브에이전트 패턴 — Task tool로 역할 분담하기
Explorer/Plan/Reviewer 등 역할별 서브에이전트를 띄워 부모 세션의 컨텍스트를 보호하고 병렬 처리 속도를 올리는 실전 패턴.
Claude Code의 강점 중 가장 늦게 활용되는 게 서브에이전트(Task tool)다. 한 세션에서 모든 일을 직접 하면 부모 컨텍스트가 빠르게 가득 차고, 큰 작업은 단일 thread에 묶여 느려진다. 서브에이전트를 한 단계 위 추상으로 두면 — Explorer는 코드를 뒤져 핵심만 보고, Reviewer는 변경된 diff만 본다 — 같은 시간 안에 두 배 더 많은 일을 다룰 수 있다.
이 가이드는 Claude Code 1.x 기준. Claude Code 셋업 + hooks 이후 매일 쓰는 워크플로를 한 단계 위로 끌어올린다.
TL;DR
- 부모 에이전트가 직접 코드 변경 + 빌드/테스트 — 짧고 빠른 작업
- Explorer 서브에이전트 — "이 코드베이스에서 X 어디?" 검색·요약. 큰 결과를 부모에 가져오지 않음
- Plan 서브에이전트 — 큰 변경의 step-by-step plan만 받아옴
- Reviewer 서브에이전트 — 부모가 만든 diff를 second opinion으로 검토
- Specialist — claude-api·security-review 같은 도메인 전용 에이전트
핵심 원칙 — 컨텍스트 보호 + 병렬화.
사전 조건
- Claude Code 1.x 설치 — Claude Code 셋업
- 프로젝트에
CLAUDE.md+.claude/settings.json기본 셋업 - (선택) hooks 베이스라인 — 서브에이전트도 부모의 hooks 일부 적용
1. Task tool 호출 모델
Claude Code 안에서 Task 도구는 새로운 에이전트를 띄우고 단일 prompt를 전달한다. 서브에이전트는 자체 컨텍스트 윈도우를 가진다 — 부모와 메시지를 공유하지 않고, return된 결과 메시지 한 번만 부모로 돌아온다.
부모 에이전트
│
├─ Task("Explore", "src/auth/ 폴더에서 토큰 검증 로직 찾아 함수명+파일 위치만 반환")
│ ↓ (별도 컨텍스트, 100k 토큰까지 자유 사용)
│ ↑ "validateToken: src/auth/verify.ts:42" ← 부모는 결과만 받음
│
└─ Task("Reviewer", "마지막 commit의 diff에 보안 이슈 있는지 검토")
↓
↑ "1건 발견: src/api/user.ts:88 — SQL injection 가능성"
부모 컨텍스트에 추가되는 건 최종 요약 1개. 서브에이전트가 200개 파일을 읽었어도 부모는 1줄짜리 결과만 받는다.
2. 핵심 패턴 4종
2.1 Explorer — 큰 검색 결과의 컨텍스트 격리
가장 자주 쓰는 패턴. "어디서 무엇이 정의돼 있나?" 류의 작업을 서브에이전트에 위임.
"Explorer 서브에이전트에 위임:
'src/ 트리에서 useAuth 훅 정의 + 사용처 모두 찾아라. 결과는
- 정의 파일:line
- 사용처 파일:line × 모두
형태로 30줄 미만 요약. 코드 본문은 가져오지 마라.'"
부모는 30줄 요약만 받음. 직접 했으면 grep + 다수 파일 read로 5-20k 토큰 소비.
언제 사용:
- 새 코드베이스에 진입한 직후
- "이 기능 어디 있지?" 검색
- "이 라이브러리 우리가 어떻게 쓰고 있지?"
- 의존성 영향 분석
안 좋은 사용:
- 작은 검색 — 부모가 grep 한 줄로 끝낼 수 있는 일
- 결과 바로 사용하는 작업 — 부모가 직접 보는 게 빠름
2.2 Plan — 큰 변경의 step-by-step만
5+ 파일 변경, 새 모듈, 아키텍처 변경 시 — Plan 서브에이전트가 자료조사·트레이드오프 분석 후 step-by-step plan만 반환.
"Plan 서브에이전트에 위임:
'다음 작업의 step-by-step 실행 계획만 받아라.
요구사항: 카테고리당 평균 7편 → 10편으로 시드 확장.
제약: 빌드 시간 1분 미만, verify:assets 100% 통과.
출력: 카테고리·주제·자산 여부·예상 분량 표 + 작성 순서.
실제 코드 작성은 하지 마라.'"
부모는 plan만 받고, 실제 작성은 부모가 직접 또는 다른 서브에이전트에 분배.
2.3 Reviewer — Second opinion
부모가 만든 diff를 다른 컨텍스트의 에이전트가 검토. 익숙해진 부모가 놓치는 것을 신선한 눈으로 잡는다.
"Reviewer 서브에이전트에 위임:
'직전 commit 4d2f0의 diff를 보안 관점에서 검토.
구체적: SQL injection, XSS, hardcoded secret, race condition.
출력: 발견 N건 + 각 파일:line + 1줄 설명. 없으면 "clean".'"
부모가 직접 검토하면 본인 코드에 익숙해서 놓치는 경우 많음. Reviewer는 같은 prompt 보고도 다른 시각에서 검토.
2.4 Specialist — 도메인 전용
특정 영역(claude-api, security-review, code-reviewer, build-validator 등) 전용 서브에이전트. 도메인 지식이 풍부하고 출력 형식도 그 영역에 맞춰져 있다.
"security-review 서브에이전트에 위임:
'현재 브랜치의 전체 변경 사항을 security 관점에서 종합 평가.
범위: 인증·인가·입력 검증·시크릿·세션·CSRF.'"
전용 에이전트는 보통 system prompt가 그 영역에 튜닝돼 있어 결과 품질 ↑.
3. 위임 prompt 작성법
서브에이전트는 부모의 컨텍스트를 모른다. prompt가 self-contained 여야 한다.
좋은 prompt
"src/ 트리에서 다음 패턴을 찾는 작업:
- `fetch(...)` 호출 중 baseURL이 hardcoded된 곳
- 결과: 파일:line + 코드 1줄 + 추정 baseURL 도메인
- 30개까지만, 더 있으면 '+N more'
- 코드 본문은 첨부하지 말고 line만"
나쁜 prompt
"아까 그 fetch 검토 해줘" ← 컨텍스트 없음, 막연함
"fetch 호출 다 찾아" ← 결과 형식 미정, 큰 출력 가능성
작성 체크리스트
- 목적 — 무엇을 알고 싶은지
- 범위 — 어디에서 (디렉토리/파일/기간)
- 출력 형식 — 표·줄 단위·요약 분량
- 제외 — 어떤 출력은 가져오지 말지 (코드 본문, 큰 diff 등)
- 종료 조건 — 발견 N건 + 더는 안 보고 끝
- 알 수 없는 경우 — "모르면 모른다고 답해, 추측 금지"
4. 병렬 실행 — 독립적인 위임은 한 번에
서로 의존이 없는 작업은 하나의 응답에서 여러 Task 호출. Claude Code는 병렬로 띄움.
"세 가지 위임을 동시에:
1) Explorer — auth 관련 파일 위치 요약
2) Explorer — db 마이그레이션 history 요약
3) Reviewer — 최근 5 commits 보안 검토
각각 결과 받은 후 통합 분석."
부모는 세 결과를 동시에 받음. 시간 1/3.
병렬 금지:
- A의 결과가 B의 입력 — 순차 실행
- 같은 파일을 동시 편집하는 작업 — race 위험
5. 컨텍스트 관리 — 위임 vs 직접
| 신호 | 위임 | 직접 |
|---|---|---|
| 결과를 1~2줄 요약으로 받을 수 있음 | ✅ | — |
| 코드 본문을 그대로 부모로 가져와야 함 | — | ✅ |
| 100+ 파일 검색 | ✅ | — |
| 1~2개 grep | — | ✅ |
| 결과 바로 다음 step에서 사용 | — | ✅ (위임 후 받기 < 직접) |
| 다른 시각이 필요 | ✅ (Reviewer) | — |
| 도메인 전용 지식 | ✅ (Specialist) | — |
엄지손가락 규칙: 부모 컨텍스트의 20%를 차지할 작업이면 위임 검토.
6. 실전 시나리오
A. 새 코드베이스 진입
1. Explorer — 폴더 구조 + 핵심 모듈 5개 요약
2. Explorer — README + CLAUDE.md(있다면) 핵심 메시지 추출
3. Explorer — 최근 10 commits 요약
↓
4. 부모 — 위 3종 결과 통합해서 "이 repo의 컨텍스트 한 단락" 생성
B. 5+ 파일 변경
1. Plan — 변경 범위 + 단계 + risk 표
2. 부모 — Plan 검토 후 step별 진행
3. 각 step 완료 후 Reviewer — diff 검토
4. 최종 commit 전 Reviewer — 전체 변경 second opinion
C. 디버깅
1. 부모 — 에러 로그 + 재현 경로 정의
2. Explorer — 관련 코드 path 추적 (스택 트레이스 기반)
3. 부모 — 가설 수립 + 수정 시도
4. 부모 — 빌드/테스트 검증
D. PR 머지 직전
1. Reviewer — diff 보안·성능 검토
2. Reviewer — 기존 코드 컨벤션과의 일관성
3. Specialist (security-review) — 종합 평가
4. 부모 — 발견 사항 정리 후 PR 코멘트 또는 추가 수정
7. hooks와 결합
Claude Code hooks의 PreToolUse로 Task 호출도 가로챌 수 있다.
{
"hooks": {
"PreToolUse": [
{
"matcher": "Task",
"hooks": [
{
"type": "command",
"command": "/bin/bash -lc 'echo \"[delegate] $(jq -r .tool_input.description)\" >> ~/.claude/delegate.log'"
}
]
}
]
}
}위임 횟수·내용을 로그로 남기면 어떤 작업을 위임 vs 직접 했는지 검토 가능. 비용 추적·패턴 학습에 활용.
8. 안티패턴 — 위임 잘못 쓰는 경우
8.1 모든 작업을 서브에이전트로
"파일 1개 수정도 위임" ← 오버헤드만 ↑
서브에이전트 호출 자체에 토큰·시간 비용이 있다. 부모가 직접 1초 작업을 30초 위임으로 변환하는 건 손해.
8.2 위임 후 또 부모가 직접 검색
"Explorer가 auth 코드 위치 요약 → 부모가 같은 파일들을 다시 grep으로 확인"
→ 위임의 의미 없음. 결과를 신뢰하고 다음 step으로.
8.3 너무 자세한 출력 요청
"각 파일의 전체 코드 + 5줄 설명 + 사용처 본문 모두 가져와"
→ 부모 컨텍스트가 위임으로도 줄지 않음. 요약 분량 제약을 prompt에 명시.
8.4 의존성 있는 작업을 병렬 위임
"A 결과 받고 B에 그 정보 넣어야 하는데 둘 다 동시 위임"
→ B는 A의 결과를 모름. 잘못된 가정으로 진행. 순차 실행이 정답.
9. 분담 매트릭스 — 누가 무엇을
| 작업 | 부모 (Main agent) | Explorer | Plan | Reviewer | Specialist |
|---|---|---|---|---|---|
| 작은 grep | ✅ | — | — | — | — |
| 코드 변경 | ✅ | — | — | — | — |
| 빌드·테스트 | ✅ | — | — | — | — |
| 큰 검색 | — | ✅ | — | — | — |
| 큰 변경 계획 | — | — | ✅ | — | — |
| diff 검토 | (작은 변경만) | — | — | ✅ | ✅ (security) |
| 보안 종합 | — | — | — | — | ✅ (security-review) |
| 도메인 API 사용법 | — | — | — | — | ✅ (claude-api 등) |
다음 단계
- Claude Code 셋업 — 부모 에이전트 본체
- Claude Code hooks — 위임 로깅·검증
- Multi-agent 워크플로 — 여러 도구·에이전트 통합 시나리오
- Agent runner — 자율 실행 + 서브에이전트 조합
참고 링크
변경 이력
- 2026-05-12 — 초안 (devAlice M3 시드 확장)