멀티 에이전트 워크플로우 — 복잡한 작업 오케스트레이션

공식 참고 자료: Sub-agents · Agent Teams · Agent SDK · CLI usage

커리큘럼 흐름

1. CLAUDE.md Mastery — 저장소 메모리와 규칙
2. Effective Prompting — 작업 framing과 제약 설정
3. MCP Power Tools — 도구와 라이브 컨텍스트 연결
4. Multi-Agent Workflows — 위임과 병렬 실행 ← 현재 문서
5. Hooks Automation — 로컬 가드레일 자동화
6. GitHub Actions Workflows — 반복 작업을 팀 자동화로 옮기기

이 문서에서 참고한 공식 문서

• subagent와 위임 모델 — Sub-agents
• 에이전트 간 팀형 오케스트레이션 — Agent Teams
• 프로그래밍 가능한 오케스트레이션 개념 — Agent SDK
• CLI 실행 패턴 — CLI usage

핵심 원칙: 멀티 에이전트의 진짜 이득은 속도보다 분리다

서브에이전트를 생각할 때 가장 흔한 오해는 “병렬이라서 빨라진다”입니다. 물론 맞는 말이지만, Anthropic 문서가 더 강조하는 포인트는 컨텍스트 분리, 역할 분리, 권한 분리입니다.

서브에이전트는 각각:

• 자기만의 컨텍스트 윈도우를 갖고
• 자기만의 시스템 프롬프트를 쓰고
• 자기만의 도구/권한 제한을 가질 수 있습니다.

핵심 가치는 “한 번에 여러 명이 일한다”보다 메인 대화를 깨끗하게 유지하면서, 특정 종류의 일을 별도 맥락에서 처리하게 하는 것에 있습니다.

먼저 결정해야 할 것: 어떤 멀티 에이전트 표면을 쓸 것인가

Claude 쪽 오케스트레이션은 하나가 아닙니다. 목적에 따라 맞는 표면이 다릅니다.

즉, 모든 병렬 작업이 서브에이전트로 해결되는 것은 아닙니다.

서브에이전트는 언제 쓰는가

공식 docs를 실무 감각으로 번역하면, 서브에이전트는 아래 상황에서 특히 강합니다.

1) 조사 출력이 많을 때

테스트 전체 로그, 긴 문서 조사, 대형 코드 검색 결과는 메인 대화를 빠르게 오염시킵니다.

테스트 전체를 메인 컨텍스트에 쏟아붓지 말고,
서브에이전트로 실행해서 실패한 테스트와 핵심 에러만 요약해줘.

2) 병렬 research가 가능할 때

인증, 데이터베이스, API 모듈을 각각 별도 서브에이전트로 조사하고,
공통으로 드러나는 위험과 의존성을 마지막에 종합해줘.

이 패턴은 research path가 서로 독립적일 때 가장 잘 맞습니다.

3) 특정 권한/도구 제한이 필요할 때

예를 들어 reviewer는 읽기만, debugger는 edit 허용, browser tester는 Playwright MCP만 허용하는 식으로 좁힐 수 있습니다.

4) 역할을 재사용하고 싶을 때

.claude/agents/에 집중된 reviewer, debugger, safe-researcher 같은 역할을 두면, 이후에는 Claude가 설명을 보고 적절히 위임하거나 사용자가 명시적으로 호출할 수 있습니다.

서브에이전트를 쓰기 전에 먼저 해야 할 설계

병렬성은 공짜가 아닙니다. 병렬 실행 전에 공유 계약을 먼저 고정하지 않으면 속도 대신 충돌만 늘어납니다.

1. 공통 계약부터 정의

병렬 작업 전에 먼저 정할 것:

• 공유 타입/인터페이스
• 수정 가능한 파일 범위
• 완료 기준
• 병합 순서

예를 들어 풀스택 기능에서는 먼저 types/notification.ts 같은 공유 계약을 고정해야 합니다. 그다음 프론트엔드/백엔드/UI 테스트를 병렬화해야 충돌이 줄어듭니다.

2. 읽기 범위와 쓰기 범위를 분리

좋은 할당:

• 에이전트 A: src/api/notifications/만 수정
• 에이전트 B: src/components/notifications/만 수정
• 에이전트 C: 로그 분석 전용, read-only

나쁜 할당:

• 셋 다 src/types/notification.ts를 동시에 편집
• 셋 다 같은 router file을 만짐

3. 의존관계를 먼저 선언

모든 일을 병렬로 던지는 게 능사는 아닙니다.

• 독립 research → 병렬
• 구현 3개 → 병렬 가능
• 통합 테스트 → 구현 완료 후 순차
• 최종 리뷰 → 모든 diff가 모인 뒤 순차

