CLAUDE.md 완전 정복 - 멀티에이전트 완전가이드

Orchestrator 패턴으로 대규모 개발 태스크를 병렬 처리하는 방법

서브에이전트란 무엇인가

Claude Code에는 메인 AI에 더해 "서브에이전트"를 기동하는 기능이 있습니다. 여러 에이전트를 연계함으로써 대규모 태스크를 병렬로 처리하거나, 전문 분야별로 역할을 나눌 수 있습니다.

서브에이전트는 메인 에이전트에서 기동되는 독립된 AI 인스턴스입니다. 메인 에이전트의 컨텍스트(대화 이력)를 소비하지 않고, 특정 태스크를 실행하여 결과만 반환합니다.

서브에이전트가 가진 정보는 기동 시에 전달된 프롬프트뿐입니다. 메인의 대화 이력은 자동으로 공유되지 않습니다. 따라서 서브에이전트에 위임할 때는 필요한 정보를 명시적으로 전달해야 합니다.

CLAUDE.md에서의 서브에이전트 설계

Orchestrator 패턴

하나의 메인 에이전트가 여러 서브에이전트에 지시를 내리는 기본 구성입니다. 메인은 "지휘자"에 철저하고, 실제 코딩이나 조사는 "연주자"인 서브에이전트에 맡깁니다.

## 에이전트 구성

### 메인 에이전트 (Orchestrator)
- 태스크 분해와 위임 담당
- 서브에이전트의 결과를 통합하여 최종 답변 생성
- 자신은 코딩·파일 읽기·조사를 직접 하지 않는다

### 서브에이전트: 코드 리서치
- 코드베이스 조사·검색 담당
- Grep, Glob, Read 툴을 사용
- 결과를 간결한 요약으로 반환 (파일 전체를 반환하지 않는다)

### 서브에이전트: 구현
- 실제 코딩 담당
- Edit, Write, Bash 툴을 사용
- 구현 + 단위 테스트 실행까지 포함

### 서브에이전트: 리뷰
- 구현 결과 리뷰 담당
- 코딩 규약 준수 체크 (4장 코딩 규약 기준)
- 보안 취약점 체크
- 결과를 체크리스트 형식으로 반환

태스크 위임 판단 기준

CLAUDE.md에 "언제 서브에이전트를 쓸지"를 명기해 두면, Claude Code가 상황에 맞게 판단합니다.

## 태스크 위임 규칙

### 서브에이전트를 기동하는 경우
1. **코드베이스 조사**: 3개 이상의 파일을 횡단하여 조사가 필요한 경우
2. **병렬 실행 가능한 독립 태스크**: 테스트 실행 + 린트 + 타입 체크를 동시에 할 경우
3. **대량 코드 생성**: 5개 파일 이상의 신규 생성·변경이 필요한 경우
4. **전문 영역 분리**: 프론트엔드 구현과 백엔드 구현을 독립적으로 진행할 수 있는 경우

### 서브에이전트를 사용하지 않는 경우
1. **단일 파일 수정**: 메인에서 직접 대응
2. **간단한 질문**: 메인에서 직접 답변
3. **의존 관계가 있는 태스크**: A가 끝나야 B를 시작할 수 있는 순서 의존이 있는 경우
4. **소규모 변경**: 추가·수정이 3행 이내인 경우

Thin Orchestrator의 원칙

멀티에이전트 구성에서 가장 중요한 원칙은, 메인 에이전트(Orchestrator)의 컨텍스트를 가볍게 유지하는 것입니다.

메인 에이전트가 모든 파일을 직접 읽어들이면 컨텍스트 윈도우가 빠르게 소진되어, 장시간 작업을 이어갈 수 없게 됩니다.