Claude Code 에이전트 팀 설계 가이드: 서브에이전트를 넘어 팀으로

Claude Code에서 서브에이전트(Subagent)를 쓰고 있다면, 절반만 쓰고 있는 겁니다. 파일 탐색을 탐색(Explore) 에이전트에 맡기고, 복잡한 리서치를 범용(General-purpose) 에이전트에 위임하고, 결과를 받아서 이어 작업하는 패턴. 대부분 이 방식에 익숙합니다.

그런데 이 구조에는 한계가 있습니다. 서브에이전트는 시켜놓고 결과만 받는 구조거든요. 에이전트끼리 대화하지 않습니다. 에이전트 A가 발견한 정보를 에이전트 B가 참고해야 하는 상황에서도, 반드시 메인 에이전트를 거쳐야 하고요. 결국 메인 에이전트가 병목이 됩니다.

2026년 2월, Opus 4.6과 함께 에이전트 팀(Agent Teams)이 리서치 프리뷰(research preview)로 공개됐습니다. OpenAI Codex 출시 3일 뒤에 나온 발표로, AI 코딩 도구의 멀티에이전트 경쟁이 본격화된 시점이기도 합니다. 여러 에이전트가 공유 태스크 리스트(Task List)와 메일박스(Mailbox)를 통해 서로 메시지를 주고받으며 팀으로 동작하는 구조입니다. 아직 프리뷰 단계이지만, 멀티에이전트 시스템의 핵심 개념을 이해하고 나면 Claude Code뿐 아니라 어떤 AI 에이전트 시스템에서든 팀 구조를 직접 설계할 수 있게 되죠.

이 글에서는 서브에이전트와 에이전트 팀의 아키텍처 차이부터 시작해서, 멀티에이전트 설계 패턴, 역할 전문화, 검증-수정 루프, 모델 배정 전략, 그리고 실패 패턴까지 하나씩 짚어보겠습니다.

서브에이전트 패턴, 정확히 뭐가 부족한가

먼저 서브에이전트의 동작 구조를 짚어보겠습니다. Claude Code에서 에이전트 도구를 호출하면 새로운 Claude 인스턴스가 생성됩니다. 이 인스턴스는 독립된 컨텍스트 윈도우를 가지고, 지정된 도구를 사용해 작업을 수행하고, 결과를 메인 에이전트에 반환하는 것으로 역할이 끝납니다.

공식 문서의 표현을 그대로 옮기면 이렇습니다. "Subagents only report results back to the main agent and never talk to each other." 서브에이전트는 메인 에이전트에게만 결과를 보고하고, 서로 대화하지 않습니다.

이 구조의 문제는 세 가지입니다.

첫째, 모든 정보가 메인 에이전트를 거칩니다. 에이전트 A가 파일 구조를 분석한 결과를 에이전트 B가 참고해야 한다면, A의 결과가 메인에 올라가고, 메인이 다시 B에게 전달하는 과정을 거치게 되죠. 메인 에이전트의 컨텍스트 윈도우에 모든 중간 결과가 쌓이고, 작업이 복잡해질수록 메인의 컨텍스트가 빠르게 소진됩니다.

둘째, 서브에이전트는 다른 서브에이전트를 생성할 수 없습니다. 공식 문서에 명시된 제약이죠. "Subagents cannot spawn other subagents." 코디네이터 역할의 서브에이전트가 실무자 역할의 서브에이전트를 만들어 위임하는 식의 계층적 작업 분해가 안 됩니다.

셋째, 피드백 루프가 없습니다. 서브에이전트가 작업을 완료하면 결과를 메인이 받아서 판단하는데, 결과가 부족하면 메인이 다시 새로운 서브에이전트를 호출하거나, 같은 서브에이전트를 resume해야 합니다. 자동화된 검증-수정 사이클을 만들기 어려운 구조입니다.

이 한계는 서브에이전트가 설계상 잘못되어서가 아닙니다. 서브에이전트는 "독립적인 단일 작업을 병렬로 처리"하는 데 최적화된 구조거든요. 파일 검색, 코드 분석, 단순 리서치처럼 작업 간 의존성이 없으면 서브에이전트가 여전히 효율적입니다. 문제는, 현실의 복잡한 작업은 에이전트 간 의존성이 있는 경우가 훨씬 많다는 겁니다.

에이전트 팀 아키텍처 해부

서브에이전트의 한계를 이해했으니, 이제 에이전트 팀이 이 문제를 어떻게 풀어내는지 들여다보겠습니다. 다음 그림은 서브에이전트 패턴과 에이전트 팀 패턴의 아키텍처 차이를 보여줍니다.

Subagent vs Agent Teams 아키텍처 비교

서브에이전트 패턴은 메인 에이전트를 중심으로 한 허브-스포크 구조입니다. 자전거 바퀴를 생각하면 됩니다. 중앙 축에서 모든 살이 뻗어나가듯, 모든 통신이 중앙을 경유합니다. 반면 에이전트 팀 패턴은 팀원끼리 직접 소통할 수 있는 메쉬 구조입니다. 그물망처럼 각 팀원이 서로 직접 연결되어 있고, 공유 태스크 리스트와 메일박스를 통해 정보를 교환합니다.

에이전트 팀은 이 한계를 구조적으로 풀어줍니다. 구성 요소는 네 가지입니다.

**팀 리드(Team Lead)**는 팀의 지휘자입니다. 사용자와 직접 대화하고, 작업을 분해하고, 팀원에게 할당하고, 결과를 종합하죠. 서브에이전트 구조의 메인 에이전트와 비슷해 보이지만, 결정적인 차이가 있습니다. 팀 리드는 모든 중간 결과를 자기 컨텍스트에 쌓지 않아도 됩니다. 팀원들이 공유 태스크 리스트를 통해 직접 소통하기 때문이죠.

**팀원(Teammates)**은 실무 에이전트입니다. 각자 독립된 Claude 인스턴스로 동작하고, 고유한 컨텍스트 윈도우를 갖습니다. 중요한 건 팀원끼리 직접 메시지를 주고받을 수 있다는 점입니다.

태스크 리스트는 공유 작업 목록입니다. 팀 리드가 작업을 등록하면, 팀원들이 자율적으로 가져갑니다. 서브에이전트와의 가장 큰 구조적 차이가 여기 있습니다. 서브에이전트는 메인이 명시적으로 호출해야 동작하지만, 에이전트 팀의 팀원은 태스크 리스트에서 자기가 처리할 수 있는 작업을 직접 가져가거든요.

메일박스는 에이전트 간 직접 메시지 시스템입니다. 팀원 A가 팀원 B에게 정보를 전달하거나 질문할 수 있고, 메인 에이전트를 거칠 필요가 없습니다.

이 네 가지가 조합되면, 회사 조직에 비유할 수 있는 구조가 됩니다. 팀장이 프로젝트를 기획하고 업무를 배분하는 부분은 중앙 제어(오케스트레이션)이고, 팀원들이 공유 칸반 보드에서 자율적으로 작업을 가져가는 부분은 분산 자율(코레오그래피)입니다. 분산 시스템 이론에서는 이걸 "하이브리드 오케스트레이션-코레오그래피" 패턴이라 부릅니다.

2026년 1월 arXiv에 발표된 멀티에이전트 오케스트레이션 종합 리뷰 논문(arXiv 2601.13671)에서도 이 하이브리드 구조를 주목합니다. 순수 오케스트레이션은 중앙 제어자가 병목이 되고, 순수 코레오그래피는 작업 간 일관성을 유지하기 어렵거든요. 두 접근법을 결합하면, 일관성은 중앙에서, 실행 효율성은 분산에서 확보할 수 있습니다.