멀티 에이전트의 기본 문법은 병렬로 가능한 것만 병렬화하고, 순서가 필요한 것은 명시적으로 직렬화하는 것입니다.

실전 오케스트레이션 패턴 1: Research fan-out

가장 안전하고 자주 쓰이는 패턴입니다.

다음 세 가지를 서브에이전트로 병렬 조사해줘.
 
1. auth/session 흐름
2. refresh token 저장 위치
3. API middleware의 인증 우회 가능성
 
각 에이전트는 수정하지 말고,
핵심 파일, 확인한 패턴, 위험 요소만 bullet로 요약해줘.
마지막에 내가 바로 구현에 들어갈 수 있게 종합 결론을 정리해줘.

이 패턴의 장점:

• 메인 컨텍스트가 검색 로그로 더러워지지 않습니다.
• 탐색 결과가 structured summary로 들어옵니다.
• 이후 구현은 메인 대화에서 집중해서 할 수 있습니다.

주의점은 하나입니다. 서브에이전트가 상세 결과를 너무 많이 돌려보내면 메인 컨텍스트를 다시 압박합니다. 그래서 "파일 경로 + 결론 + 리스크" 정도만 요약해 달라고 지시하는 것이 중요합니다.

실전 오케스트레이션 패턴 2: Writer / Reviewer 분리

Anthropic best practices는 fresh context를 가진 reviewer 패턴을 추천합니다. 코드를 쓴 같은 맥락에서 자기 코드를 다시 검토하면 편향이 생기기 쉽기 때문입니다.

세션 A: rate limiter 구현
세션 B: 방금 구현된 diff를 리뷰
 
리뷰 세션에는 아래처럼 요청:
@src/middleware/rateLimiter.ts 를 리뷰해줘.
edge case, race condition, 기존 middleware 패턴과의 일관성을 중심으로 봐줘.

이 패턴이 좋은 이유:

• reviewer가 작성 맥락에 덜 끌립니다.
• “왜 이렇게 짰는지”보다 “실제로 위험한가”를 더 잘 봅니다.
• 구현/리뷰를 병렬에 가깝게 굴릴 수 있습니다.

문서 작업에서도 그대로 쓸 수 있습니다.

• Writer: 초안 작성
• Reviewer: 사실관계, 구조, 누락 포인트 점검
• Main: 최종 정리

실전 오케스트레이션 패턴 3: 구현 lane + 검증 lane

병렬 구현은 종종 가능하지만, 검증은 대개 마지막에 한 번 더 모아야 합니다.

에이전트 1: 백엔드 API 구현
에이전트 2: 프론트엔드 UI 구현
에이전트 3: 마이그레이션 초안 작성
에이전트 4: 위 1~3 완료 후 통합 테스트 작성 및 실행

핵심은 에이전트 4를 처음부터 병렬로 돌리지 않는 것입니다. 구현 산출물이 아직 없는 상태에서 테스트 lane을 억지로 병렬화하면 오히려 재작업이 커집니다.

실전 오케스트레이션 패턴 4: high-volume 작업 격리

공식 sub-agents 문서는 테스트, 문서 수집, 로그 처리처럼 출력이 큰 일을 서브에이전트로 분리하라고 권합니다.

예:

서브에이전트로 전체 테스트를 실행하고,
실패한 테스트 이름, 핵심 에러 메시지, 공통 원인 후보만 요약해줘.
성공 로그는 길게 붙이지 마.

공식 문서를 읽는 조사 에이전트를 따로 두고,
최종 구현에 필요한 사실만 요약해서 가져와.
원문 전체를 길게 복사하지 마.

이 패턴은 속도 최적화라기보다 컨텍스트 위생 관리에 가깝습니다.

실전 오케스트레이션 패턴 5: chain subagents

모든 멀티 에이전트가 병렬일 필요는 없습니다. sub-agents 문서는 순차 체인도 중요한 패턴으로 소개합니다.

예:

1. code-reviewer 서브에이전트로 성능 이슈를 찾고
2. 그 결과를 바탕으로 optimizer 서브에이전트가 수정안을 제안하거나 구현하게 해줘

좋은 상황:

• review → fix
• investigate → implement
• schema audit → migration proposal
• docs inventory → documentation rewrite

중요한 제약:

• 서브에이전트는 또 다른 서브에이전트를 spawn할 수 없습니다.
• 중첩 위임이 필요하면 메인 대화가 계속 coordinator 역할을 해야 합니다.

메인 대화에 남겨야 하는 일 vs 서브에이전트로 넘겨야 하는 일

Anthropic docs에는 이 경계가 꽤 분명하게 나옵니다.

