Claude Code에서 여러 서브에이전트 오케스트레이션: 복잡한 워크플로우 구축 (2026)

- Claude Code의 에이전트 오케스트레이션 영역은 빠르게 변하고 있어요(에이전트 팀, 동적 워크플로우, 깊이 제한 등). 이 글의 수치는 작성 시점에 Claude Code 공식 문서와 Anthropic의 리서치 게시물에 비추어 다시 확인한 것이에요. 실제로 의존하기 전에 최신 문서를 확인하세요.

서브에이전트 오케스트레이션이란 무엇인가요?

단일 서브에이전트를 만들고 실행하는 데 익숙해졌다면, 다음 단계는 Claude Code에서 서브에이전트를 오케스트레이션하는 거예요. 하나의 메인 에이전트가 여러 워커 서브에이전트를 동시에 조율하거나 서로 연결하도록 하는 것이죠. 이것이 고전적인 오케스트레이터-워커 패턴(리드 에이전트가 워커를 조율한다고도 불러요)이에요.

기억해 둘 짧은 정의: 서브에이전트 오케스트레이션이란, 하나의 조율 에이전트(오케스트레이터)가 여러 서브에이전트를 띄우고, 각 서브에이전트가 독립된 컨텍스트 윈도우에서 작업의 일부를 처리한 뒤, 메인 에이전트가 종합할 수 있도록 간결한 요약을 돌려주는 것을 말해요.

모든 핵심은 "독립된 컨텍스트"라는 말에 있어요. 각 서브에이전트는 독립된 컨텍스트 윈도우를 가지므로, 수십 개의 파일을 읽고 여러 명령을 실행하며 긴 출력을 만들어도 메인 세션의 컨텍스트를 부풀리지 않아요. 메인 에이전트는 정제된 부분만 돌려받아요. 이것이 원래 세션의 컨텍스트를 깨끗하게 유지하면서 크고 여러 갈래로 나뉜 작업을 처리하는 방법이에요.

이것은 고급 기능이에요. 서브에이전트가 무엇인지, 기본적인 것을 어떻게 선언하는지 아직 명확하지 않다면, 먼저 초보자를 위한 서브에이전트 가이드를 읽고 다시 돌아오세요. 이 글은 이미 최소한 하나의 서브에이전트를 만들어 봤고, 이제 여러 개를 동시에 지휘하고 싶은 상황을 전제로 해요. 이는 실습형 튜토리얼에서 처음부터 끝까지 다루는 경우가 거의 없는 주제예요.

여러 서브에이전트를 오케스트레이션해야 할 때와 하지 말아야 할 때

여러 에이전트를 조율하는 것이 항상 이득은 아니에요. 토큰을 많이 먹고 지연도 늘어나므로, 작업이 정말로 분기로 나뉠 때에만 값어치를 해요. 여기가 가장 가치 있는 판단 지점이며, 문서와 블로그가 대개 그냥 지나쳐 버리는 부분이에요.

15배라는 토큰 수치와 상태 공유 경고는 모두 Anthropic의 멀티 에이전트 리서치 시스템 게시물(2025년 6월 13일)에서 나온 것이에요. 같은 게시물은 성능 편차의 대부분(약 80%)이 소비된 토큰 양에서 비롯된다고 언급해요 — 즉 토큰은 비용이자 지렛대예요. 실용적인 규칙: 작업을 명확하고 분리된 분기로 표현할 수 없다면 오케스트레이션하지 말고 하나의 선형 세션을 쓰세요. 서브에이전트가 스킬, 훅, MCP와 어떤 관계에 있는지 보려면 스킬, 서브에이전트, 훅, MCP의 차이를 읽어 보세요.

두 가지 오케스트레이션 패턴: 병렬 vs 파이프라인

기초가 되는 패턴은 정확히 두 가지예요. 각각을 언제 꺼내 쓸지 아는 것만으로도 이미 대부분의 개발자보다 앞서 있는 거예요.

병렬(팬아웃 / 팬인): 메인 에이전트가 여러 서브에이전트를 동시에 띄워 각각 독립된 분기를 처리한 뒤, 메인 에이전트가 요약을 하나의 결과로 모아요(팬인).

 ┌─→ subagent: auth ────┐
main agent ├─→ subagent: database ─┤─→ synthesize
 └─→ subagent: API ─────┘
 (parallel fan-out) (fan-in)