서브에이전트와 에이전트 팀의 차이를 한눈에 비교하면 이렇습니다.

항목	서브에이전트	에이전트 팀
통신 구조	메인 ↔ 에이전트 (허브-스포크)	에이전트 ↔ 에이전트 (메쉬)
작업 할당	메인이 명시적 호출	팀원이 태스크 리스트에서 자율 청구
컨텍스트 부담	메인에 모든 결과 집중	팀원 간 직접 공유로 분산
피드백 루프	수동 (메인이 재호출)	자동 (훅(hooks) 기반 검증-수정)
최적 용도	독립적 병렬 작업	상호 의존적 복합 작업
토큰 비용	작업당 1x (조율 오버헤드 없음)	작업당 1.5~2x (팀 조율 오버헤드 포함, 팀 크기에 따라 비선형 증가)

마지막 항목이 중요합니다. 에이전트 팀이 항상 좋은 건 아닙니다. 팀 조율에 토큰이 소비되거든요. 독립적인 작업 3개를 병렬로 돌리는 상황이라면 서브에이전트가 더 효율적입니다. 에이전트 팀은 에이전트 간 의존성이 있는 복합 작업에서 진가를 발휘합니다.

팀 리드를 운용할 때 알아두면 좋은 기능이 델리게이트 모드(Delegate Mode)입니다. Shift+Tab으로 활성화하면, 팀 리드가 코드를 직접 작성하지 않고 조율과 위임에만 집중하죠. 오케스트라의 지휘자가 직접 악기를 연주하지 않는 것과 같은 원리입니다. 팀 리드가 구현 작업까지 떠안으면 컨텍스트가 빠르게 소진되므로, 팀 규모가 3명 이상이면 델리게이트 모드를 기본으로 쓰는 게 좋습니다.

팀원들의 컨텍스트 공유도 짚어야 합니다. 에이전트 팀의 팀원들은 자신의 작업 디렉토리에 있는 CLAUDE.md 파일을 자동으로 읽습니다. 프로젝트의 코딩 컨벤션, 아키텍처 원칙, 금지 사항 등을 CLAUDE.md에 정리해두면 모든 팀원이 동일한 맥락에서 작업하게 되죠. 별도의 프롬프트로 일일이 전달하지 않아도 되니, 팀 일관성을 유지하기에 가장 간편합니다.

현재 알려진 한계

에이전트 팀은 아직 리서치 프리뷰 단계입니다. 실무에 적용하기 전에 알아야 할 제약이 있습니다.

첫째, 세션 복구가 안 됩니다. /resume 명령이 에이전트 팀 세션에서는 동작하지 않거든요. 장시간 작업 중에 세션이 끊기면 처음부터 다시 시작해야 합니다. 대규모 작업에서는 상당한 리스크이므로, 작업을 작은 단위로 나눠서 중간 산출물을 파일로 저장하는 습관이 필요합니다.

둘째, 중첩 팀을 구성할 수 없습니다. 팀원이 자체적으로 하위 팀을 만드는 구조가 불가능하고, 현재는 하나의 팀 리드 아래 평면적인 팀 구조만 지원합니다.

셋째, 리서치 프리뷰 특성상 API와 동작 방식이 변경될 수 있습니다. 프로덕션 워크플로의 핵심 경로에 에이전트 팀을 넣기보다는, 보조적인 작업부터 시도하면서 안정성을 확인하는 게 현실적이죠.

멀티에이전트 설계 패턴 다섯 가지

다음 그림은 멀티에이전트 시스템의 기본 설계 패턴 다섯 가지를 시각화한 것입니다.

멀티에이전트 설계 패턴 5가지

프롬프트 체이닝(Prompt Chaining)은 순차 파이프라인, 라우팅(Routing)은 분류 후 전문가 라우팅, 병렬화(Parallelization)는 병렬 처리 후 결과 통합, 오케스트레이터-워커(Orchestrator-Workers)는 동적 작업 분해와 위임, 평가자-최적화기(Evaluator-Optimizer)는 생성-평가 피드백 루프입니다. 실전에서는 이 패턴들을 조합합니다.

Anthropic이 2024년 12월에 발표한 "Building Effective Agents" 가이드는 에이전트 시스템의 기본 설계 패턴 다섯 가지를 정의합니다. 에이전트 팀을 설계할 때 이 다섯 가지 패턴을 알아두면 좋습니다. 팀 구조가 결국 이 패턴들의 조합이거든요.

프롬프트 체이닝

가장 단순한 패턴입니다. 하나의 작업을 순차적인 단계로 분해하고, 앞 단계의 출력이 다음 단계의 입력이 되죠. "번역 → 문법 교정 → 톤 조정"처럼 파이프라인이 명확한 작업에 적합합니다.

이 패턴에서 눈여겨볼 점은 각 단계 사이에 검증 게이트를 넣을 수 있다는 겁니다. 앞 단계의 출력이 기준을 충족하는지 확인하고, 충족하지 않으면 다시 돌아갑니다. 에이전트 팀에서는 훅의 TaskCompleted 이벤트로 구현할 수 있습니다.

라우팅

입력을 분석해서 적절한 처리 경로로 보내는 패턴입니다. 분류기 역할의 에이전트가 작업 유형을 판단하고, 그에 맞는 전문 에이전트에게 라우팅하죠. 고객 문의를 "기술 지원", "결제 문의", "일반 문의"로 분류해서 각각 다른 에이전트가 처리하는 식입니다.

에이전트 팀에서 팀 리드가 작업을 분해하고 적절한 팀원에게 할당하는 과정이 이 라우팅 패턴에 해당하고, 라우팅의 정확도가 전체 시스템의 성능을 좌우합니다.

병렬화

독립적인 작업을 동시에 실행하는 패턴입니다. Anthropic은 두 가지 변형을 구분합니다. 분할(Sectioning)은 작업을 독립적인 하위 작업으로 나눠 병렬 처리하는 것이고, 투표(Voting)는 동일한 작업을 여러 에이전트가 각각 수행한 뒤 결과를 집계하는 겁니다.

분할은 직관적입니다. 프론트엔드 코드 분석과 백엔드 코드 분석을 동시에 돌리면 되니까요. 투표는 덜 직관적이지만 강력합니다. 코드 리뷰를 세 명의 에이전트에게 각각 시키면, 한 명이 놓치는 문제를 다른 에이전트가 잡아낼 확률이 높아지죠. Addy Osmani(구글 크롬 팀)도 자신의 블로그에서 에이전트 팀의 핵심 사용 사례로 "경쟁 가설 디버깅"을 꼽았습니다. 버그 원인에 대한 서로 다른 가설을 여러 에이전트가 동시에 검증하는 방식입니다.

오케스트레이터-워커

중앙의 오케스트레이터가 작업을 동적으로 분해하고 워커에게 위임하는 패턴입니다. 프롬프트 체이닝과 달리 분해 결과를 미리 정의하지 않고, 오케스트레이터가 작업을 분석한 뒤 "이 작업에는 이런 하위 작업들이 필요하겠다"고 판단해서 워커를 배정합니다.

에이전트 팀의 기본 구조가 바로 이 패턴입니다. 팀 리드가 오케스트레이터, 팀원이 워커죠. Anthropic 가이드의 설명을 빌리면, "필요한 세부 작업을 미리 예측할 수 없는 복잡한 문제"에 이 패턴이 최적입니다.

평가자-최적화기

