테마
13. Claude Code 멀티 에이전트
멀티 에이전트는 AI를 많이 켜는 것이 아니라 역할이 분리된 여러 작업자를 하나의 흐름으로 운영하는 방식이다. Claude Code에서는 Sub Agent, Skill, MCP, Hook, 설정 파일을 조합해 리서치, 작성, 검증, 변환, 배포 같은 일을 나눠 맡길 수 있다.
이 장은 08장에서 배운 단일 서브에이전트와 10장에서 배운 Skill을 바탕으로, 여러 에이전트를 어떻게 설계하고 연결해야 하는지 정리한다.
참고로 Claude Code에는 여러 세션이 협업하며 메시지를 주고받는 별도 기능인 agent teams도 있다. 다만 이 기능은 experimental이며 기본 비활성화 상태라 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS로 활성화해야 한다. 이 장은 우선 단일 Claude Code 세션 안에서 여러 Sub Agent와 Skill을 조합하는 패턴에 집중한다.
1. 왜 멀티 에이전트가 필요한가
단일 에이전트는 편하지만 모든 일을 한 번에 맡기면 문제가 생긴다. 리서치, 기획, 글쓰기, 디자인, 검증을 한 컨텍스트에서 모두 처리하면 정보가 섞이고, 중간 판단이 흐려지며, 비용도 커진다.
| 구분 | 단일 에이전트 | 멀티 에이전트 |
|---|---|---|
| 작업 방식 | 한 대화에서 순차 처리 | 역할별 에이전트가 분담 |
| 컨텍스트 | 하나의 컨텍스트에 모든 정보가 쌓임 | 역할별 독립 컨텍스트 사용 |
| 속도 | 의존 작업이 길어질수록 느림 | 독립 작업은 병렬 처리 가능 |
| 품질 | 한 모델이 모든 관점을 담당 | 리서처, 작성자, 검토자 관점 분리 |
| 리스크 | 과구현, 맥락 오염, 검증 누락 | 핸드오프 실패, 비용 증가, 조정 복잡성 |
멀티 에이전트의 핵심은 사람의 역할이 "작업자"에서 지휘자로 바뀐다는 점이다. 사람은 모든 산출물을 직접 만들기보다, 어떤 일을 어떤 에이전트에게 맡기고 어디에서 승인할지 설계한다.
2. 앞 장들과의 역할 분리
멀티 에이전트는 앞 장의 내용을 다시 설명하는 장이 아니다. 각 장의 관심사는 다르다.
| 장 | 관심사 | 이 장에서 확장하는 지점 |
|---|---|---|
| 08. 서브에이전트 & 훅 | 단일 서브에이전트의 정의, 생성, 호출 | 여러 서브에이전트를 연결하는 운영 패턴 |
| 10. Claude Skill | 반복 절차와 참고 문서의 점진적 로딩 | 에이전트가 필요한 Skill을 선택해 쓰는 구조 |
| 12. 클로드 하네스 구축 | 규칙, 절차, 검증, CI를 묶는 제어 체계 | 하네스 안에 에이전트 팀을 배치하는 방법 |
따라서 이 장의 기준은 "에이전트 파일을 어떻게 하나 만들까"가 아니라 작업을 어떤 단위로 나누고, 어떤 순서와 권한으로 연결할까다.
3. 멀티 에이전트 설계 원칙
좋은 에이전트 팀은 조직도처럼 보인다. 각 에이전트가 맡은 일이 분명하고, 다른 에이전트의 일을 침범하지 않는다.
| 원칙 | 설명 |
|---|---|
| 단일 책임 | 한 에이전트는 한 가지 역할에 집중한다 |
| 독립 컨텍스트 | 서로 다른 관점의 조사는 별도 컨텍스트에서 수행한다 |
| 명확한 핸드오프 | 결과물을 파일, 표, JSON 등 명확한 형식으로 넘긴다 |
| 최소 권한 | 읽기만 필요한 에이전트에게 쓰기 권한을 주지 않는다 |
| 출력 계약 | 최종 산출물 형식과 검증 기준을 미리 정한다 |
| 사람 승인 | 요구사항 확정, 아키텍처 선택, 외부 배포는 사람이 승인한다 |
역할이 겹치면 에이전트가 서로 다른 방향으로 추측한다. 예를 들어 "리서처이면서 카피라이터이면서 디자이너"인 에이전트는 빠르게 보이지만, 조사 근거와 표현 전략과 시각 규칙이 한꺼번에 섞인다. 복잡한 작업일수록 역할을 좁게 나누는 편이 낫다.
4. 대표 오케스트레이션 패턴
멀티 에이전트 구조는 크게 직렬, 병렬, 하이브리드로 나눌 수 있다.
| 패턴 | 적합한 상황 | 예시 | 주의할 점 |
|---|---|---|---|
| 직렬 | 앞 단계 결과가 다음 단계 입력이 되는 경우 | 리서치 → 구조화 → 작성 → 검수 | 앞 단계 품질이 낮으면 뒤 단계가 모두 흔들림 |
| 병렬 | 작업 간 의존성이 낮고 관점이 다른 경우 | 5개 주제 동시 리서치 | 결과 형식이 다르면 수합 비용 증가 |
| 하이브리드 | 큰 흐름은 직렬, 일부 단계는 병렬인 경우 | 기획 후 여러 섹션 이미지 병렬 생성 | 오케스트레이터의 수합 규칙이 필요 |
| 감독자 | 중앙 에이전트가 작업 분배와 검증을 맡는 경우 | Orchestrator-Worker | 감독자가 너무 많은 세부 일을 직접 하면 병목 발생 |
| 네트워크 | 에이전트들이 서로 결과를 주고받는 경우 | 리서처와 리뷰어의 반복 피드백 | 흐름 추적이 어려워질 수 있음 |
처음에는 Orchestrator-Worker 패턴이 가장 다루기 쉽다. 사용자는 목표를 오케스트레이터에게 주고, 오케스트레이터는 작업을 분해해 각 에이전트에게 맡긴다.
여기서 오케스트레이터는 보통 사용자가 대화 중인 메인 Claude Code 세션, 또는 --agent로 메인 세션처럼 실행한 에이전트다. 일반 Sub Agent 안에서 다시 다른 Sub Agent를 중첩 호출하는 구조로 이해하면 안 된다.
5. Sub Agent와 Skill을 섞어 쓴다
Sub Agent와 Skill은 둘 다 Claude Code를 확장하지만 역할이 다르다.
| 항목 | Sub Agent | Skill |
|---|---|---|
| 목적 | 독립 판단과 전문 작업 위임 | 반복 절차, 참고 자료, 실행 playbook 재사용 |
| 컨텍스트 | 메인과 분리된 새 컨텍스트 | 필요할 때 본문을 로드 |
| 비용 | 별도 작업이므로 커질 수 있음 | 사용 시점에만 로드되어 상대적으로 가벼움 |
| 적합한 작업 | 대규모 리서치, 코드 리뷰, 검증, 복잡한 분석 | PPT 변환, 배포 절차, 디자인 규칙, 체크리스트 |
| 실패 유형 | 역할 중복, 권한 과다, 핸드오프 누락 | 너무 자주 호출, 절차가 과도하게 길어짐 |
실전에서는 둘을 섞는다. 예를 들어 PPT 자동화에서는 리서치는 Sub Agent가 맡고, 디자인 규칙과 pptx 변환은 Skill이 맡는 식이다.
판단이 필요한 일은 Sub Agent, 반복 가능한 변환과 절차는 Skill에 맡긴다고 생각하면 된다.
6. 서브에이전트 정의 파일의 핵심
서브에이전트는 Markdown 파일로 정의한다. 사용자 전체에서 쓰려면 ~/.claude/agents/, 프로젝트에 공유하려면 .claude/agents/에 둔다. 최신 Claude Code에서는 /agents 인터페이스로 만들거나 직접 파일을 작성할 수 있다.
markdown
---
name: ai-trend-researcher
description: Use this agent when researching AI trends, market signals, model updates, and industry adoption patterns.
model: sonnet
color: blue
tools: Read, Grep, Glob, Bash
---
You are an AI trend research specialist.
## Responsibilities
- Collect reliable signals about AI model, product, regulation, and industry trends.
- Separate confirmed facts from interpretation.
- Produce structured markdown that another agent can turn into slides or reports.
## Output
Return:
1. Executive summary
2. Key trends
3. Evidence and sources
4. Risks and unknowns
5. Recommended next research questions주요 frontmatter는 다음과 같이 이해하면 된다.
| 필드 | 용도 |
|---|---|
name | 에이전트 식별자. 보통 소문자와 하이픈을 쓴다 |
description | Claude가 언제 이 에이전트에게 위임할지 판단하는 설명 |
model | sonnet, opus, haiku, 전체 모델 ID, 또는 inherit |
tools | 사용할 수 있는 도구 allowlist. 생략하면 기본적으로 상속된다 |
disallowedTools | 상속된 도구 중 금지할 도구 |
skills | 시작 시 미리 로드할 Skill |
memory | 에이전트 기억 범위. user, project, local 중 선택 |
color | 실행 중인 에이전트를 UI에서 구분하기 위한 표시 색상. red, blue, green, yellow, purple, orange, pink, cyan 중 하나를 쓴다 |
모델은 항상 가장 큰 모델이 정답은 아니다. 빠른 분류나 단순 정리는 haiku, 균형 잡힌 분석과 작성은 sonnet, 복잡한 전략 수립과 고품질 원고는 opus처럼 배치할 수 있다. 다만 모델 이름과 사용 가능 여부는 Claude Code 버전과 플랜에 따라 바뀔 수 있으므로 실제 프로젝트에서는 최신 문서를 확인한다.
7. 라우팅 규칙을 CLAUDE.md에 둔다
에이전트가 많아질수록 "누가 무엇을 맡는가"가 더 중요해진다. 이 규칙은 개별 에이전트 파일이 아니라 프로젝트의 CLAUDE.md에 짧게 두는 편이 좋다.
markdown
## Multi-agent routing
- 대규모 리서치는 `ai-trend-researcher`에게 위임한다.
- 리서치 결과를 슬라이드 구조로 바꿀 때는 `slide-structure-planner`를 사용한다.
- 최종 문서 검증은 `output-verifier`에게 맡긴다.
- 외부 배포, 결제, API 키 생성, 권한 상승은 사용자 승인 전까지 실행하지 않는다.
- 각 에이전트는 결과를 `handoff/<agent-name>.md`에 저장하고, 최종 요약만 반환한다.라우팅 규칙이 없으면 Claude가 매번 즉흥적으로 에이전트를 고른다. 작은 프로젝트에서는 괜찮지만, 에이전트가 5개를 넘기면 같은 작업을 다른 에이전트가 반복하거나, 중요한 검증 에이전트가 빠질 수 있다.
8. 병렬 리서치 팀 예시
원문 강의의 대표 예시는 "2026년 AI 트렌드를 5개 병렬 에이전트로 조사하기"다. 이 작업은 병렬 처리에 잘 맞는다. 각 리서치 주제가 서로 독립적이기 때문이다.
| 에이전트 | 조사 범위 | 산출물 |
|---|---|---|
model-researcher | 모델 구조, 추론 성능, 멀티모달 변화 | research/model.md |
business-researcher | 산업 적용, 비즈니스 모델, 도입 사례 | research/business.md |
policy-researcher | 규제, 윤리, 저작권, 데이터 거버넌스 | research/policy.md |
infra-researcher | 인프라, 개발 도구, 비용 구조 | research/infra.md |
agent-researcher | Agentic AI, 자동화, 멀티 에이전트 도구 | research/agent.md |
프롬프트는 다음처럼 시작할 수 있다.
text
2026년 AI 트렌드를 조사하고 싶다.
5개의 병렬 리서치 에이전트 팀을 설계해줘.
각 에이전트의 조사 범위는 겹치지 않게 나누고,
각자 결과를 markdown 파일로 저장하게 해줘.
공식 Claude Code subagent 구조를 기준으로 계획을 먼저 제시해줘.여기서 중요한 점은 "바로 조사해"가 아니라 팀 설계와 계획을 먼저 제시하라고 요청하는 것이다. 에이전트 팀은 한 번 만들면 반복해서 쓰게 되므로, 초기 설계를 검토하는 시간이 필요하다.
9. PPT 자동화 팀 예시
PPT 자동화는 멀티 에이전트와 Skill을 같이 쓰기 좋은 예다.
이 구조에서 각 역할은 다르다.
| 역할 | 책임 |
|---|---|
| Research Agent | 주제 조사, 근거 수집, 핵심 메시지 추출 |
| Planner Agent | 표지, 섹션, 비교, 통계, 인용, CTA 같은 슬라이드 유형 배치 |
| Design Skill | 브랜드 가이드라인, 색상, 타이포그래피, 레이아웃 규칙 적용 |
| PPTX Skill | 최종 파일 변환과 형식 처리 |
| Verifier | 조사 근거, 슬라이드 순서, 누락, 과장 표현 검토 |
PPT 품질은 "PPT 만들어줘"라는 한 문장보다 brand-guideline.md, 슬라이드 유형, 출력 규칙이 있을 때 훨씬 안정적이다. 디자인 레퍼런스를 분석해 brand-guideline.md를 만들고, 이후 모든 PPT 작업에서 그 파일을 참조하게 하는 방식이 좋다.
10. 마케팅 산출물 팀 예시
전자책, 뉴스레터, 블로그, SNS 포스트처럼 여러 산출물을 한 번에 만들 때는 직렬과 병렬을 섞는다.
| 단계 | 담당 | 설명 |
|---|---|---|
| 1 | Research Agent | 주제, 통계, 사례, 출처 조사 |
| 2 | Organizer Agent | 목차, 핵심 메시지, 산출물별 구조 정리 |
| 3 | Writer Agent | 긴 글, 뉴스레터, 블로그 본문 작성 |
| 4 | Copy Agent | SNS, 카드뉴스, CTA 문구로 재가공 |
| 5 | Designer Skill | 시각 스타일과 레이아웃 적용 |
| 6 | Publisher Skill | PDF, DOCX, PPTX, HTML 같은 형식으로 변환 |
이 흐름에서는 ResearchData.json 같은 중간 데이터를 남기는 것이 유용하다. 나중에 PPT나 Docs로 바꿀 때 같은 리서치를 다시 하지 않아도 되고, 사람이 출처와 통계를 검토하기 쉽다.
11. 상세 페이지 자동화 팀 예시
원문에는 상세 페이지를 여러 섹션으로 나누어 자동 생성하는 예시도 있다. 핵심은 설득형 페이지의 섹션 구조를 먼저 정하고, 각 섹션을 독립 작업으로 나누는 것이다.
| 섹션 묶음 | 예시 |
|---|---|
| 문제 인식 | Hero, Pain Point, Problem Agitation |
| 해결 제안 | Solution, Mechanism, Product Benefit |
| 신뢰 형성 | Proof, Review, Comparison, FAQ |
| 전환 유도 | Offer, Bonus, CTA, Closing |
이런 작업은 하이브리드 패턴에 가깝다.
- 오케스트레이터가 전체 설득 구조를 만든다.
- 섹션별 에이전트가 독립적으로 초안이나 이미지를 만든다.
- 수합 에이전트가 톤, 크기, 라운드, 여백, 색상 일관성을 맞춘다.
- 검증 에이전트가 메시지 흐름과 과장 표현을 확인한다.
- 사람이 최종 상업적 표현과 법적 리스크를 승인한다.
이미지 생성 API나 외부 모델을 붙일 때는 .env에 API 키를 저장하고, 모델명을 정확히 명시해야 한다. 모델명, 가격, 결제 조건은 빠르게 바뀔 수 있으므로 문서에 하드코딩하지 말고 실행 시점의 공식 문서를 확인한다.
12. 병렬 실행의 조건
병렬 실행은 항상 좋은 것이 아니다. 다음 조건을 만족할 때만 병렬화한다.
| 조건 | 질문 |
|---|---|
| 의존성 없음 | A 결과가 있어야 B를 할 수 있는가? |
| 출력 형식 통일 | 여러 에이전트 결과를 같은 형식으로 합칠 수 있는가? |
| 검증 기준 존재 | 서로 다른 결과 중 무엇이 좋은지 판단할 기준이 있는가? |
| 비용 허용 | 여러 모델을 동시에 쓰는 비용을 감당할 수 있는가? |
| 실패 격리 | 한 에이전트 실패가 전체 결과를 망치지 않게 설계했는가? |
의존성이 강한 작업은 직렬로 둔다. 예를 들어 "리서치 → 글쓰기 → 디자인"은 보통 직렬이다. 반면 "경쟁사 A/B/C 조사"나 "13개 상세 페이지 섹션 이미지 초안 생성"은 병렬로 나눌 수 있다.
13. 실패를 줄이는 출력 계약
멀티 에이전트에서 가장 자주 생기는 문제는 핸드오프 실패다. 리서처는 긴 글을 쓰고, 작성자는 표를 기대하고, 디자이너는 섹션별 JSON을 기대하면 전체 흐름이 깨진다.
그래서 에이전트마다 출력 계약을 정한다.
markdown
## Output contract
Write the result to `handoff/research-summary.md`.
Use this structure:
### Executive summary
- 5 bullets max
### Evidence table
| Claim | Evidence | Source | Confidence |
|-------|----------|--------|------------|
### Open questions
- List unresolved questions and what should be verified next.출력 계약에는 파일 위치, 형식, 필수 필드, 근거 수준, 미확인 사항이 포함되어야 한다. 그래야 다음 에이전트가 결과를 안정적으로 이어받는다.
14. 리스크와 운영 원칙
멀티 에이전트는 강력하지만 남발하면 오히려 느려진다.
| 리스크 | 대응 |
|---|---|
| 에이전트 수 과다 | 처음에는 3~5개 역할로 시작한다 |
| 비용 증가 | 단순 작업은 Skill이나 작은 모델에 맡긴다 |
| 권한 과다 | 읽기 전용 에이전트는 tools를 제한한다 |
| 결과 충돌 | 오케스트레이터가 최종 수합 기준을 가진다 |
| 검증 누락 | 별도 Verifier를 두고 사람 승인 지점을 명시한다 |
| 자동화 과신 | 외부 배포, 결제, API 키, 법적 표현은 사람이 확인한다 |
특히 bypassPermissions나 권한 생략 모드는 조심해야 한다. 빠르게 자동화할 수 있지만 파일 삭제, 외부 명령, 보안 정보 처리 같은 위험이 커진다. 멀티 에이전트 구조에서는 한 에이전트의 실수가 여러 산출물로 퍼질 수 있으므로 권한은 작게 시작한다.
15. 구축 체크리스트
멀티 에이전트 팀을 만들 때는 다음 순서로 점검한다.
- 목표 산출물을 한 문장으로 정의한다.
- 산출물까지 필요한 작업을 직렬과 병렬로 나눈다.
- 각 에이전트의 단일 책임을 정한다.
- Sub Agent로 만들 일과 Skill로 만들 일을 분리한다.
.claude/agents/에 에이전트 정의 파일을 만든다.CLAUDE.md에 라우팅 규칙과 금지 사항을 적는다.- 각 에이전트의 출력 계약과 핸드오프 파일 위치를 정한다.
- 처음에는 계획만 생성하게 하고 사람이 검토한다.
- 작은 입력으로 리허설을 실행한다.
- 비용, 권한, 실패 로그를 보고 에이전트 수를 조정한다.
핵심 정리
멀티 에이전트는 복잡한 자동화를 가능하게 하지만, 핵심은 "많이 실행하기"가 아니라 "정확히 나누기"다.
- 단일 책임으로 나눈다. 한 에이전트에게 리서치, 작성, 디자인, 검증을 모두 맡기지 않는다.
- Sub Agent와 Skill을 구분한다. 판단과 독립 컨텍스트가 필요하면 Sub Agent, 반복 절차와 변환은 Skill이 적합하다.
- 핸드오프 형식을 고정한다. 파일 위치, 표 구조, 필수 필드가 있어야 다음 에이전트가 안정적으로 이어받는다.
- 병렬화는 의존성이 낮을 때만 한다. 독립 작업은 병렬로, 의존 작업은 직렬로 처리한다.
- 사람 승인 지점을 남긴다. 요구사항, 외부 배포, 보안, 결제, 법적 표현은 자동화보다 검토가 먼저다.
Claude Code를 잘 쓰는 사람은 에이전트 하나에게 모든 일을 시키는 사람이 아니라, 작은 전문가 팀이 같은 기준으로 움직이도록 설계하는 사람이다.