파이프라인(체인 / 순차): 서브에이전트가 순서대로 실행되며, 한 단계의 출력이 다음 단계의 입력이 돼요. 메인 에이전트가 각 링크 사이에서 컨텍스트를 전달해요.

main → subagent: reviewer → subagent: optimizer → result
 (find issues) (fix based on issues)

한 문장 테스트: 분기가 서로의 결과를 알 필요가 없으면 병렬, B 단계가 A 단계의 결과를 필요로 하면 파이프라인이에요. 실제 워크플로우의 상당수는 하이브리드예요. 수집 단계에서는 병렬로 팬아웃하고, 마지막 종합 단계 하나만 연결해요.

예제 1 — 서브에이전트를 병렬로 실행하기(처음부터)

실제 작업: 백엔드 리포지토리를 빠르게 감사하고 싶어요. 세 가지 독립 영역 — auth, database, API — 을 한꺼번에 점검해요. 이 세 영역은 서로 의존하지 않아서 병렬 실행에 딱 들어맞는 교과서적 사례예요.

1. 조율 프롬프트를 입력하세요. Claude에게 명시적으로 팬아웃하도록 요청하고, 세 분기를 지정하며, 각 서브에이전트가 요약만 반환하도록 지시하세요:

   Audit this repo in parallel using 3 independent subagents:
   1) auth: check login flow, sessions, permission holes
   2) database: check schema, N+1 queries, missing indexes
   3) API: check input validation, rate limiting, error handling
   Each subagent should return only a short summary (~10 bullets max),
   NOT a full log dump. Then combine into one report.

2. Claude가 팬아웃하는 것을 지켜보세요. Claude Code가 세 서브에이전트를 띄워 병렬로 실행하고, 각각 자체 컨텍스트에서 코드를 읽어요. 세션에서 세 개의 작업 흐름이 동시에 진행되는 것을 볼 수 있어요.
3. 병합된 요약을 읽으세요. 셋이 모두 끝나면(팬인) 메인 에이전트가 이를 하나의 보고서로 합쳐요. 각 서브에이전트가 간결한 항목만 반환했기 때문에 메인 세션의 컨텍스트는 가볍게 유지돼요.

종합 단계의 압축된 출력은 대략 다음과 같아요(형식을 보여 주기 위한 것이며, 여러분 리포지토리의 실제 수치가 아니에요):