한 에이전트가 결과물을 생성하고, 다른 에이전트가 그것을 평가하고, 평가 결과를 바탕으로 다시 개선하는 루프입니다. 이 글의 후반부에서 다룰 "검증-수정 루프"의 이론적 기반이기도 합니다.

Anthropic 가이드에서는 이렇게 설명합니다. "LLMs generally perform better when each consideration is handled by a separate LLM call." 하나의 LLM에게 생성과 평가를 동시에 시키는 것보다, 생성 전문가와 평가 전문가를 분리하는 게 더 나은 결과를 만들어냅니다. 사람 조직에서도 마찬가지죠. 코드를 작성한 사람이 자기 코드를 리뷰하는 것보다, 다른 사람이 리뷰하는 게 효과적인 것과 같은 원리입니다.

실제 에이전트 팀을 설계할 때는 이 다섯 가지 패턴을 단독으로 쓰기보다 조합해서 씁니다. 예를 들어, 전체 작업은 오케스트레이터-워커로 분해하고, 각 워커의 산출물은 평가자-최적화기 루프를 거치고, 서로 독립적인 워커들은 병렬화로 동시에 실행하는 식입니다.

역할 전문화, 어떤 팀원이 필요한가

멀티에이전트 시스템의 성패를 가르는 첫 번째 결정은 "어떤 역할의 에이전트를 만들 것인가"입니다. LLM 기반 멀티에이전트 소프트웨어 공학에 대한 ACM TOSEM 문헌 조사(arXiv 2404.04834)에 따르면, 역할 기반 협력이 16개 설계 패턴 중 가장 많이 쓰이는 패턴입니다. 역할을 제대로 나누지 못하면 나머지 설계가 모두 무너지게 되죠.

도메인 전문가와 형식 전문가의 분리

역할 설계의 첫 번째 원칙은 "무엇을 아는 에이전트"와 "어떻게 표현하는 에이전트"를 분리하는 겁니다.

도메인 전문가는 특정 분야의 지식과 판단 기준을 가진 에이전트입니다. 보안 감사, 성능 분석, 아키텍처 설계 에이전트 등이 여기에 해당하고, 이들의 프롬프트에는 해당 도메인의 평가 기준, 체크리스트, 핵심 원칙이 들어갑니다.

형식 전문가는 산출물의 품질과 형태를 다듬는 에이전트입니다. 문서 편집, 코드 포매터, 테스트 작성 에이전트 등이죠. 이들은 도메인 지식보다는 산출물의 형식적 완성도에 집중합니다.

이 분리가 왜 중요한지 예를 들어보겠습니다. "경쟁사 분석 리포트 작성"이라는 작업을 하나의 에이전트에게 맡기면, 그 에이전트는 조사도 하고, 분석도 하고, 글도 쓰고, 형식도 맞춰야 합니다. 컨텍스트 윈도우에 모든 역할의 지침이 동시에 들어가서 서로 간섭하게 되죠. 반면 researcher 에이전트가 데이터를 수집하고, analyst 에이전트가 분석 프레임워크를 적용하고, editor 에이전트가 리포트를 작성하면, 각 에이전트의 컨텍스트가 깔끔해지고 추론 품질이 올라갑니다.

Addy Osmani도 같은 취지로 이렇게 정리했습니다. "LLM은 컨텍스트가 확장될수록 성능이 저하됩니다. 전문화된 범위를 갖춘 각 에이전트에게 깔끔한 컨텍스트를 제공하면 더 나은 추론이 가능합니다."

핵심 역할 아키타입

여러 멀티에이전트 프레임워크와 연구를 종합하면, 반복적으로 등장하는 역할 아키타입이 있습니다.

Director/Coordinator는 전체 전략을 수립하고 작업 우선순위를 결정합니다. 에이전트 팀의 팀 리드가 이 역할이고, 높은 추론 능력이 필요하니 Opus급 모델을 씁니다.

Researcher/Explorer는 정보 탐색과 수집을 맡습니다. 웹 검색, 파일 분석, 코드베이스 탐색 같은 작업이죠. 깊은 추론보다 빠른 반복이 중요해서 Haiku급으로 충분할 때가 많습니다.

Worker/Implementer가 실제 구현을 합니다. 코드 작성, 문서 작성, 데이터 가공 같은 실무 작업이고, Sonnet급이 비용과 품질의 균형점입니다.

QA/Reviewer는 산출물 검증입니다. 코드 리뷰, 테스트 실행, 품질 기준 충족 확인을 맡고요. 수락 기준에 따라 PASS/FAIL만 판정하면 Sonnet급으로 되지만, 정성적 판단까지 필요하면 Opus급이 안전합니다.

Support/Fixer는 QA가 발견한 문제를 수정합니다. Worker와 비슷하지만 기존 산출물을 고치는 데 특화되어 있고, 최소한의 변경으로 문제를 풀어야 하니 Sonnet 이상이 맞습니다.

MetaGPT가 이 패턴의 대표적인 사례입니다. Product Manager, Architect, Engineer, QA Engineer 네 가지 역할을 분리하고, 표준 운영 절차를 각 역할에 구체화했죠. 역할 간 통신은 publish-subscribe 방식으로 필터링해서, 각 에이전트가 자기에게 관련된 메시지만 받도록 했습니다.

동적 팀 구성, 작업에 따라 팀을 바꾼다

같은 도구를 가진 에이전트라도 작업에 따라 최적의 팀 구성은 달라집니다. "코드 리팩토링"과 "경쟁사 분석"에 같은 팀을 투입하는 건 비효율적이죠. 이 문제를 학술적으로 접근한 것이 DyLAN(Dynamic LLM-Agent Network) 프레임워크입니다.

DyLAN의 핵심 아이디어는 두 단계입니다. 첫 번째 단계에서 여러 에이전트 조합을 시험해보고, 각 에이전트의 기여도를 Agent Importance Score라는 비지도 지표로 측정합니다. 두 번째 단계에서 해당 작업 유형에 가장 기여도가 높은 에이전트들로 팀을 구성하고요. COLM 2024에서 발표된 실험 결과에 따르면, 이런 팀 최적화만으로 MMLU 벤치마크에서 최대 25%의 절대 성능 향상을 얻었습니다.

이것을 Claude Code 에이전트 팀에 적용하는 방법은 단순합니다. 사용자가 자연어로 작업을 지시하면서, 원하는 팀 구성을 함께 설명하면 됩니다. "인증을 JWT로 리팩토링해줘. architect가 전략을 잡고, implementer 두 명이 병렬로 구현하고, reviewer가 검증하는 팀으로 진행해"라고 말하면, 팀 리드가 그 구성대로 팀을 만들고 실행합니다. 팀 구성을 따로 지정하지 않으면 팀 리드가 작업을 분석해서 알아서 팀을 구성하고요.

DyLAN의 "작업 유형에 따라 최적의 팀이 달라진다"는 원리를 참고하면, 작업을 지시할 때 어떤 팀 구성을 요청할지 감을 잡을 수 있습니다. 아래는 필자의 구성안이며, 실제 최적 구성은 프로젝트 특성과 팀의 경험에 따라 달라집니다.

코드 리팩토링 작업이라면, architect가 전략을 수립하고, implementer 두 명이 병렬로 모듈별 리팩토링을 수행하고, reviewer가 검증하는 4명 구성이 효과적입니다.

리서치/분석 작업이라면, researcher 세 명이 서로 다른 소스에서 병렬로 정보를 수집하고, analyst가 분석 프레임워크에 따라 정리하고, writer가 최종 리포트를 작성하는 5명 구성이 적합하고요.

