오늘만 무료

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

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

by AI개발자

4시간전 brunch_membership's

서브에이전트란 무엇인가

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)의 컨텍스트를 가볍게 유지하는 것입니다.

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

## Orchestrator 규칙 (Thin Orchestrator 원칙)

- 파일 내용을 자신의 컨텍스트에 직접 읽어들이지 않는다
- 파일 경로와 구조만 파악하고, 내용 조사는 서브에이전트에 위임한다
- 컨텍스트 사용률을 50% 이하로 유지하는 것을 목표로 한다
- 자신은 실제 코딩·문서 작성·데이터 분석을 하지 않는다
- 서브에이전트로부터는 결과 요약만 받는다. 전체 파일 내용은 받지 않는다

서브에이전트 위임 포맷

서브에이전트에 태스크를 전달할 때는, 다음 4가지 정보를 반드시 포함합니다.

## 서브에이전트 위임 포맷

태스크를 서브에이전트에게 위임할 때는 다음 정보를 전달한다:

1. **목적** — 무엇을 달성하는가 (1문장으로)
2. **참조 파일** — 필요한 입력 파일의 경로 목록 (내용은 서브에이전트가 직접 읽는다)
3. **출력 형식** — 결과를 어떤 형식으로 반환하는가 (요약/파일 경로/체크리스트 등)
4. **제약** — 금지 사항, 품질 기준, 변경 허용 범위

위임 예시

# 나쁜 위임 예 (정보 부족)
"인증 기능을 구현해줘"

# 좋은 위임 예 (명확한 지시)
목적: NextAuth.js v5를 사용한 카카오 소셜 로그인 구현
참조 파일:
- src/app/api/auth/[...nextauth]/route.ts (기존 파일)
- docs/kakao-oauth.md (카카오 OAuth 사양)
출력 형식:
- 구현한 파일 경로 목록
- 테스트 통과 여부
- 남은 작업 (완료하지 못한 부분)
제약:
- 기존 NextAuth 설정을 삭제하지 않는다
- 환경변수는 .env.local에 추가 (코드에 하드코딩 금지)
- 카카오 API 키를 로그에 출력하지 않는다

실전: 대규모 기능 구현 패턴

예: 카카오 로그인 + 결제 기능 동시 구현

## 대규모 기능 병렬 구현 절차
1. 서브에이전트(리서치)로 코드베이스 조사:
- 기존 인증 관련 코드 구조
- 현재 사용 중인 DB 스키마 (users 테이블 확인)
- 토스페이먼츠 연동 코드 유무

2. 조사 결과를 바탕으로 구현 계획 수립 및 팀 확인

3. 독립된 부분을 서브에이전트로 병렬 구현:
- 에이전트 A: DB 스키마 변경 + 마이그레이션 (users 테이블에 kakao_id 추가)
- 에이전트 B: NextAuth 카카오 프로바이더 설정
- 에이전트 C: 토스페이먼츠 결제 모듈 (features/payment/)

4. 에이전트 A 완료 후, 에이전트 B·C 결과와 통합

5. 서브에이전트(테스트)로 통합 테스트 실행:
- 로그인 플로우 E2E 테스트
- 결제 플로우 단위 테스트

6. 서브에이전트(리뷰)로 최종 코드 리뷰:
- 보안 체크 (인증 토큰 누출, 결제 금액 클라이언트 계산 등)
- 개인정보 처리 규약 준수 여부

팀 구성 패턴

프로젝트의 성질에 맞게 에이전트 구성을 조정합니다.

웹 서비스 개발팀 (국내 서비스)

## 에이전트 구성

- **Orchestrator**: 태스크 관리, 결과 통합, PR 생성
- **Frontend Agent**: Next.js 컴포넌트, Tailwind 스타일링
- **Backend Agent**: Fastify API, Prisma DB 조작
- **Payment Agent**: 토스페이먼츠·카카오페이·네이버페이 연동 전담
- **Test Agent**: Vitest 단위 테스트, Playwright E2E 테스트

Payment Agent를 별도로 두는 이유:
결제 코드는 보안 요구사항이 높고, 국내 PG사별 API가 달라 전문화가 필요합니다.
실수가 발생하면 금전적 피해로 이어지므로, 전담 에이전트가 집중적으로 검증합니다.

데이터 처리 파이프라인

## 에이전트 구성

- **Orchestrator**: 파이프라인 전체 관리, 진행 상황 모니터링
- **ETL Agent**: 데이터 추출·변환·로드 (외부 API, DB)
- **Validation Agent**: 데이터 품질 체크, 이상값 탐지
- **Report Agent**: 결과 리포트 생성 (Slack 알림 포함)

기술 문서 자동 생성

## 에이전트 구성

- **Orchestrator**: 문서 전체 구성 관리
- **Research Agent**: 코드베이스 조사, API 스펙 추출, 타입 정의 분석
- **Writer Agent**: 한국어 기술 문서 작성 (README, API 문서)
- **Review Agent**: 교정, 일관성 체크, 예시 코드 동작 확인

주의 사항

컨텍스트의 독립성

서브에이전트는 메인의 대화 이력을 알지 못합니다. "이전에 논의한 인증 방식"처럼 암묵적인 공유 지식을 전제로 위임하면 서브에이전트가 엉뚱한 결과를 반환합니다. 필요한 정보는 위임 프롬프트에 모두 명시하세요.

비용과 효율

서브에이전트를 기동할 때마다 API 호출이 발생합니다. 3행짜리 수정을 위해 서브에이전트를 쓰는 것은 오히려 비효율입니다. 위임 판단 기준(앞의 태스크 위임 규칙)을 CLAUDE.md에 명시해 두면, Claude Code가 스스로 판단합니다.

파일 변경 충돌

여러 서브에이전트가 동시에 같은 파일을 변경하면 충돌이 발생합니다.

해결책 1: 파일 담당을 사전에 명확히 분리 (에이전트 A는 src/features/auth/, 에이전트 B는 src/features/payment/)

해결책 2: 공유 파일(타입 정의, 상수 등)은 먼저 처리하고, 이후에 의존하는 파일을 병렬 처리

해결책 3: 충돌 가능성이 있는 경우는 순차 실행으로 전환

국내 서비스에서의 개인정보 주의

멀티에이전트 구성에서는 개인정보가 여러 에이전트의 컨텍스트를 오가게 됩니다.

## 멀티에이전트 개인정보 취급 규칙

- 서브에이전트에 전달하는 프롬프트에 실제 사용자 개인정보를 포함시키지 않는다
- DB 조회 결과에 개인정보가 포함된 경우, 메인 에이전트에 반환 전에 마스킹 처리
- 서브에이전트 결과를 로그 파일에 저장할 때는 개인정보 포함 여부를 확인