Audit report (merged from 3 subagents):
[auth] - Sessions not setting HttpOnly/Secure flags
 - Missing permission check on /admin/* endpoints
[database] - Order list query has N+1 (findOne in loop)
 - users table missing index on email column
[API] - 4 endpoints not validating the request body
 - No rate limit on the login route

여기서 병렬이 맞는 이유: 세 분기는 서로의 데이터가 필요 없으므로, 동시에 실행하면 실행 시간을 줄이고 각 긴 보고서를 자체 컨텍스트에 분리할 수 있어요. 이를 억지로 순차 실행해도 느려질 뿐 더 정확해지지는 않아요.

예제 2 — 순차 파이프라인(체인): reviewer에서 optimizer로

실제 작업: 어떤 모듈에 성능 문제가 있다고 의심해요. 1단계에서 code-reviewer 서브에이전트가 병목을 찾아요. 2단계에서 optimizer 서브에이전트가 그 목록에 기반해 병목을 고쳐요. 이는 명확한 의존 관계예요 — optimizer는 reviewer가 무엇을 찾았는지 알아야 하므로 — 따라서 병렬이 아니라 순차여야 해요.

1. 먼저 reviewer를 실행하세요. 조율 프롬프트:

   Use the code-reviewer subagent to find performance bottlenecks
   in the src/services/ directory and return a prioritized list.

2. 결과를 optimizer에 넘기세요. 메인 에이전트가 reviewer의 목록을 다음 단계의 입력으로 받아요:

   Hand the list above to the optimizer subagent:
   fix in priority order, add one line explaining each change,
   and do NOT change any public API behavior.

3. 최종 결과를 얻으세요. optimizer는 reviewer가 표시한 바로 그것을 작업해요. Claude가 중계 역할을 하며 두 링크 사이에서 컨텍스트를 전달해요.

[reviewer] Found 3 bottlenecks:
 P1 - parseAll() re-reads the file inside a loop
 P2 - sequential API calls that could be batched
 P3 - JSON.parse repeated on the same payload
[optimizer] Fixed:
 P1 → cache file contents outside the loop
 P2 → merge into a single batch request
 P3 → parse once, reuse the object

핵심 포인트: 뒤 단계가 앞 단계의 출력을 필요로 할 때 파이프라인을 쓰세요. 이 의존적인 두 단계를 병렬화하려 하면 reviewer의 목록이 아직 없기 때문에 optimizer가 눈먼 채로 고치게 돼요. 오케스트레이션은 고립되어 존재하지 않아요 — 그것은 브레인스토밍 → 플랜 → 쿡 → 십 워크플로우의 한 조각이에요. 보통 먼저 계획을 세운 다음, 서브에이전트를 풀어 분기를 쿡해요.

고급 — 오케스트레이터 에이전트, 중첩 서브에이전트, 깊이 제한

매번 조율 프롬프트를 입력하는 대신, 조율만 전담하는 전용 오케스트레이터 에이전트를 선언할 수 있어요. .claude/agents/coordinator.md에 파일을 만드세요:

---
name: coordinator
description: Coordinates worker subagents for large, multi-branch tasks.
 Only splits work, spawns workers, and merges summaries - does NOT write code itself.
---

You are a coordinating agent. Your job:
1. Decompose the request into independent branches (if any).
2. Independent branches → dispatch in parallel; dependent branches → chain.
3. Require each worker to return ONLY a tight summary.
4. Merge everything into a single result for the user.
Do not do the detailed work yourself; always delegate to workers.

프런트매터의 name과 description은 Claude가 이 에이전트를 언제 호출할지 판단하는 데 도움을 줘요. "조율만" 제약은 에이전트가 스스로 작업에 뛰어들어 자기 컨텍스트를 폭발시키는 것을 막아 줘요.

중첩 서브에이전트: 서브에이전트는 자신의 자식 서브에이전트를 띄울 수 있어요. 이는 강력하지만 통제를 잃기 쉬워서 Claude Code가 깊이에 상한을 둬요. 서브에이전트에 관한 Claude Code 공식 문서(2026-08 확인)에 따르면 기본 생성 깊이는 3단계이며 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 환경 변수로 조정할 수 있어요. 너무 높게 설정하면 에이전트 수가 폭발하고 토큰이 낭비되기 쉬워요. 실제 워크플로우 대부분은 기본값을 넘길 필요가 없어요.

지속적인 병렬 작업이나 단일 컨텍스트 윈도우를 넘어서는 작업에는, 이 패턴이 멈추는 지점을 이어받는 두 가지 새로운 네이티브 프리미티브가 있어요 — 아래 "오케스트레이션의 새로운 기능(2026)"을 참고하세요.

오케스트레이터-워커 모델 외에도, 위임 실행이 아니라 조언을 원할 때를 위한 덜 흔한 패턴이 있어요: 어드바이저리 패턴: 체크포인트에서 kongming에게 조언 구하기.

오케스트레이션의 새로운 기능(2026): 동적 워크플로우 & 에이전트 팀

위에서 다룬 프롬프트-앤-코디네이터 패턴은 설명한 그대로 여전히 잘 작동하고, 일상적인 여러 분기 위임에는 여전히 올바른 기본값이에요 — 대부분의 작업은 그 이상이 필요 없어요. 이 가이드가 처음 공개된 이후, Claude Code는 오케스트레이션을 한층 더 확장하는 두 가지 새로운 네이티브 프리미티브를 출시했어요: Claude Code 동적 워크플로우(Claude가 스크립트를 작성해 작업을 프로그램적으로 팬아웃)와 Claude Code 에이전트 팀(실험적인 멀티 세션 모드)이에요. 둘 다 위의 패턴을 대체하지 않아요 — 더 크거나 오래 실행되는 작업을 위해 그 위에 얹히는 것이에요.

이 가이드의 두 예제 같은 일상적인 여러 분기 작업에는 위의 프롬프트-앤-코디네이터 패턴을 계속 쓰세요. 작업이 하나의 컨텍스트 윈도우를 넘어서거나 실제 규모에서 교차 검증된 백그라운드 실행이 유용할 때는 동적 워크플로우를 꺼내 쓰세요. 단발성 위임-반환 실행이 아니라 오래 실행되는 협업형 멀티 세션 구성이 필요할 때는 에이전트 팀을 꺼내 쓰세요. 두 프리미티브 모두 정확한 에이전트 수와 동시성 한도를 포함해 여전히 발전 중이므로, 프로덕션에서 어느 쪽에든 의존하기 전에 최신 문서를 다시 확인하세요.

오케스트레이션할 때 토큰과 비용 최적화하기

멀티 에이전트 실행은 일반 채팅 세션의 약 15배 토큰이 들기 때문에(Anthropic 기준), 토큰 최적화는 선택이 아니에요 — 그것이 오케스트레이션을 돈값하게 만드는 조건이에요. 실용적인 몇 가지 방법:

• 서브에이전트 수를 제한하세요 — 한 번의 팬아웃당 3~5개로. 에이전트를 더 늘려도 품질이 비례해서 좋아지는 경우는 드물지만, 토큰은 선형으로 늘어나요.
• 워커를 더 저렴한 모델로 보내세요. 단순한 분기(파일 읽기, 목록 나열)는 Haiku 같은 저렴한 모델에 맡기고, 강력한 모델은 종합 단계를 위해 아껴 두세요.
• 서브에이전트가 요약만 반환하도록 강제하세요, 전체 로그/디프 덤프를 메인 에이전트로 되돌리지 말고요. 이것이 토큰 낭비의 가장 큰 원인이며, 누구나 여기에 빠져요.
• 여러 서브에이전트가 각각 긴 출력을 메인으로 반환하는 것을 피하세요 — 여러 긴 출력을 팬인하면 메인 컨텍스트가 꽉 차서 분리의 취지 자체가 무너져요.

멀티 에이전트 세션의 토큰 예산을 더 깊이 알아보려면 여러 에이전트를 실행할 때 토큰 최적화하기 가이드를 보세요.

직접 만들고 싶지 않다고요? 이미 만들어진 오케스트레이터 에이전트 키트(AgentKit)

괜찮은 코디네이터와 워커 한 무리를 작성하는 데는 시간이 걸려요. 바로 쓸 수 있는 것을 원한다면, 이를 패키징한 키트가 있어요. 혼동을 피하기 위해 한마디: 여기서 말하는 AgentKit은 Claude Code용 키트(agentkit.best, ak CLI)이고, OpenAI의 AgentKit(Agent Builder/ChatKit, 2025년 10월 6일 출시)이 아니에요.

AgentKit의 Engineer Kit에는 17개의 엔지니어 에이전트(플랫폼 전체 45개 = 엔지니어 17 + 마케팅 28 중)와 오케스트레이션 워크플로우 — 예를 들어 ak-orchestrate 스킬 — 가 함께 제공되어, 코디네이터를 처음부터 작성할 필요가 없어요. 표시된 Engineer Kit 가격은 99달러이고, 페이지에 정기 결제 언급은 없어요. 솔직히 말하면, 위 섹션을 따라 오케스트레이터는 얼마든지 직접 만들 수 있어요. 키트는 셋업 시간을 절약하고 미리 튜닝된 에이전트를 쓰고 싶을 때만 값어치가 있어요. 안에 정확히 무엇이 들어 있는지 보려면 Engineer Kit 리뷰를 읽거나, AgentKit의 이미 만들어진 오케스트레이터 에이전트를 바로 확인해 보세요.

여러 서브에이전트를 오케스트레이션할 때 흔한 실수

• 서브에이전트를 너무 많이 띄우기. 모두가 한꺼번에 결과를 반환하면 메인 컨텍스트가 타 버려요. 회피법: 한 라운드당 3~5개로 유지하고 요약을 강제하세요.
• 의존적인 작업에 병렬 쓰기. 잘못된 결과나 데이터 경쟁을 일으켜요. 회피법: "뒤 단계가 앞 단계의 출력을 필요로 하나?"라고 물어보세요 — 그렇다면 파이프라인을 쓰세요.
• 서브에이전트가 요약 대신 긴 로그를 반환하기. 토큰 낭비와 컨텍스트 과부하를 낳아요. 회피법: 출력 한도를 프롬프트나 에이전트 정의에 명시하세요.
• 깊이 제한을 잊기. 중첩 서브에이전트가 단계를 넘쳐 에이전트 수가 폭발해요. 회피법: 분명한 이유가 없다면 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH를 기본값으로 유지하세요.
• 불균형한 토큰 소비. 작은 변경에 멀티 에이전트를 쓰기. 회피법: 작거나 빠른 작업에는 오케스트레이션하지 말고 하나의 선형 세션을 실행하세요.

자주 묻는 질문(FAQ)

병렬로 몇 개의 서브에이전트를 실행할 수 있나요?

실무에서는 한 번의 팬아웃당 3~5개의 서브에이전트로 유지하세요. 엄격한 한도는 아니지만, 그 이상이면 대개 품질이 비례해 좋아지지 않으면서 토큰은 빠르게 오르고 병합된 컨텍스트가 과부하되기 쉬워요. 하나의 거대한 라운드보다 여러 번의 작은 팬아웃이 나아요.

병렬과 파이프라인 중 어느 쪽이 토큰을 더 쓰나요?

병렬은 대개 많은 에이전트가 각자 자체 컨텍스트로 한꺼번에 실행되므로 토큰이 더 급격히 치솟아요. 파이프라인은 어느 한 시점에서는 토큰 소비가 더 완만하지만 단계마다 누적되고 더 느려요. 토큰만이 아니라 작업의 의존 관계에 따라 선택하세요.

서브에이전트가 자신의 자식 서브에이전트(중첩)를 띄울 수 있나요?

네. 서브에이전트는 자식 서브에이전트(중첩 서브에이전트)를 띄울 수 있어요. Claude Code는 깊이에 상한을 둬요 — 기본 3단계 — 그리고 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 변수로 조정할 수 있어요. 대부분의 워크플로우는 기본값을 넘길 필요가 없어요.

오케스트레이션하려면 에이전트 팀이 필요한가요?

아니요, 필수가 아니에요. 조율 프롬프트나 직접 선언한 오케스트레이터 에이전트만으로도 오케스트레이션할 수 있어요. 에이전트 팀은 단일 컨텍스트 윈도우를 넘어서는 지속적이고 대규모의 병렬 처리를 위한 표면이에요. 기능이 새롭고 빠르게 바뀌므로 최신 문서를 확인하세요 — 전체 비교는 위의 "오케스트레이션의 새로운 기능(2026)"을 참고하세요.

동적 워크플로우는 서브에이전트 오케스트레이션과 같은 건가요?

아니요. 이 가이드의 오케스트레이터-워커 패턴은 프롬프트 주도예요 — Claude가 매 턴 다음에 무엇을 실행할지 결정해요. 동적 워크플로우는 별개의 더 새로운 프리미티브예요: Claude가 앞서 JS 스크립트를 작성하므로, 계획이 Claude의 컨텍스트가 아니라 스크립트에 존재하고, 손으로 조율하는 것보다 훨씬 많은 에이전트(작성 시점 문서 기준 최대 1,000개)로 팬아웃할 수 있어요. 셋업과 제한은 동적 워크플로우 전체 가이드를 보세요.

작은 프로젝트에 여러 에이전트 오케스트레이션이 값어치가 있나요?

대개는 아니에요. 작거나 빠른 변경에서는 조율과 토큰 비용(멀티 에이전트 실행은 Anthropic 기준 약 15배 토큰이 듦)이 이점을 웃돌아요. 작업이 정말로 독립적인 분기로 나뉘거나 여러 영역에 걸칠 때에만 오케스트레이션하세요.

이미 만들어진 조율 에이전트 키트가 있나요?

네. AgentKit의 Engineer Kit(agentkit.best, ak CLI — OpenAI AgentKit과는 다름)는 17개의 엔지니어 에이전트와 오케스트레이션 워크플로우를 패키징해, 코디네이터를 직접 작성하지 않아도 돼요. 위에서 보여 준 대로 전부 직접 만들 수도 있어요. 키트는 단지 셋업 시간을 절약해 줄 뿐이에요.

결론과 다음 단계

열 개짜리 에이전트 오케스트라로 시작하지 마세요. 먼저 2단계 파이프라인(reviewer에서 optimizer 같은)을 만들고, 그것이 태우는 토큰을 측정한 다음, 작업이 정말로 독립적인 분기로 나뉠 때에만 병렬 팬아웃으로 확장하세요. 초보자를 위한 서브에이전트 가이드에서 기본기를 다지고, 브레인스토밍 → 플랜 → 쿡 → 십 워크플로우 안에서 오케스트레이션을 제자리에 놓으세요. 코디네이터를 직접 작성하고 싶지 않다면 Engineer Kit 리뷰를 확인해 보세요.