버그 수정 작업이라면, explorer가 관련 코드를 탐색하고, debugger가 원인을 분석하고, fixer가 수정하고, tester가 검증하는 4명 구성이 맞습니다.

팀 리드에게 맡길 수도, 직접 지정할 수도 있다는 게 포인트입니다. 처음에는 팀 리드에게 맡겨보고, 결과를 보면서 "다음에는 reviewer를 추가해야겠다"고 조정해가는 게 현실적인 접근법입니다.

여기서 중요한 점이 있습니다. Claude Code 공식 문서에서 권장하는 최적 팀 크기는 3~5명이고, 팀원당 5~6개 작업이 적정 수준입니다. 이 이상으로 팀을 키우면 조율 오버헤드가 급격히 증가하거든요. 에이전트 수가 늘어날수록 조율 복잡도는 선형이 아니라 지수적으로 증가한다는 MAST 프레임워크(arXiv 2503.13657)의 분석이 이를 뒷받침합니다.

DyLAN에서 하나 더 배울 게 있습니다. 조기 종료(early stopping) 메커니즘인데, 에이전트들의 답변이 충분히 수렴하면 추가 라운드 없이 종료하는 방식입니다. 불필요한 토큰 소비를 줄이는 장치죠. 에이전트 팀 설계에서도 "언제 멈출 것인가"를 분명히 정해두는 게 비용 관리의 관건입니다.

스카우트 패턴: 에이전트가 팀을 설계한다

DyLAN처럼 여러 조합을 실험하는 대신, 더 실용적인 접근법이 있습니다. 코드베이스를 먼저 탐색하는 스카우트 에이전트를 두는 겁니다. 사람이 "이 작업에는 architect와 implementer가 필요하겠다"고 직접 판단하는 대신, Opus급 스카우트를 관련 코드 영역에 투입해서 "이 코드의 구조와 작업 내용을 보니, 이런 역할의 에이전트가 필요하다"는 제안을 받는 구조입니다.

중요한 건 고정된 에이전트 카탈로그에서 고르지 않는다는 점입니다. architect, implementer, reviewer 같은 일반적인 역할 목록은 참고용일 뿐이고, 스카우트가 실제 코드를 보고 그 프로젝트에 맞는 역할을 설계합니다. 같은 "인증 리팩토링"이라도 Express 기반 모놀리스와 Next.js 기반 마이크로서비스에서는 팀 구성이 달라야 하니까요.

실제로 스카우트를 쓰는 방법은 간단합니다. 에이전트 팀에서 사용자가 대화하는 상대는 처음부터 끝까지 팀 리드 하나뿐입니다. 별도의 프롬프트 창이 열리거나, 팀원에게 직접 지시하는 과정은 없습니다. 처음 작업을 지시할 때 스카우트 요청을 함께 포함하면 됩니다.

인증 시스템을 JWT로 리팩토링해줘. 팀으로 진행해.
먼저 src/auth/와 src/middleware/ 코드를 분석해서 어떤 팀원이 필요한지 제안해줘.
제안을 보여주고, 내가 확인한 뒤에 실행해줘.

이렇게 한 번에 말하면 팀 리드가 스카우트 역할의 에이전트를 투입해서 코드를 분석하고, "이 구조라면 architect 1명과 implementer 2명이 필요합니다"같은 제안을 사용자에게 보여줍니다. 사용자가 확인하면 그때 팀을 구성하고 실행을 시작하죠. 중간에 개입하고 싶으면 같은 대화창에서 팀 리드에게 말하면 됩니다. "implementer한테 DB 스키마는 건드리지 말라고 전달해줘"라고 하면 팀 리드가 해당 팀원에게 메일박스로 메시지를 전달합니다. 구체적인 워크플로는 뒤의 "실전 가이드" 섹션에서 다룹니다.

에이전트 간 통신, 메시지 패싱과 블랙보드

에이전트들이 어떻게 정보를 교환하는지가 시스템의 성격을 결정합니다. 크게 두 가지 접근법이 있습니다.

메시지 패싱

에이전트가 다른 에이전트에게 직접 메시지를 보내는 방식입니다. 보내는 쪽이 받는 쪽을 알아야 하고, 메시지의 형식과 프로토콜이 정의되어 있어야 하죠. Claude Code 에이전트 팀의 메일박스가 이 방식입니다.

장점은 통신이 명시적이라 추적이 쉽다는 겁니다. 누가 누구에게 무슨 정보를 보냈는지 로그로 남으니까요. 단점은 에이전트 수가 늘어나면 통신 경로가 복잡해집니다. N명의 에이전트가 있으면 최대 N(N-1)/2개의 통신 채널이 생기거든요.

블랙보드 패턴

모든 에이전트가 하나의 공유 저장소에 정보를 읽고 씁니다. 에이전트는 다른 에이전트를 직접 알 필요가 없고, 공유 저장소의 상태 변화에 반응하죠. 2025년 arXiv에 발표된 블랙보드 아키텍처 연구(arXiv 2507.01701, 프리프린트)가 이 패턴을 LLM 멀티에이전트에 적용한 사례입니다.

장점은 에이전트 간 결합도가 낮다는 겁니다. 새로운 에이전트를 추가해도 기존 에이전트를 수정할 필요가 없으니까요. 단점은 경쟁 조건이 발생할 수 있다는 점입니다. 두 에이전트가 동시에 같은 데이터를 수정하면 충돌이 일어납니다.

Claude Code의 하이브리드 구조

에이전트 팀은 두 패턴을 결합합니다. 태스크 리스트가 블랙보드 역할을 하고, 모든 팀원이 공유 태스크 리스트를 보면서 거기서 작업을 가져갑니다. 동시에 메일박스를 통한 직접 메시지도 지원하죠. 팀원 A가 팀원 B에게 "이 파일은 수정하지 마세요, 제가 작업 중입니다"라고 직접 알릴 수 있습니다.

Nicholas Carlini가 16개의 Claude 인스턴스로 C 컴파일러를 만든 사례도 블랙보드 패턴의 변형입니다. current_tasks/ 디렉토리에 파일을 만들어서 작업을 할당하고, 각 에이전트가 해당 디렉토리를 확인해서 자기 작업을 가져갔습니다. 파일 시스템이 블랙보드 역할을 한 셈이죠. 16개 에이전트, 약 2,000회 Claude Code 세션, 10만 줄의 Rust 코드, $20,000의 비용. 이 규모의 협업이 가능했던 건 에이전트 간 직접 통신이 아니라, 공유 디렉토리를 매개로 느슨하게 결합된 블랙보드 구조 덕분입니다.

실제 팀을 설계할 때는 두 가지 질문을 던져보면 됩니다. "에이전트 A의 산출물을 에이전트 B가 반드시 알아야 하는가?" 예라면 메시지 패싱이 적합합니다. "에이전트들이 전체 작업 상태를 공유해야 하는가?" 예라면 블랙보드가 적합하고요. 대부분의 실전 시나리오에서는 둘 다 필요합니다.

검증-수정 루프, 자동으로 품질을 잡는 구조

멀티에이전트 시스템에서 가장 가치 있는 패턴이 검증검증-수정 루프 (Quality Gate) 흐름도-수정 루프입니다. 사람 조직에서 코드 리뷰 → 수정 → 재리뷰 사이클이 코드 품질을 보장하듯, 에이전트 시스템에서도 자동화된 검증-수정 루프가 산출물의 품질을 결정합니다.

다음 그림은 훅 기반의 자동 검증-수정 루프가 어떻게 동작하는지 보여줍니다.