메인 대화에 남기는 편이 좋은 작업

• 자주 왕복하며 방향을 조정해야 하는 작업
• planning → implementation → testing이 강하게 이어지는 작업
• 아주 작은 수정
• latency가 중요한 작업

즉, 계속 “아니, 이 방향 말고”라고 교정해야 할 일은 메인 대화가 더 낫습니다.

서브에이전트로 넘기기 좋은 작업

• verbose output이 많은 조사/실행
• 요약된 결과만 받아도 되는 self-contained 작업
• 특정 권한/도구 제약을 강하게 걸고 싶은 작업
• 같은 역할을 반복적으로 재사용하는 작업

Agent teams는 언제 올라가야 하나

sub-agents 문서는 “병렬 작업과 상호 통신이 모두 필요하면 agent teams를 보라”고 안내합니다. 이 구분이 중요합니다.

서브에이전트로 충분한 경우

• 한 세션 안에서 메인 대화가 coordinator 역할을 잘 할 수 있을 때
• worker 사이 직접 통신이 꼭 필요하지 않을 때
• 병렬 research 또는 짧은 역할 분리가 핵심일 때

Agent teams가 더 잘 맞는 경우

• 병렬 실행이 오래 지속될 때
• worker끼리 메시지와 shared task coordination이 필요할 때
• 메인 세션 하나의 컨텍스트로 감당하기 어려울 때
• 독립적인 세션/작업공간을 유지하면서 협업시켜야 할 때

즉, subagent는 single-session 분업, agent teams는 multi-session 협업에 가깝다고 보면 됩니다.

여러 Claude 세션을 병렬로 굴리는 패턴

Anthropic best practices는 Claude Desktop, Claude on the Web, agent teams를 병렬 세션 전략으로 소개합니다. 여기서 중요한 포인트는 “parallel = faster”뿐 아니라 fresh context가 주는 품질 향상입니다.

예:

• 세션 A: 구현
• 세션 B: 리뷰
• 세션 C: 문서/릴리즈 노트 정리

좋은 이유:

• 세션마다 별도 맥락을 유지합니다.
• 리뷰 세션이 구현 편향에서 자유롭습니다.
• unrelated context가 섞이지 않습니다.

세션을 브랜치처럼 이름 붙여 두고 claude --continue, claude --resume으로 이어 쓰면 장기 작업에도 잘 맞습니다.

headless fan-out은 “많은 작은 독립 태스크”에 강하다

여러 파일에 같은 성격의 조사/변환을 적용할 때는 대화형보다 claude -p 기반 스크립트가 더 적합한 경우가 많습니다.

# 예시: 모듈별 코드 리뷰 리포트 생성
for module in src/auth src/api src/database; do
  claude -p "${module}를 리뷰하고 위험 요소를 markdown bullet로 정리해줘"     > "reports/$(basename "$module")-review.md" &
done
wait

이 방식이 맞는 작업:

• 파일 목록이 이미 있고
• 각 작업이 서로 거의 독립적이며
• 결과를 나중에 합쳐도 되는 경우

반대로 실시간 협의와 교정이 필요한 작업은 headless보다 대화형 세션이 낫습니다.

context budget 관점에서 멀티 에이전트를 봐야 한다

멀티 에이전트는 컨텍스트 문제를 완화하지만 공짜는 아닙니다.

좋은 점

• 조사 로그가 메인 대화에 덜 쌓입니다.
• 각 worker가 자기 일에 집중합니다.
• 빠른 모델과 강한 모델을 역할별로 나누기 쉽습니다.

나쁜 점

• 결과 요약이 많아지면 메인 대화가 다시 부풀어 오릅니다.
• 너무 많은 worker를 돌리면 coordinator가 결과를 읽는 비용이 커집니다.
• 서로 다른 맥락에서 나온 판단이 충돌할 수 있습니다.

그래서 실무에서는 이렇게 생각하는 편이 좋습니다.

병렬성은 공짜 compute가 아니라 오케스트레이션 부채를 함께 만든다.

질문은 “몇 개까지 돌릴 수 있나?”가 아니라 **“내가 결과를 다시 흡수하고 통합할 수 있나?”**입니다.

병렬화를 하지 말아야 하는 경우

Anthropic 문서를 실무에 적용하면, 아래 상황에서는 병렬성이 오히려 해롭습니다.

1) 작업이 너무 작을 때

오타 수정, 단일 파일 작은 편집, 명확한 rename은 메인 대화 하나가 가장 빠릅니다.

2) 같은 파일을 여러 lane이 동시에 건드릴 때

공유 hotspot 파일이 있으면 병렬성보다 충돌 비용이 더 커집니다.

예:

• 같은 router file
• 같은 shared type file
• 같은 migration file

