Claude Code 멀티에이전트 실전 — 서브에이전트 병렬화로 반복 작업 시간을 압축하는 법
이 글은 Claude Code의 병렬 실행 구조를 직접 다루는 개발자·파워유저를 대상으로 한다. 서브에이전트가 무엇인지, 스킬·MCP·워크플로우와 어떻게 역할을 나누는지, 그리고 fan-out, 파이프라인, 검증 루프 같은 실전 패턴을 언제 어떻게 쓰면 되는지를 여기서 정리한다.
Claude Code 멀티에이전트 병렬화 구조를 요약한 AI 생성 대표 이미지.
서브에이전트·스킬·MCP·워크플로우는 각각 무슨 역할인가?
Claude Code의 확장 구조는 4개 레이어로 나뉜다. 각각이 담당하는 범위가 다르므로 혼용하면 설계가 꼬인다.
| 레이어 | 정의 | 주 용도 | 적재 위치 |
|---|---|---|---|
| 서브에이전트 | 독립 컨텍스트·권한을 가진 별도 Claude 세션 | 병렬 실행, 역할 분리 | 오케스트레이터가 런타임에 생성 |
| 스킬(Skill) | 마크다운 기반 지시 묶음 (.claude/skills/) | 재사용 가능한 절차 정의 | 프로젝트 또는 글로벌 설정 |
| MCP 서버 | 외부 도구·데이터소스를 노출하는 실행 프로세스 | DB, 이슈 트래커, 브라우저 자동화 연동 | settings.json mcpServers |
| 워크플로우 | 서브에이전트를 조율하는 JS 오케스트레이션 스크립트 | 동적 fan-out, 대규모 병렬 처리 | Dynamic Workflows 런타임(연구 미리보기) |
스킬은 절차를 재사용 가능하게 묶는 가장 단순한 확장이고, MCP는 외부 시스템에 연결하는 인터페이스다. 서브에이전트는 실제로 병렬 실행을 만들어내는 단위이며, 워크플로우는 그 서브에이전트들을 동적으로 조율하는 상위 레이어다.
단일 에이전트 vs 서브에이전트 병렬화 — 어느 쪽을 택해야 하는가?
모든 작업을 병렬화하는 것은 오히려 비용만 높인다. 판단 기준은 단순하다.
- 작업 순서가 엄격하게 종속된 경우 (A 완료 후 B 시작)
- 총 작업량이 소규모 (파일 3개 이하, 컨텍스트 여유 있음)
- 상태를 공유해야 하는 단일 데이터 흐름
- 입력 항목이 독립적인 배치 (파일 N개, URL N개, 모듈 N개)
- 역할이 명확하게 분리되는 경우 (작성 / 검토 / 테스트)
- 각 서브태스크가 실패해도 전체가 멈추면 안 되는 경우
- 순차 처리 시 대기 시간이 병목인 경우
실측 경험에 따르면 파일 8개를 단일 에이전트가 순차로 읽는 대신 4개 서브에이전트가 2개씩 병렬로 처리하면 컨텍스트 노이즈도 줄고 대기 시간도 절반 안팎으로 단축된다. 단, 동시도가 높아질수록 사용량 한도 소진 속도도 빨라지므로 무작정 높이는 것은 권하지 않는다.
실전 패턴 4가지 — fan-out, 파이프라인, 판정 패널, 검증 루프
아래 패턴들은 Claude Code 공식 문서 및 Dynamic Workflows 발표 사례를 기반으로 일반화한 것이다. 특정 도메인에 묶이지 않고 어떤 반복·병렬 작업에도 적용 가능하다.
패턴 1. Fan-out (분산-수집)
오케스트레이터가 N개 입력을 N개 서브에이전트에 각각 할당하고, 완료 후 결과를 수집·통합한다. 가장 기본적인 패턴이며 배치 처리, 다중 소스 조사, 파일 단위 변환에 적합하다.
# 개념적 구조 (의사코드)
items = ['A', 'B', 'C', 'D']
# 서브에이전트 병렬 실행
results = parallel([
agent(task='process', input=item)
for item in items
])
# 오케스트레이터가 결과 통합
summary = synthesize(results)패턴 2. 파이프라인 (Pipeline)
항목 스트림이 여러 처리 단계를 거치되, 각 단계 내에서는 병렬 실행된다. 단계 간 장벽(barrier)이 없어 처리량이 높다. 대량 콘텐츠 생성·변환 시 유용하다.
# stage 1: 수집 (병렬)
raw = parallel([agent(task='fetch', source=s) for s in sources])
# stage 2: 정제 (병렬, stage 1 완료 불필요)
processed = pipeline(raw, transform=agent_clean)
# stage 3: 발행 (병렬)
outputs = pipeline(processed, transform=agent_publish)패턴 3. 판정 패널 (Judge Panel)
동일 입력을 복수 서브에이전트가 독립적으로 분석한 후, 별도 심사 에이전트가 결과를 비교해 최종 판정을 낸다. 중요한 결정이나 코드 리뷰, 보안 검토 등에 적합하다.
opinions = parallel([
agent(task='analyze', perspective='security', input=code),
agent(task='analyze', perspective='performance', input=code),
agent(task='analyze', perspective='correctness', input=code),
])
verdict = agent(task='judge', inputs=opinions)패턴 4. 검증 루프 (Verification Loop)
결과를 생성하는 에이전트와 그 결과를 반박하는 에이전트를 교대로 실행한다. 2026년 5월 공개된 Dynamic Workflows의 /deep-research 커맨드가 이 구조를 내장하고 있다 — 주장을 생성하는 서브에이전트와 주장을 논박하는 서브에이전트가 수렴할 때까지 반복하며, 살아남은 주장만 최종 출력에 포함된다.
claim = agent(task='generate_claim', input=topic)
while not converged:
rebuttal = agent(task='refute', claim=claim)
if rebuttal.accepted:
claim = agent(task='revise', claim=claim, rebuttal=rebuttal)
else:
converged = True
final_output = claim비용·품질 트레이드오프 — 모델 선택과 동시도 상한은 어떻게 정하는가?
병렬화는 처리 시간을 줄이지만 사용량 소진 속도를 높인다. 모델 선택이 비용·품질의 핵심 변수다.
| 모델 | 권장 용도 | 특이사항 |
|---|---|---|
| Claude Opus | 계획 수립, 아키텍처 결정, 어려운 디버깅 | 한도 소진이 빠름, 병렬 서브에이전트에 남발 금지 |
| Claude Sonnet | 대부분의 코딩·리팩터링·테스트 작성 | Opus 대비 2배 빠름, 비용 절감 여지 큼 |
| Claude Haiku | 보일러플레이트, 단순 변환, 짧은 분류 작업 | 컨텍스트 짧고 기계적인 서브에이전트에 적합 |
현재(2026-05) 서브에이전트 모델 라우팅에 알려진 이슈가 있다 — 문서상 별도 모델을 지정해도 부모 세션 모델을 상속하는 경우가 보고된다. 실제 라우팅 동작은 사용 중인 버전에서 직접 확인해야 한다.
동시도 상한에 대해서는 실전 경험에서 도출한 실용 기준이 있다. 기본값은 동시 2개로 시작하고, 검증 후 필요하면 최대 3~4개까지 늘린다. Dynamic Workflows는 공식적으로 동시 16개, 총 1,000개까지 허용하지만, 그 규모는 오케스트레이터가 스크립트를 작성해 관리하는 경우에 해당한다. 사람이 직접 설계하는 수동 구성에서 동시 8개 이상은 상태 추적과 비용 통제 모두 어렵다.
병렬 에이전트에서 환각·오류를 어떻게 줄이는가?
서브에이전트를 늘릴수록 각 에이전트의 출력 품질 관리가 필요해진다. 실전에서 효과적인 3가지 원칙이 있다.
1. 서브에이전트 범위를 좁게 정의한다. 하나의 서브에이전트가 한 가지 명확한 작업만 수행하도록 제약하면 오류 발생 범위가 줄고 디버깅이 쉬워진다. '분석 에이전트'와 '작성 에이전트'를 분리하는 것만으로도 품질이 달라진다.
2. 검증 루프를 반드시 넣는다. 생성 에이전트의 출력을 그대로 최종 결과로 쓰지 않는다. 검증 에이전트가 별도로 사실 확인, 코드 실행, 로직 반박을 수행하게 한다. Dynamic Workflows의 /deep-research가 이 패턴을 내장하고 있다.
3. 오케스트레이터에게 수렴 조건을 명시한다. "결과가 일치할 때까지 반복"이 아니라 "최대 N회 반복 후 불일치 시 보고"처럼 종료 조건을 구체적으로 명시하지 않으면 루프가 비용을 무제한 소모하거나 조기 종료할 수 있다.
FAQ — Claude Code 멀티에이전트 자주 묻는 질문 5가지
참고 자료
이 글에서 다룬 기능의 공식 문서와 추가 레퍼런스다.
- Claude Code 공식 문서 — Anthropic
- Claude Code 에이전트 팀 구성 가이드
- Claude Code 서브에이전트 생성 공식 문서
- Dynamic Workflows 공식 문서
- Dynamic Workflows 발표 블로그 — Anthropic (2026-05-28)
- Obsidian — 마크다운 기반 로컬 노트 앱
- 서브에이전트는 독립 컨텍스트로 병렬 실행하는 단위다. 스킬은 절차, MCP는 외부 연동, 워크플로우는 동적 조율을 담당한다.
- fan-out / 파이프라인 / 판정 패널 / 검증 루프 — 4가지 패턴이 대부분의 반복 작업을 커버한다.
- 비용은 모델 선택(Sonnet 우선, Opus는 계획에만)과 동시도 상한(기본 2~3)으로 통제한다.
다음 글 예고: Claude Code MCP 서버 설정 실전 — 로컬 DB·이슈 트래커·브라우저 자동화를 한 번에 연결하는 법을 다룰 예정이다.
도구 기능은 업데이트가 잦아 공식 문서 재확인을 권한다.
댓글
댓글 쓰기