검증-수정 루프 (Quality Gate) 흐름도

Worker가 코드를 작성하고 작업 완료를 시도하면, TaskCompleted Hook이 자동으로 테스트와 린트를 실행합니다. 검증을 통과하면(종료 코드(exit code) 0) 작업이 완료되고, 실패하면(종료 코드 2) 피드백과 함께 Worker에게 수정을 요청하는 루프가 자동으로 돌아갑니다.

품질 게이트(Quality Gate) 개념

품질 게이트는 "이 기준을 충족하지 않으면 다음 단계로 넘어가지 않는다"는 관문입니다. PR 리뷰에서 CI가 통과해야 머지할 수 있는 것과 같은 원리죠. Claude Code의 훅 시스템에서 이걸 가능하게 하는 메커니즘이 종료 코드 2입니다.

구체적으로 어떻게 설정하는지 보겠습니다. 프로젝트의 .claude/settings.json에 이런 훅을 추가합니다.

{
  "hooks": {
    "TaskCompleted": [
      {
        "type": "command",
        "command": "npm test"
      }
    ]
  }
}

이 설정 하나면, 팀원이 작업을 완료했다고 표시할 때마다 자동으로 npm test가 실행됩니다. 테스트가 통과하면(종료 코드 0) 작업이 완료되고, 실패하면(종료 코드 2) 팀원에게 "테스트가 실패했으니 수정하라"는 피드백이 자동으로 전달됩니다.

여기서 중요한 건 종료 코드 2입니다. "작업을 완료로 표시하지 말고, 이 피드백을 반영해서 계속 작업하라"는 신호거든요. TeammateIdle 훅에서도 마찬가지입니다. 팀원이 할 일이 없다고 판단했을 때 lint나 테스트를 실행하고, 실패하면 종료 코드 2와 함께 에러 메시지를 반환하면 해당 팀원이 문제를 수정합니다.

이것이 자동화되면 어떤 일이 벌어지는지 구체적으로 살펴보겠습니다. Worker 에이전트가 코드를 작성하고, 작업 완료를 시도합니다. TaskCompleted 훅이 발동해서 pytest를 실행하는데, 테스트가 실패합니다. 훅이 종료 코드 2와 함께 "테스트 3개 실패: test_auth.py line 42, test_api.py line 87, test_db.py line 15"라는 메시지를 반환하죠. Worker는 완료 처리가 차단되고, 피드백을 받아서 실패한 테스트를 수정합니다. 다시 완료를 시도하면, 이번에는 모든 테스트가 통과하고 작업이 완료로 표시됩니다.

사람이 개입하지 않아도 이 루프가 자동으로 돌아갑니다. C 컴파일러 프로젝트에서 Nicholas Carlini가 강조한 교훈이 이것이었습니다. "자율 에이전트는 검증자가 거의 완벽해야 합니다." CI 파이프라인이 그 역할을 했고요. 검증자가 정확할수록 에이전트의 자율성을 높여도 안전합니다.

훅 핸들러의 세 가지 유형

검증 로직을 어떤 형태로 구현할지는 작업의 성격에 따라 다릅니다. Claude Code 훅은 세 가지 핸들러 타입을 지원합니다.

command 핸들러는 bash 스크립트를 실행합니다. 테스트 실행, 린트 체크, 빌드 검증 같은 결정적인 검증에 적합하고, 결과가 명확하고 재현 가능합니다.

prompt 핸들러는 Haiku 모델로 단일 턴 평가를 수행합니다. "이 코드가 보안 원칙을 준수하는지 확인하라"처럼 정성적 판단이 필요한 검증에 적합하죠. 빠르고 비용이 낮습니다.

agent 핸들러는 서브에이전트로 도구를 사용하는 검증을 수행합니다. 파일을 읽고, 코드를 분석하고, 여러 단계의 판단이 필요한 복잡한 검증에 적합합니다.

실전에서는 이 세 유형을 계층적으로 조합합니다. 먼저 command 핸들러로 빠르게 걸러내고(테스트 통과?), 통과하면 prompt 핸들러로 정성적 검증을 하고(코드 스타일 준수?), 필요하면 agent 핸들러로 심층 분석을 하는 식이죠(아키텍처 원칙과 일치?). 가벼운 검증부터 무거운 검증으로 올라가는 캐스케이드 구조입니다.

수락 기준을 먼저 정한다

검증-수정 루프가 효과를 내려면 "무엇을 검증할 것인가"가 분명해야 합니다. 여기서 등장하는 개념이 수락 기준입니다. 팀이 실행을 시작하기 전에, 측정 가능한 기준을 목록으로 만들어두는 겁니다.

수락 기준은 처음 작업을 지시할 때 프롬프트에 함께 적어주면 됩니다. "좋은 코드를 작성해줘"는 수락 기준이 아닙니다. 이렇게 적어야 합니다.

인증을 JWT로 전환해줘. 팀으로 진행해.

수락 기준:
- JWT 토큰 생성과 검증이 구현될 것
- 기존 테스트 52개가 모두 통과할 것
- 미들웨어가 만료된 토큰을 401로 거부할 것

주관적 판단이 아니라 예/아니오로 답할 수 있는 기준이어야 합니다. 팀 리드는 이 기준을 qa 에이전트에게 전달하고, qa 에이전트는 이 기준만을 근거로 PASS/FAIL을 판정합니다. 증거 없는 PASS는 허용되지 않습니다. "코드를 봤는데 괜찮아 보입니다"가 아니라, "test_jwt_validation.py의 7개 테스트가 모두 통과했으므로 AC-3은 PASS입니다"처럼 구체적인 근거가 있어야 합니다. 이렇게 하면 검증이 재현 가능해지고, 다른 사람이나 다른 에이전트가 같은 기준으로 검증해도 동일한 결과가 나옵니다.

수락 기준을 프롬프트에 적지 않으면 팀 리드가 자체적으로 기준을 설정합니다. 동작은 하지만, 사용자가 의도한 것과 팀 리드가 판단한 것이 다를 수 있습니다. 중요한 작업일수록 직접 기준을 명시하는 게 안전합니다.

루프에는 반드시 상한선을 둡니다. 최대 3라운드가 적절합니다. 동일한 오류가 3회 반복되면, 에이전트가 해결할 수 없는 구조적 문제일 가능성이 높습니다. 이때는 루프를 즉시 중단하고 사용자에게 보고해야 합니다. 4라운드, 5라운드를 돌리는 건 토큰만 태울 뿐입니다.

모델 배정 전략, 적재적소에 맞는 모델을 배치한다

멀티에이전트 시스템의 비용을 예측 가능하게 만드는 건 모델 배정 전략입니다. 모든 에이전트에 Opus를 배정하면 품질은 높겠지만 비용이 감당이 안 됩니다. 모든 에이전트에 Haiku를 배정하면 비용은 낮겠지만 복잡한 추론이 필요한 작업에서 실패하고요.

다음 그림은 역할별 모델 배정의 캐스케이드 패턴을 보여줍니다.

모델 배정 전략 캐스케이드 패턴

Opus는 전체 요청의 3~5%만 처리하지만 전략 수립과 최종 검증 같은 고난도 추론을 담당합니다. Sonnet은 25~30%의 실무 구현 작업을, Haiku는 60~70%의 탐색과 분류 작업을 처리하여 비용과 성능의 균형을 잡습니다.

역할별 모델 매핑 원칙