3) 작업 순서가 강하게 직렬일 때

• DB schema 확정 전 API 구현
• API shape 확정 전 UI 구현
• 구현 전 통합 테스트 lane 확정

이 경우 억지 병렬화는 재작업만 늘립니다.

4) 메인 대화와 강한 상호작용이 필요한 작업일 때

사용자와 계속 의사결정을 주고받아야 하는 설계 작업은 메인 대화가 더 낫습니다.

5) latency가 더 중요할 때

서브에이전트는 fresh context로 시작하므로 준비 시간이 필요합니다. 아주 짧은 작업은 오히려 느립니다.

subagent 설계 자체가 품질을 좌우한다

Anthropic sub-agents docs의 best practices는 세 가지로 요약됩니다.

1. agent는 좁게 설계

한 subagent는 한 가지 일을 잘해야 합니다.

• good: code-reviewer, debugger, safe-researcher
• bad: “모든 걸 다 하는 만능 엔지니어”

2. description을 구체적으로

Claude는 description을 보고 언제 위임할지 판단합니다. 설명이 모호하면 delegation 품질도 떨어집니다.

3. tool access는 최소화

reviewer라면 Read/Grep/Glob/Bash 정도로 충분할 수 있고, read-only가 더 안전합니다. edit 권한이 정말 필요한 역할에만 Edit/Write를 줍니다.

worktree / 격리 전략을 같이 생각하자

여러 세션을 병렬로 돌릴 때는 git worktree 같은 격리 전략이 특히 유용합니다.

좋은 상황:

• 독립 실험을 병렬 진행할 때
• 리뷰용 세션을 완전히 분리하고 싶을 때
• 큰 리팩터링 가지를 여러 방향으로 시험할 때

핵심은 멀티 에이전트의 단위를 “프롬프트”만이 아니라 작업공간까지 포함해서 설계하는 것입니다.

Agent SDK는 언제 생각하면 되나

이 문서의 중심은 interactive Claude Code지만, orchestration 자체를 코드로 만들고 싶다면 Agent SDK 문서가 다음 단계입니다.

Agent SDK를 검토할 만한 상황:

• 같은 조사/검증 파이프라인을 반복 실행할 때
• CI에서 구조화된 결과를 수집하고 싶을 때
• 사용자 입력 없이 batch orchestration을 만들고 싶을 때

즉, 사람 주도 세션을 넘어서 반복 가능한 멀티 에이전트 운영 로직이 필요해질 때 올라가면 됩니다.

바로 복붙할 수 있는 오케스트레이션 프롬프트

패턴 1: 병렬 조사

다음 세 영역을 병렬로 조사해줘.
- auth/session
- auth/middleware
- auth/token-refresh
 
각 서브에이전트는 read-only로 조사하고,
관련 파일, 핵심 흐름, 위험 요소만 요약해줘.
상세 로그는 생략하고 마지막에 종합 결론만 정리해줘.

패턴 2: 구현 + 리뷰 분리

먼저 메인 대화에서 기능을 구현해.
그다음 fresh context의 reviewer 세션/서브에이전트로
방금 변경한 diff만 리뷰해줘.
리뷰 항목은 edge case, race condition, 기존 패턴 일관성이다.

패턴 3: lane 분업

"사용자 프로필" 기능을 다음 lane으로 나눠줘.
- Lane A: 백엔드 API
- Lane B: 프론트엔드 UI
- Lane C: 테스트 계획
 
먼저 공유 타입과 의존관계를 정의하고,
병렬 가능한 lane만 동시에 진행해줘.
검증은 마지막에 통합해서 수행해줘.

패턴 4: high-volume 격리

전체 테스트 스위트는 서브에이전트로 돌리고,
실패한 테스트 이름, 핵심 에러, 공통 원인만 요약해서 가져와.
성공 로그와 장황한 출력은 메인 컨텍스트로 가져오지 마.

최종 체크리스트

멀티 에이전트로 가기 전에 아래를 확인하면 실패가 크게 줄어듭니다.

• 정말 병렬화할 수 있는 독립 작업인가?
• 공유 타입/인터페이스를 먼저 고정했는가?
• 각 lane의 쓰기 범위가 겹치지 않는가?
• 요약 결과가 메인 컨텍스트를 다시 오염시키지 않는가?
• 메인 대화, subagent, 여러 세션, agent teams 중 어떤 표면이 맞는지 선택했는가?

잘 설계된 멀티 에이전트 워크플로는 “에이전트를 많이 돌리는 것”이 아닙니다. 무엇을 함께 생각해야 하고, 무엇을 분리해야 하는지 명확히 나누는 것이 진짜 오케스트레이션입니다.