Caylent의 분석에 따르면, 최적의 비용 구조는 캐스케이드 패턴입니다. 전체 요청의 60~70%를 Haiku가 처리하고, 25~30%를 Sonnet이 처리하고, 3~5%만 Opus가 처리하는 구조죠. 이 비율을 역할에 매핑하면 다음과 같습니다.

Opus가 담당해야 하는 역할은 전체 전략 수립(Director), 복잡한 의사결정, 산출물 최종 검증(QA)입니다. 요청 빈도가 낮지만, 한 번의 판단 오류가 전체 작업에 영향을 주기 때문에 비용을 아끼면 안 되는 곳입니다.

Sonnet이 담당해야 하는 역할은 실무 구현(Worker), 문서 작성, 코드 수정(Support)입니다. 추론 능력과 실행 속도의 균형이 필요한 곳이고, 비용 대비 품질의 균형점이죠.

Haiku가 담당해야 하는 역할은 정보 탐색(Researcher/Explorer), 분류, 데이터 추출, 간단한 검증입니다. 반복 횟수가 많고 각 요청의 복잡도가 낮아서, 빠른 응답 시간이 더 중요합니다.

Claude Code에서 이것을 구현하는 방법은 간단합니다. .claude/agents/ 디렉토리에 커스텀 에이전트 파일을 만들고, 상단의 YAML frontmatter에서 model 필드를 지정하면 됩니다. 예를 들어, .claude/agents/explorer.md 파일을 이렇게 만듭니다.

---
model: haiku
tools: Read, Glob, Grep
---
당신은 코드베이스 탐색 전문가입니다.
지정된 영역의 파일 구조, 패턴, 의존성을 분석하고 보고합니다.
코드를 수정하지 않습니다.

같은 방식으로 worker는 model: sonnet, reviewer는 model: opus로 설정합니다. 이렇게 역할별로 모델을 고정해두면 총 비용을 사전에 추정할 수 있습니다.

opusplan 모드

Claude Code에는 opusplan이라는 특수 모델 모드가 있습니다. 계획 단계에서는 Opus를 사용하고, 실행 단계에서는 자동으로 Sonnet으로 전환하죠. 하나의 에이전트 안에서 단계별로 모델이 바뀌는 구조입니다.

Director/Worker를 분리하지 않고도 비용을 최적화할 수 있는 방법이기도 합니다. 팀 리드에 opusplan을 적용하면, 작업 분해와 전략 수립(Opus)은 높은 품질로 수행하고, 직접적인 코드 작성이나 파일 수정(Sonnet)은 비용 효율적으로 처리하게 되죠.

비용 절감 실측

Caylent의 분석을 기준으로 계산해보면, 모든 에이전트에 Opus만 쓰는 것 대비 캐스케이드 패턴을 적용하면 평균 요청 비용이 50~60% 절감됩니다. 5명 팀에서 각각 10개 작업을 수행한다고 가정하면, 50개 작업 중 30~35개는 Haiku, 12~15개는 Sonnet, 2~3개만 Opus가 처리하는 구조죠.

다만 주의할 점이 있습니다. 비용 절감을 위해 모델을 낮추면 실패율이 올라갈 수 있거든요. 실패한 작업을 재시도하는 비용까지 포함하면, 처음부터 적정 모델을 배정하는 게 오히려 총비용이 낮을 수 있습니다. "너무 싸게 가려다 더 비싸지는" 함정을 피하려면, 각 역할의 실패율을 모니터링하고 실패율이 일정 수준을 넘으면 모델을 한 단계 올리는 적응형 전략이 필요합니다.

실패 패턴, 멀티에이전트는 왜 무너지는가

멀티에이전트 시스템을 설계할 때 가장 과소평가되는 것이 실패 모드입니다. 에이전트 한 명이 잘 동작하니까 여러 명을 붙이면 더 잘 되겠지, 하는 기대는 대부분 빗나갑니다. 2025년 arXiv에 발표된 MAST 프레임워크(arXiv 2503.13657)는 멀티에이전트 LLM 시스템의 실패 원인을 체계적으로 분류했는데, 프로덕션 환경에서의 실패율이 41~86.7%입니다.

세 가지 실패 카테고리

첫 번째는 시스템 설계 문제, 아키텍처 자체의 결함입니다. 역할 정의가 모호해서 에이전트들이 같은 작업을 중복 수행하거나, 아무도 처리하지 않는 작업이 생기는 경우죠. "사양 모호성"이라고도 하는데, 에이전트가 자기 역할을 오해석하고 범위를 벗어난 행동을 합니다.

해법은 역할 경계를 프롬프트에 분명하게 정의하는 겁니다. "당신은 코드 리뷰만 담당합니다. 코드를 직접 수정하지 마세요. 문제를 발견하면 태스크 리스트에 수정 작업을 등록하세요." 이렇게 무엇을 해야 하는지뿐 아니라, 무엇을 하면 안 되는지까지 명시해야 합니다.

두 번째는 에이전트 간 불일치, 에이전트의 행동이 서로 충돌하는 상황입니다. MAST 프레임워크(arXiv 2503.13657)의 분석에 따르면, 멀티에이전트 시스템 오류의 67%가 개별 에이전트의 결함이 아니라 에이전트 간 상호작용에서 발생합니다. 에이전트 A가 파일을 수정하는 동안 에이전트 B가 같은 파일을 다른 방향으로 수정하거나, A의 산출물을 B가 잘못 해석하는 경우죠.

에이전트 팀에서는 메일박스를 통한 명시적 조율이 이 문제를 완화합니다. 하지만 근본적인 해결책은 작업 의존성을 태스크 리스트에서 분명히 정의하는 겁니다. "작업 B는 작업 A가 완료된 후에만 시작 가능"이라는 의존성을 설정하면, 동시 수정으로 인한 충돌을 구조적으로 방지할 수 있습니다.

세 번째는 작업 검증 문제입니다. 산출물의 정확성을 판단하지 못하는 상황이죠. 검증 메커니즘이 없거나 부실하면 잘못된 산출물이 다음 단계로 전달되고, 오류가 전파됩니다. 앞서 다룬 검증-수정 루프가 이 문제를 해결하는 핵심 패턴입니다.

조율 오버헤드

MAST 프레임워크가 지적하는 또 하나의 핵심 문제는 조율 오버헤드입니다. 에이전트 수가 증가할수록 조율에 필요한 토큰과 시간이 비선형적으로 증가하거든요. 3명 팀에서 5명 팀으로 늘리면 조율 비용은 거의 두 배가 됩니다.

이것을 "툴-조율 트레이드오프"라고 합니다. 멀티에이전트로 갈수록 에이전트당 사용할 수 있는 토큰 예산이 줄어들어서, 복잡한 도구 사용 능력이 저하될 수 있습니다. 쉽게 말해서, 혼자서 하면 충분히 할 수 있는 작업을 팀으로 나누면 오히려 못하는 경우가 생기는 거죠.

그래서 Claude Code 공식 문서의 권장사항이 "3~5명"인 겁니다. 이 숫자는 직감이 아니라, 조율 오버헤드와 병렬 처리 이득의 균형점에서 도출된 결과입니다.

실패를 줄이는 설계 원칙

MAST 프레임워크와 실전 사례를 종합하면, 실패를 줄이는 핵심 원칙이 세 가지로 정리됩니다.

첫째, 역할 경계를 명확히 하되, 겹치는 영역을 의도적으로 두지 않습니다. 모호한 회색 지대는 중복 작업과 충돌의 온상이거든요.

둘째, 에이전트 수를 최소화합니다. "이 작업에 꼭 별도 에이전트가 필요한가?"를 반드시 질문해야 합니다. Anthropic의 "start simple" 원칙이죠. 단일 에이전트로 충분한 작업에 멀티에이전트를 투입하지 않습니다.

셋째, 검증 메커니즘을 반드시 포함합니다. 검증 없는 멀티에이전트는 오류를 증폭시키는 시스템이 됩니다.

실전 가이드: 팀을 조립하고 실행하는 6단계

지금까지 다룬 원칙들을 하나의 워크플로로 통합하면, 6단계의 실전 방법론이 됩니다. 에이전트 팀을 사용하려면 먼저 활성화가 필요합니다. settings.json에 환경변수를 설정하면 됩니다.

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

이 설정 하나로 에이전트 팀 기능이 활성화됩니다. 사용자가 별도의 명령을 입력할 필요는 없습니다. 자연어로 작업을 지시하면 팀 리드가 알아서 팀을 만들고, 팀원 간 메시지를 주고받게 하고, 작업이 끝나면 팀을 해산합니다.

가장 간단한 시작

6단계 방법론을 설명하기 전에, 가장 간단한 사용법부터 보겠습니다. 환경변수를 설정한 뒤 Claude Code를 열고, 이렇게 말하면 됩니다.

이 프로젝트의 인증 시스템을 세션 기반에서 JWT로 바꿔줘.
팀으로 진행하고, 다 끝나면 테스트도 돌려줘.

이것만으로 팀 리드가 알아서 코드를 분석하고, 필요한 팀원을 만들고, 작업을 분배하고, 결과를 검증합니다. 서브에이전트를 쓸 때처럼 "어떤 에이전트를 호출할지" 고민할 필요가 없습니다. 팀 구성과 역할 분배는 팀 리드가 판단합니다.

물론 이렇게 맡기기만 하면 팀 리드의 판단에 전적으로 의존하게 됩니다. 팀 구성을 직접 제어하고 싶거나, 더 복잡한 작업에서 품질을 확보하고 싶다면, 아래의 6단계 방법론이 도움이 됩니다. 6단계를 반드시 순서대로 밟아야 하는 건 아닙니다. 작업의 복잡도에 따라 필요한 단계만 골라서 쓰면 되고, 경험이 쌓이면서 자연스럽게 체계가 잡힙니다.

1단계: 작업 분석과 범위 확정

첫 번째로 할 일은 "이 작업에 정말 팀이 필요한가"를 판단하는 겁니다. 기준은 단순합니다. 에이전트 간 의존성이 있는가? 없다면 서브에이전트로 충분하고, 있다면 에이전트 팀을 고려합니다.

팀이 필요하다고 판단되면, 작업과 관련된 코드베이스 영역을 식별합니다. 인증 리팩토링이라면 src/auth/, src/middleware/, tests/auth/가 관련 영역이겠죠. 이 단계에서 범위를 명확히 잡아야 다음 단계가 효율적으로 돌아갑니다. 관련 없는 영역까지 포함하면 스카우트가 불필요한 에이전트를 제안하고, 관련 영역을 빠뜨리면 나중에 팀 구성을 수정해야 합니다.

2단계: 코드베이스 스카우트

앞서 "동적 팀 구성" 섹션에서 소개한 스카우트 패턴을 여기서 실행합니다. 1단계에서 식별한 각 코드 영역에 스카우트 에이전트를 투입합니다.

스카우트의 임무는 두 가지입니다. 해당 영역의 코드를 읽고 현재 상태를 파악하는 것, 그리고 이 작업에 필요한 에이전트를 구체적으로 제안하는 것. 스카우트는 Opus급 모델을 쓰고, 코드를 수정하지 않습니다. 읽기 전용입니다.

여러 영역이 있으면 스카우트를 병렬로 실행합니다. 예를 들어, 인증 리팩토링이라면 src/auth/ 영역을 탐색하는 스카우트와 src/middleware/ 영역을 탐색하는 스카우트를 동시에 띄우는 식입니다. 이름은 자유롭게 붙이면 됩니다. 각 스카우트는 맡은 영역을 탐색하고 필요한 역할을 제안합니다. 스카우트에게 기대하는 출력은 현재 상태 요약(파일 구조, 기존 패턴, 주의사항), 제안 에이전트 목록(이름, 역할, 구체적 작업, 참고 파일), 영역별 제약사항, 이 세 가지입니다.

"테스트 커버리지 올려줘"처럼 코드 탐색 없이도 팀 구성이 명확한 작업이라면, 이 단계를 건너뛰고 바로 3단계로 가면 됩니다.

3단계: 팀 구성과 수락 기준 확정

스카우트 보고서를 취합해서 최종 팀을 구성합니다. 여기서 네 가지를 결정합니다.

첫째, 에이전트 역할을 확정합니다. 여러 스카우트가 비슷한 역할을 제안했으면 합치고, 빠진 역할이 있으면 추가합니다. 이때 qa는 무조건 포함합니다. support는 qa가 FAIL을 발견했을 때만 투입되는 대기 역할이지만, 역할 정의는 미리 해둬야 합니다. qa는 검증만 하고 코드를 수정하지 않습니다. support는 qa가 발견한 문제만 수정하고, 범위를 벗어난 변경은 하지 않습니다. qa가 없는 팀은 검증 없이 산출물을 내보내는 파이프라인이 됩니다.

둘째, 의존성 그래프를 설계합니다. 어떤 에이전트가 먼저 끝나야 다음 에이전트가 시작할 수 있는지 결정하는 겁니다. architect → implementer → test-writer 같은 순서죠. 의존성이 없는 에이전트끼리는 병렬 실행이 가능합니다.

셋째, 모델을 배정합니다. 판단이 필요한 역할(architect, qa)에는 Opus, 실행 역할(implementer, support)에는 Sonnet, 탐색 역할(researcher)에는 Haiku. 확신이 없으면 한 단계 높은 모델로 시작하고 나중에 낮추는 게 낫습니다.

넷째, 수락 기준을 정의합니다. 이것이 이 단계에서 가장 중요한 결정입니다. "AC-1: JWT 토큰 생성과 검증 구현", "AC-2: 기존 테스트 전부 통과", "AC-3: 미들웨어에서 만료 토큰 401 거부" 같은 측정 가능한 기준을 목록으로 만듭니다. 이 기준이 5단계 검증의 근거가 됩니다.

4단계: 실행

팀 구성이 확정되면 실행합니다. 팀 리드에게 작업을 지시하면, 팀 리드가 팀을 생성하고, 각 에이전트의 작업을 태스크 리스트에 등록하고, 작업 간 의존성을 설정합니다.

팀 리드가 얼마나 잘하느냐는 사용자가 처음에 주는 지시의 구체성에 달려 있습니다. 단순히 "JWT로 바꿔줘"라고 말하면 팀 리드가 알아서 하긴 하지만, 다음 다섯 가지를 포함해서 지시하면 결과가 훨씬 좋아집니다.

[Context] 이 프로젝트는 Express 기반이고, 현재 세션 기반 인증을 쓰고 있어.
[Goal] src/auth/jwt.ts에 토큰 생성/검증 함수를 구현하고,
       src/middleware/auth.ts의 세션 검증을 JWT 검증으로 교체해줘.
[Reference Files] src/auth/, src/middleware/, tests/auth/ 를 참고해.
[Constraints] DB 스키마는 건드리지 마. tests/ 디렉토리의 기존 테스트 구조는 유지해.
[Output] 완료되면 변경 파일 목록과 테스트 결과를 정리해줘.

실제로 이렇게 대괄호를 쓸 필요는 없습니다. 자연어로 풀어서 한 번에 말하면 됩니다. 요점은 배경(Context), 목표(Goal), 참고 파일(Reference Files), 제약사항(Constraints), 산출물 형태(Output Format), 이 다섯 가지가 지시에 포함되어야 한다는 겁니다. 무엇을 해야 하는지뿐 아니라, 무엇을 하면 안 되는지까지 명시해야 에이전트가 범위를 벗어나지 않습니다.

의존성 없는 에이전트들은 팀 리드가 자동으로 병렬 실행합니다. 의존성이 있으면 선행 에이전트의 결과를 다음 에이전트에 전달하며 순차 실행하고요.

5단계: 검증

qa 에이전트가 3단계에서 정의한 수락 기준을 하나씩 검증합니다. 각 기준에 대해 PASS 또는 FAIL을 판정하고, 판정 근거를 명시합니다. "AC-2: 기존 테스트 전부 통과 → PASS. pytest 실행 결과 52/52 통과"처럼요.

FAIL이 나오면 support 에이전트가 해당 항목만 수정합니다. qa가 플래그하지 않은 부분은 건드리지 않습니다. 수정 후 qa가 다시 검증합니다.

이 루프는 최대 3라운드입니다. 3라운드 후에도 같은 기준이 FAIL이면, 무한 루프에 빠지는 대신 멈추고 보고합니다. 어떤 기준이 실패했는지, 어떤 수정을 시도했는지, 왜 해결이 안 되는지를 정리해서 사용자에게 전달합니다. 여기서부터는 사람이 개입해야 할 영역입니다.

6단계: 정리

모든 수락 기준이 PASS면 결과 보고서를 만들고 팀을 해산합니다. 어떤 에이전트가 무엇을 했는지, 수락 기준 충족 여부, 검증 라운드 수, 수정 이력을 기록합니다. 팀 리드가 각 팀원에게 종료를 알리고 팀을 해산합니다.

이 기록을 남겨두는 이유가 있습니다. 다음에 비슷한 작업을 할 때 참고할 수 있거든요. "저번에 인증 리팩토링을 4명 팀으로 했는데, qa는 Sonnet으로도 충분했다" 같은 교훈이 쌓이면 팀 설계가 점점 정교해집니다.

시나리오: 세션 기반 인증을 JWT로 전환

6단계를 실제 작업에 적용해 보겠습니다. 사용자가 실제로 Claude Code에 입력하는 내용을 중심으로 따라가 봅시다.

1단계: 작업 분석. 세션 기반 인증을 JWT로 전환하는 작업은 auth 모듈, middleware, 테스트가 서로 의존합니다. 에이전트 간 의존성이 명확하므로 에이전트 팀이 적합합니다.

2~3단계: 스카우트와 팀 구성. Claude Code에 이렇게 입력합니다.

세션 기반 인증을 JWT로 전환하려고 해. 팀으로 진행해줘.

먼저 src/auth/, src/middleware/, tests/auth/ 영역을 스카우트해서
현재 구조를 파악하고, 어떤 역할의 팀원이 필요한지 제안해줘.

수락 기준은 이거야:
- JWT 토큰 생성/검증/갱신이 구현될 것
- 기존 auth 테스트가 전부 통과하거나 JWT에 맞게 업데이트될 것
- 미들웨어가 유효한 JWT는 통과시키고 만료/변조된 JWT는 401로 거부할 것
- 기존 API 엔드포인트에 회귀가 없을 것

architect는 Opus로, 나머지는 Sonnet으로 배정해줘.
DB 스키마는 건드리지 마.

이 한 번의 지시로 팀 리드가 스카우트를 실행하고, 코드를 분석하고, 팀을 구성합니다. 스카우트 결과를 바탕으로 팀 리드가 architect, implementer, test-updater, qa 4명의 팀을 구성하고, FAIL 대비로 support를 대기시킵니다. 스카우트가 제안한 역할 중 겹치는 것이 있으면 팀 리드가 알아서 통합합니다.

4단계: 실행. 팀 리드가 팀을 구성한 뒤 자동으로 실행을 시작합니다. architect가 JWT 토큰 전략과 마이그레이션 경로를 설계하고, 그 결과를 받은 implementer가 코드를 구현하고, test-updater가 테스트를 수정합니다. 이 과정에서 사용자는 지켜보기만 해도 됩니다. 중간에 개입하고 싶으면 "architect한테 access 토큰 만료 시간을 15분으로 잡으라고 전달해줘"처럼 자연어로 지시하면 팀 리드가 해당 팀원에게 메시지를 전달합니다.

5단계: 검증. qa가 수락 기준을 하나씩 검증합니다. "pytest 실행 결과 52/52 통과"처럼 구체적인 근거와 함께 PASS/FAIL을 판정하고, FAIL이 나오면 support가 해당 항목만 수정합니다. 이 검증-수정 루프는 최대 3라운드 자동으로 돌아갑니다.

6단계: 정리. 모든 기준이 PASS면 팀 리드가 결과 보고서를 정리하고 팀을 해산합니다.

마무리

Anthropic의 "Building Effective Agents" 가이드는 첫 문장부터 이렇게 시작합니다. "Start simple." 단순하게 시작하라. 멀티에이전트 시스템도 마찬가지입니다.

지금 서브에이전트를 잘 쓰고 있다면, 그것 자체가 잘못된 게 아닙니다. 문제는 서브에이전트의 한계에 부딪혔는데도 더 나은 구조가 있다는 걸 모르고 같은 패턴만 반복하는 상황입니다. 에이전트 간 정보 전달이 병목이 되고, 검증-수정을 수동으로 반복하고, 메인 에이전트의 컨텍스트가 빠르게 소진되는 경험을 하고 있다면, 그때가 에이전트 팀의 개념을 적용할 시점입니다.

이 글에서 다룬 개념들은 Claude Code에 한정되지 않습니다. 오케스트레이션-코레오그래피 하이브리드, 역할 전문화, 검증-수정 루프, 모델 캐스케이드 패턴은 어떤 멀티에이전트 시스템에서든 적용할 수 있는 설계 원칙이죠. LangGraph든 CrewAI든, 아니면 직접 만든 프레임워크든, 핵심은 같습니다.

한 가지만 기억한다면 이겁니다. 팀의 크기를 늘리기 전에, 각 팀원의 역할을 날카롭게 만드는 것이 먼저입니다. 3명이 각자의 역할에 집중하는 팀이, 10명이 서로의 영역을 침범하는 팀보다 항상 낫습니다.

첫 번째 실험은 세 단계면 충분합니다.

첫째, settings.json에 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS를 추가합니다. 둘째, 지금 쓰고 있는 서브에이전트 워크플로 중에서 에이전트 간 정보 전달이 병목인 작업을 하나 골라, Claude Code를 열고 "이 작업을 팀으로 진행해줘"라고 말합니다. 셋째, 팀 리드가 팀을 만들고 작업을 분배하는 과정을 지켜봅니다. 환경변수 설정부터 첫 번째 팀 실행까지 30분이면 충분합니다. 에이전트 두 명이 서로 메시지를 주고받는 것을 처음 보는 순간, "아, 이런 구조가 가능하구나"라는 것을 실감하게 됩니다. 그 감각이 다음 설계의 출발점입니다.

기대했던 수준의 결과가 나오지 않는다면 그때 이 글의 설계 원칙들을 하나씩 적용해보면 됩니다. 역할을 더 세분화하거나, 수락 기준을 명시하거나, 훅으로 자동 검증을 걸거나. 처음부터 완벽한 팀을 설계할 필요는 없습니다.