Claude Code 세션 팀 오케스트레이션

여러 Claude Code 인스턴스가 팀으로 협력하도록 조율합니다. 공유 작업 목록, 에이전트 간 메시징, 중앙 집중식 관리를 지원합니다.

주의:

에이전트 팀은 실험적 기능이며 기본적으로 비활성화되어 있습니다. settings.json 또는 환경 변수에 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS를 추가하여 활성화할 수 있습니다. 에이전트 팀에는 세션 복원, 작업 조율, 종료 동작과 관련된 알려진 제한 사항이 있습니다.

에이전트 팀을 사용하면 여러 Claude Code 인스턴스가 함께 작업하도록 조율할 수 있습니다. 하나의 세션이 팀 리드 역할을 하여 작업을 조율하고, 업무를 할당하며, 결과를 종합합니다. 팀원들은 각자 독립적으로 작업하며, 각각 자체 컨텍스트 윈도우를 가지고, 서로 직접 소통합니다.

서브에이전트와 달리, 서브에이전트는 단일 세션 내에서 실행되며 메인 에이전트에게만 보고할 수 있지만, 에이전트 팀에서는 리드를 거치지 않고 개별 팀원과 직접 상호작용할 수 있습니다.

이 페이지에서 다루는 내용:

에이전트 팀을 사용해야 하는 경우 - 최적의 사용 사례와 서브에이전트와의 비교
팀 시작하기
팀원 제어하기 - 디스플레이 모드, 작업 할당, 위임
병렬 작업 모범 사례

에이전트 팀을 사용해야 하는 경우

에이전트 팀은 병렬 탐색이 실질적인 가치를 제공하는 작업에서 가장 효과적입니다. 전체 시나리오는 사용 사례 예시를 참고하세요. 가장 적합한 사용 사례는 다음과 같습니다:

리서치 및 리뷰: 여러 팀원이 문제의 다양한 측면을 동시에 조사한 후, 서로의 발견 내용을 공유하고 검증할 수 있습니다
새로운 모듈이나 기능: 팀원이 각각 별도의 영역을 담당하여 서로 충돌하지 않습니다
경쟁 가설을 통한 디버깅: 팀원이 서로 다른 가설을 병렬로 테스트하여 더 빠르게 답을 수렴합니다
크로스 레이어 조율: 프론트엔드, 백엔드, 테스트에 걸쳐 변경이 필요한 경우, 각각을 다른 팀원이 담당합니다

에이전트 팀은 조율 오버헤드가 발생하며 단일 세션보다 훨씬 더 많은 토큰을 사용합니다. 팀원이 독립적으로 작업할 수 있을 때 가장 효과적입니다. 순차적 작업, 동일 파일 편집, 또는 많은 의존성이 있는 작업의 경우 단일 세션이나 서브에이전트가 더 효과적입니다.

서브에이전트와의 비교

에이전트 팀과 서브에이전트 모두 작업을 병렬화할 수 있지만, 작동 방식이 다릅니다. 작업자 간 소통이 필요한지에 따라 선택하세요:

Diagram comparing subagent and agent team architectures. Subagents are spawned by the main agent, do work, and report results back. Agent teams coordinate through a shared task list, with teammates communicating directly with each other.

	서브에이전트	에이전트 팀
컨텍스트	자체 컨텍스트 윈도우; 결과가 호출자에게 반환됨	자체 컨텍스트 윈도우; 완전히 독립적
소통	메인 에이전트에게만 결과를 보고	팀원끼리 직접 메시지를 주고받음
조율	메인 에이전트가 모든 작업을 관리	공유 작업 목록을 통한 자체 조율
적합한 용도	결과만 중요한 집중적인 작업	논의와 협업이 필요한 복잡한 작업
토큰 비용	낮음: 결과가 요약되어 메인 컨텍스트로 반환	높음: 각 팀원이 별도의 Claude 인스턴스

결과만 빠르게 보고받으면 되는 집중 작업자가 필요할 때는 서브에이전트를 사용하세요. 팀원들이 발견 내용을 공유하고, 서로의 의견에 이의를 제기하며, 자체적으로 조율해야 할 때는 에이전트 팀을 사용하세요.

에이전트 팀 활성화

에이전트 팀은 기본적으로 비활성화되어 있습니다. 셸 환경 또는 settings.json에서 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 환경 변수를 1로 설정하여 활성화하세요:

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

첫 번째 에이전트 팀 시작하기

에이전트 팀을 활성화한 후, Claude에게 에이전트 팀을 만들도록 지시하고 원하는 작업과 팀 구조를 자연어로 설명하세요. Claude가 팀을 생성하고, 팀원을 생성하며, 프롬프트에 따라 작업을 조율합니다.

이 예시는 세 가지 역할이 서로 독립적이고 대기 없이 문제를 탐색할 수 있어 효과적입니다:

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Create an agent team to explore this from different angles: one
teammate on UX, one on technical architecture, one playing devil's advocate.

여기서 Claude는 공유 작업 목록이 있는 팀을 만들고, 각 관점별 팀원을 생성하고, 문제를 탐색하게 한 후, 발견 내용을 종합하고, 완료 시 팀 정리를 시도합니다.

리드의 터미널에는 모든 팀원과 그들이 진행 중인 작업이 표시됩니다. Shift+Down을 사용하여 팀원을 순환하며 직접 메시지를 보낼 수 있습니다. 마지막 팀원 이후에는 Shift+Down이 다시 리드로 돌아갑니다.

각 팀원을 별도의 분할 패널에서 보고 싶다면 디스플레이 모드 선택을 참고하세요.

에이전트 팀 제어하기

리드에게 원하는 것을 자연어로 지시하세요. 리드가 지시에 따라 팀 조율, 작업 할당, 위임을 처리합니다.

디스플레이 모드 선택

에이전트 팀은 두 가지 디스플레이 모드를 지원합니다:

인프로세스: 모든 팀원이 메인 터미널 내에서 실행됩니다. Shift+Down으로 팀원을 순환하며 직접 메시지를 입력할 수 있습니다. 어떤 터미널에서든 작동하며 추가 설정이 필요 없습니다.
분할 패널: 각 팀원이 자체 패널을 갖습니다. 모든 팀원의 출력을 동시에 볼 수 있으며, 패널을 클릭하여 직접 상호작용할 수 있습니다. tmux 또는 iTerm2가 필요합니다.

참고:

tmux는 특정 운영 체제에서 알려진 제한 사항이 있으며 전통적으로 macOS에서 가장 잘 작동합니다. iTerm2에서 tmux -CC를 사용하는 것이 tmux에 진입하는 권장 방법입니다.

기본값은 "auto"로, 이미 tmux 세션 내에서 실행 중이면 분할 패널을 사용하고, 그렇지 않으면 인프로세스를 사용합니다. "tmux" 설정은 분할 패널 모드를 활성화하고 터미널에 따라 tmux 또는 iTerm2를 자동 감지합니다. 재정의하려면 settings.json에서 teammateMode를 설정하세요:

{
  "teammateMode": "in-process"
}

단일 세션에서 인프로세스 모드를 강제하려면 플래그로 전달하세요:

claude --teammate-mode in-process

분할 패널 모드는 tmux 또는 it2 CLI가 설치된 iTerm2가 필요합니다. 수동 설치 방법:

tmux: 시스템의 패키지 관리자를 통해 설치합니다. 플랫폼별 안내는 tmux 위키를 참고하세요.
iTerm2: it2 CLI를 설치한 후, iTerm2 → Settings → General → Magic → Enable Python API에서 Python API를 활성화합니다.

팀원과 모델 지정

Claude는 작업에 따라 생성할 팀원 수를 결정하지만, 정확히 원하는 것을 지정할 수도 있습니다:

Create a team with 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.

팀원의 계획 승인 요구

복잡하거나 위험한 작업의 경우, 팀원이 구현 전에 계획을 세우도록 요구할 수 있습니다. 팀원은 리드가 접근 방식을 승인할 때까지 읽기 전용 계획 모드에서 작업합니다:

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

팀원이 계획을 완료하면 리드에게 계획 승인 요청을 보냅니다. 리드가 계획을 검토하고 승인하거나 피드백과 함께 반려합니다. 반려되면 팀원은 계획 모드에 머물며 피드백을 반영하여 수정한 후 재제출합니다. 승인되면 팀원은 계획 모드를 종료하고 구현을 시작합니다.

리드는 자율적으로 승인 결정을 내립니다. 리드의 판단에 영향을 주려면 "테스트 커버리지가 포함된 계획만 승인하라" 또는 "데이터베이스 스키마를 수정하는 계획은 반려하라"와 같은 기준을 프롬프트에 포함하세요.

팀원과 직접 대화하기

각 팀원은 완전하고 독립적인 Claude Code 세션입니다. 아무 팀원에게나 직접 메시지를 보내 추가 지시를 내리거나, 후속 질문을 하거나, 접근 방식을 변경할 수 있습니다.

인프로세스 모드: Shift+Down으로 팀원을 순환한 후, 메시지를 입력하여 전송합니다. Enter를 눌러 팀원의 세션을 확인하고, Escape를 눌러 현재 턴을 중단합니다. Ctrl+T로 작업 목록을 토글합니다.
분할 패널 모드: 팀원의 패널을 클릭하여 해당 세션과 직접 상호작용합니다. 각 팀원은 자체 터미널의 전체 뷰를 가집니다.

작업 할당과 클레임

공유 작업 목록은 팀 전체의 작업을 조율합니다. 리드가 작업을 생성하고 팀원이 작업을 수행합니다. 작업에는 대기 중, 진행 중, 완료의 세 가지 상태가 있습니다. 작업에는 다른 작업에 대한 의존성도 있을 수 있습니다: 미해결 의존성이 있는 대기 중인 작업은 해당 의존성이 완료될 때까지 클레임할 수 없습니다.

리드가 명시적으로 작업을 할당하거나 팀원이 자체 클레임할 수 있습니다:

리드가 할당: 리드에게 어떤 작업을 어떤 팀원에게 줄지 지시합니다
자체 클레임: 작업을 완료한 후, 팀원이 다음 미할당되고 차단되지 않은 작업을 스스로 선택합니다

작업 클레임은 여러 팀원이 동시에 같은 작업을 클레임하려 할 때의 경합 조건을 방지하기 위해 파일 잠금을 사용합니다.

팀원 종료

팀원의 세션을 우아하게 종료하려면:

Ask the researcher teammate to shut down

리드가 종료 요청을 보냅니다. 팀원은 승인하여 우아하게 종료하거나, 설명과 함께 거부할 수 있습니다.

팀 정리

작업이 완료되면 리드에게 정리를 요청하세요:

Clean up the team

이렇게 하면 공유 팀 리소스가 제거됩니다. 리드가 정리를 실행할 때 활성 팀원이 있는지 확인하고, 아직 실행 중인 팀원이 있으면 실패하므로 먼저 종료시키세요.

주의:

항상 리드를 통해 정리하세요. 팀원이 정리를 실행하면 팀 컨텍스트가 올바르게 해석되지 않아 리소스가 불일치 상태로 남을 수 있습니다.

훅을 통한 품질 게이트 적용

훅을 사용하여 팀원이 작업을 마치거나 작업이 완료될 때 규칙을 적용할 수 있습니다:

TeammateIdle: 팀원이 유휴 상태가 되려 할 때 실행됩니다. 종료 코드 2로 반환하면 피드백을 전송하고 팀원이 계속 작업하게 합니다.
TaskCompleted: 작업이 완료로 표시될 때 실행됩니다. 종료 코드 2로 반환하면 완료를 막고 피드백을 전송합니다.

에이전트 팀의 작동 원리

이 섹션에서는 에이전트 팀의 아키텍처와 메커니즘을 다룹니다. 사용을 시작하려면 위의 에이전트 팀 제어하기를 참고하세요.

Claude가 에이전트 팀을 시작하는 방법

에이전트 팀이 시작되는 두 가지 방법이 있습니다:

사용자가 팀을 요청: Claude에게 병렬 작업이 효과적인 작업을 주고 명시적으로 에이전트 팀을 요청합니다. Claude가 지시에 따라 팀을 생성합니다.
Claude가 팀을 제안: Claude가 작업이 병렬 작업에 적합하다고 판단하면 팀 생성을 제안할 수 있습니다. 진행 전에 사용자의 확인을 받습니다.

두 경우 모두 사용자가 통제권을 갖습니다. Claude는 사용자의 승인 없이 팀을 생성하지 않습니다.

아키텍처

에이전트 팀은 다음으로 구성됩니다:

구성 요소	역할
팀 리드	팀을 생성하고, 팀원을 생성하며, 작업을 조율하는 메인 Claude Code 세션
팀원	각각 할당된 작업을 수행하는 별도의 Claude Code 인스턴스
작업 목록	팀원이 클레임하고 완료하는 공유 작업 항목 목록
메일박스	에이전트 간 소통을 위한 메시징 시스템

디스플레이 구성 옵션은 디스플레이 모드 선택을 참고하세요. 팀원의 메시지는 리드에게 자동으로 전달됩니다.

시스템은 작업 의존성을 자동으로 관리합니다. 팀원이 다른 작업이 의존하는 작업을 완료하면, 차단된 작업은 수동 개입 없이 차단이 해제됩니다.

팀과 작업은 로컬에 저장됩니다:

팀 설정: ~/.claude/teams/{team-name}/config.json
작업 목록: ~/.claude/tasks/{team-name}/

팀 설정에는 각 팀원의 이름, 에이전트 ID, 에이전트 유형이 포함된 members 배열이 있습니다. 팀원은 이 파일을 읽어 다른 팀 멤버를 확인할 수 있습니다.

권한

팀원은 리드의 권한 설정으로 시작합니다. 리드가 --dangerously-skip-permissions로 실행하면 모든 팀원도 마찬가지입니다. 생성 후 개별 팀원 모드를 변경할 수 있지만, 생성 시점에 팀원별 모드를 설정할 수는 없습니다.

컨텍스트와 소통

각 팀원은 자체 컨텍스트 윈도우를 가집니다. 생성 시 팀원은 일반 세션과 동일한 프로젝트 컨텍스트를 로드합니다: CLAUDE.md, MCP 서버, 스킬. 또한 리드로부터 생성 프롬프트를 받습니다. 리드의 대화 기록은 전달되지 않습니다.

팀원 간 정보 공유 방식:

자동 메시지 전달: 팀원이 메시지를 보내면 수신자에게 자동으로 전달됩니다. 리드가 업데이트를 폴링할 필요가 없습니다.
유휴 알림: 팀원이 작업을 마치고 멈추면 리드에게 자동으로 알립니다.
공유 작업 목록: 모든 에이전트가 작업 상태를 확인하고 가능한 작업을 클레임할 수 있습니다.

팀원 메시징:

message: 특정 팀원 한 명에게 메시지를 보냅니다
broadcast: 모든 팀원에게 동시에 보냅니다. 비용이 팀 규모에 비례하여 증가하므로 아껴서 사용하세요.

토큰 사용량

에이전트 팀은 단일 세션보다 훨씬 더 많은 토큰을 사용합니다. 각 팀원이 자체 컨텍스트 윈도우를 가지며, 토큰 사용량은 활성 팀원 수에 비례하여 증가합니다. 리서치, 리뷰, 새 기능 작업의 경우 추가 토큰은 대개 그만한 가치가 있습니다. 일상적인 작업의 경우 단일 세션이 더 비용 효율적입니다. 사용량 안내는 에이전트 팀 토큰 비용을 참고하세요.

사용 사례 예시

이 예시들은 에이전트 팀이 병렬 탐색이 가치를 더하는 작업을 어떻게 처리하는지 보여줍니다.

병렬 코드 리뷰 실행

단일 리뷰어는 한 번에 한 유형의 이슈에 집중하는 경향이 있습니다. 리뷰 기준을 독립적인 영역으로 분리하면 보안, 성능, 테스트 커버리지 모두 동시에 철저한 검토를 받을 수 있습니다. 프롬프트는 각 팀원에게 겹치지 않도록 고유한 관점을 할당합니다:

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

각 리뷰어는 같은 PR에서 작업하되 다른 필터를 적용합니다. 리드는 모든 리뷰어가 완료된 후 발견 내용을 종합합니다.

경쟁 가설을 통한 조사

근본 원인이 불분명할 때 단일 에이전트는 하나의 그럴듯한 설명을 찾고 탐색을 멈추는 경향이 있습니다. 이 프롬프트는 팀원을 명시적으로 적대적으로 만들어 이를 방지합니다: 각 팀원의 임무는 자신의 이론을 조사하는 것뿐만 아니라 다른 팀원의 이론에 이의를 제기하는 것입니다.

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

토론 구조가 핵심 메커니즘입니다. 순차적 조사는 앵커링 효과에 시달립니다: 한 가지 이론이 탐색되면 이후 조사가 그 이론에 편향됩니다.

여러 독립적인 조사자가 적극적으로 서로의 이론을 반증하려 할 때, 살아남은 이론이 실제 근본 원인일 가능성이 훨씬 높습니다.

모범 사례

팀원에게 충분한 컨텍스트 제공

팀원은 CLAUDE.md, MCP 서버, 스킬 등 프로젝트 컨텍스트를 자동으로 로드하지만, 리드의 대화 기록은 상속받지 않습니다. 자세한 내용은 컨텍스트와 소통을 참고하세요. 생성 프롬프트에 작업별 세부 정보를 포함하세요:

Spawn a security reviewer teammate with the prompt: "Review the authentication module
at src/auth/ for security vulnerabilities. Focus on token handling, session
management, and input validation. The app uses JWT tokens stored in
httpOnly cookies. Report any issues with severity ratings."

적절한 팀 규모 선택

팀원 수에 대한 엄격한 제한은 없지만, 실질적인 제약이 있습니다:

토큰 비용이 선형적으로 증가: 각 팀원이 자체 컨텍스트 윈도우를 가지며 독립적으로 토큰을 소비합니다. 자세한 내용은 에이전트 팀 토큰 비용을 참고하세요.
조율 오버헤드 증가: 팀원이 많을수록 더 많은 소통, 작업 조율, 잠재적 충돌이 발생합니다
수확 체감: 일정 수준을 넘어서면 추가 팀원이 작업 속도를 비례적으로 높이지 못합니다

대부분의 워크플로우에서는 35명의 팀원으로 시작하세요. 이는 병렬 작업과 관리 가능한 조율 사이의 균형을 맞춥니다. 이 가이드의 예시에서는 다양한 작업 유형에서 잘 작동하는 35명을 사용합니다.

팀원당 5~6개의 작업을 두면 과도한 컨텍스트 전환 없이 모두 생산적으로 유지됩니다. 독립적인 작업이 15개라면 팀원 3명이 좋은 출발점입니다.

작업이 진정으로 동시 작업의 혜택을 받을 때만 규모를 키우세요. 집중력 있는 팀원 3명이 분산된 5명보다 나은 경우가 많습니다.

적절한 작업 크기 설정

너무 작은 경우: 조율 오버헤드가 이점을 초과합니다
너무 큰 경우: 팀원이 체크인 없이 너무 오래 작업하여 낭비되는 노력의 위험이 증가합니다
적절한 경우: 함수, 테스트 파일, 리뷰 등 명확한 산출물을 생성하는 자체 완결적인 단위

팁:

리드가 자동으로 작업을 분할하고 팀원에게 할당합니다. 충분한 작업이 생성되지 않는다면 작업을 더 작은 조각으로 나누도록 요청하세요. 팀원당 5~6개의 작업을 두면 모두 생산적으로 유지되며, 누군가 막히면 리드가 작업을 재할당할 수 있습니다.

팀원이 완료할 때까지 대기

때때로 리드가 팀원을 기다리지 않고 직접 작업을 구현하기 시작합니다. 이를 발견하면:

Wait for your teammates to complete their tasks before proceeding

리서치와 리뷰부터 시작하기

에이전트 팀이 처음이라면 명확한 경계가 있고 코드 작성이 필요 없는 작업부터 시작하세요: PR 리뷰, 라이브러리 조사, 버그 조사 등. 이런 작업은 병렬 구현의 조율 어려움 없이 병렬 탐색의 가치를 보여줍니다.

파일 충돌 방지

두 팀원이 같은 파일을 편집하면 덮어쓰기가 발생합니다. 각 팀원이 서로 다른 파일 세트를 담당하도록 작업을 분할하세요.

모니터링 및 조정

팀원의 진행 상황을 확인하고, 효과적이지 않은 접근 방식을 변경하며, 발견 내용이 나오는 대로 종합하세요. 팀을 너무 오래 무인으로 방치하면 낭비되는 노력의 위험이 증가합니다.

문제 해결

팀원이 나타나지 않음

Claude에게 팀 생성을 요청한 후 팀원이 나타나지 않는 경우:

인프로세스 모드에서는 팀원이 이미 실행 중이지만 보이지 않을 수 있습니다. Shift+Down을 눌러 활성 팀원을 순환해 보세요.
Claude에게 준 작업이 팀을 구성할 만큼 충분히 복잡한지 확인하세요. Claude는 작업에 따라 팀원 생성 여부를 결정합니다.
분할 패널을 명시적으로 요청한 경우, tmux가 설치되어 있고 PATH에서 사용 가능한지 확인하세요:
```
which tmux
```
iTerm2의 경우, it2 CLI가 설치되어 있고 iTerm2 환경설정에서 Python API가 활성화되어 있는지 확인하세요.

권한 프롬프트가 너무 많음

팀원의 권한 요청이 리드로 전달되어 마찰이 발생할 수 있습니다. 팀원을 생성하기 전에 권한 설정에서 일반적인 작업을 사전 승인하여 중단을 줄이세요.

팀원이 오류 발생 시 멈춤

팀원이 오류를 만나면 복구하지 않고 멈출 수 있습니다. 인프로세스 모드에서 Shift+Down을 사용하거나 분할 모드에서 패널을 클릭하여 출력을 확인한 후:

직접 추가 지시를 내리거나
교체 팀원을 생성하여 작업을 계속합니다

리드가 작업 완료 전에 종료

리드가 모든 작업이 실제로 완료되기 전에 팀이 끝났다고 결정할 수 있습니다. 이 경우 계속 진행하라고 지시하세요. 리드가 위임 대신 직접 작업을 하기 시작하면 팀원이 완료할 때까지 기다리라고 지시할 수도 있습니다.

고아 tmux 세션

팀이 종료된 후 tmux 세션이 남아있다면 완전히 정리되지 않았을 수 있습니다. 세션을 나열하고 팀이 생성한 세션을 종료하세요:

tmux ls
tmux kill-session -t <session-name>

제한 사항

에이전트 팀은 실험적 기능입니다. 알아야 할 현재 제한 사항:

인프로세스 팀원의 세션 복원 불가: /resume과 /rewind는 인프로세스 팀원을 복원하지 않습니다. 세션 복원 후 리드가 더 이상 존재하지 않는 팀원에게 메시지를 보내려 할 수 있습니다. 이 경우 리드에게 새 팀원을 생성하라고 지시하세요.
작업 상태 지연 가능: 팀원이 때때로 작업을 완료로 표시하지 못하여 의존 작업이 차단됩니다. 작업이 멈춰 보이면 실제로 완료되었는지 확인하고 작업 상태를 수동으로 업데이트하거나 리드에게 팀원을 독촉하라고 지시하세요.
종료가 느릴 수 있음: 팀원은 현재 요청이나 도구 호출을 마친 후 종료하므로 시간이 걸릴 수 있습니다.
세션당 하나의 팀: 리드는 한 번에 하나의 팀만 관리할 수 있습니다. 새 팀을 시작하기 전에 현재 팀을 정리하세요.
중첩 팀 불가: 팀원은 자체 팀이나 팀원을 생성할 수 없습니다. 리드만 팀을 관리할 수 있습니다.
리드 고정: 팀을 생성한 세션이 수명 동안 리드입니다. 팀원을 리드로 승격하거나 리더십을 이전할 수 없습니다.
생성 시 권한 설정: 모든 팀원은 리드의 권한 모드로 시작합니다. 생성 후 개별 팀원 모드를 변경할 수 있지만, 생성 시점에 팀원별 모드를 설정할 수는 없습니다.
분할 패널은 tmux 또는 iTerm2 필요: 기본 인프로세스 모드는 어떤 터미널에서든 작동합니다. 분할 패널 모드는 VS Code 통합 터미널, Windows Terminal, Ghostty에서는 지원되지 않습니다.

팁:

CLAUDE.md는 정상 작동합니다: 팀원은 작업 디렉토리에서 CLAUDE.md 파일을 읽습니다. 이를 사용하여 모든 팀원에게 프로젝트별 안내를 제공하세요.

다음 단계

병렬 작업과 위임을 위한 관련 접근 방식을 살펴보세요:

경량 위임: 서브에이전트는 세션 내에서 리서치나 검증을 위한 도우미 에이전트를 생성합니다. 에이전트 간 조율이 필요 없는 작업에 더 적합합니다
수동 병렬 세션: Git worktrees를 사용하면 자동화된 팀 조율 없이 직접 여러 Claude Code 세션을 실행할 수 있습니다
접근 방식 비교: 서브에이전트 vs 에이전트 팀 비교에서 나란히 비교해 보세요

Claude Code 세션 팀 오케스트레이션

여러 Claude Code 인스턴스가 팀으로 협력하도록 조율합니다. 공유 작업 목록, 에이전트 간 메시징, 중앙 집중식 관리를 지원합니다.

주의:

에이전트 팀은 실험적 기능이며 기본적으로 비활성화되어 있습니다. settings.json 또는 환경 변수에 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS를 추가하여 활성화할 수 있습니다. 에이전트 팀에는 세션 복원, 작업 조율, 종료 동작과 관련된 알려진 제한 사항이 있습니다.

이 페이지에서 다루는 내용:

에이전트 팀을 사용해야 하는 경우 - 최적의 사용 사례와 서브에이전트와의 비교
팀 시작하기
팀원 제어하기 - 디스플레이 모드, 작업 할당, 위임
병렬 작업 모범 사례

에이전트 팀을 사용해야 하는 경우

리서치 및 리뷰: 여러 팀원이 문제의 다양한 측면을 동시에 조사한 후, 서로의 발견 내용을 공유하고 검증할 수 있습니다
새로운 모듈이나 기능: 팀원이 각각 별도의 영역을 담당하여 서로 충돌하지 않습니다
경쟁 가설을 통한 디버깅: 팀원이 서로 다른 가설을 병렬로 테스트하여 더 빠르게 답을 수렴합니다
크로스 레이어 조율: 프론트엔드, 백엔드, 테스트에 걸쳐 변경이 필요한 경우, 각각을 다른 팀원이 담당합니다

서브에이전트와의 비교

에이전트 팀과 서브에이전트 모두 작업을 병렬화할 수 있지만, 작동 방식이 다릅니다. 작업자 간 소통이 필요한지에 따라 선택하세요:

	서브에이전트	에이전트 팀
컨텍스트	자체 컨텍스트 윈도우; 결과가 호출자에게 반환됨	자체 컨텍스트 윈도우; 완전히 독립적
소통	메인 에이전트에게만 결과를 보고	팀원끼리 직접 메시지를 주고받음
조율	메인 에이전트가 모든 작업을 관리	공유 작업 목록을 통한 자체 조율
적합한 용도	결과만 중요한 집중적인 작업	논의와 협업이 필요한 복잡한 작업
토큰 비용	낮음: 결과가 요약되어 메인 컨텍스트로 반환	높음: 각 팀원이 별도의 Claude 인스턴스

에이전트 팀 활성화

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

첫 번째 에이전트 팀 시작하기

이 예시는 세 가지 역할이 서로 독립적이고 대기 없이 문제를 탐색할 수 있어 효과적입니다:

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Create an agent team to explore this from different angles: one
teammate on UX, one on technical architecture, one playing devil's advocate.

각 팀원을 별도의 분할 패널에서 보고 싶다면 디스플레이 모드 선택을 참고하세요.

에이전트 팀 제어하기

리드에게 원하는 것을 자연어로 지시하세요. 리드가 지시에 따라 팀 조율, 작업 할당, 위임을 처리합니다.

디스플레이 모드 선택

에이전트 팀은 두 가지 디스플레이 모드를 지원합니다:

인프로세스: 모든 팀원이 메인 터미널 내에서 실행됩니다. Shift+Down으로 팀원을 순환하며 직접 메시지를 입력할 수 있습니다. 어떤 터미널에서든 작동하며 추가 설정이 필요 없습니다.
분할 패널: 각 팀원이 자체 패널을 갖습니다. 모든 팀원의 출력을 동시에 볼 수 있으며, 패널을 클릭하여 직접 상호작용할 수 있습니다. tmux 또는 iTerm2가 필요합니다.

참고:

tmux는 특정 운영 체제에서 알려진 제한 사항이 있으며 전통적으로 macOS에서 가장 잘 작동합니다. iTerm2에서 tmux -CC를 사용하는 것이 tmux에 진입하는 권장 방법입니다.

{
  "teammateMode": "in-process"
}

단일 세션에서 인프로세스 모드를 강제하려면 플래그로 전달하세요:

claude --teammate-mode in-process

분할 패널 모드는 tmux 또는 it2 CLI가 설치된 iTerm2가 필요합니다. 수동 설치 방법:

tmux: 시스템의 패키지 관리자를 통해 설치합니다. 플랫폼별 안내는 tmux 위키를 참고하세요.
iTerm2: it2 CLI를 설치한 후, iTerm2 → Settings → General → Magic → Enable Python API에서 Python API를 활성화합니다.

팀원과 모델 지정

Claude는 작업에 따라 생성할 팀원 수를 결정하지만, 정확히 원하는 것을 지정할 수도 있습니다:

Create a team with 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.

팀원의 계획 승인 요구

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

팀원과 직접 대화하기

인프로세스 모드: Shift+Down으로 팀원을 순환한 후, 메시지를 입력하여 전송합니다. Enter를 눌러 팀원의 세션을 확인하고, Escape를 눌러 현재 턴을 중단합니다. Ctrl+T로 작업 목록을 토글합니다.
분할 패널 모드: 팀원의 패널을 클릭하여 해당 세션과 직접 상호작용합니다. 각 팀원은 자체 터미널의 전체 뷰를 가집니다.

작업 할당과 클레임

리드가 명시적으로 작업을 할당하거나 팀원이 자체 클레임할 수 있습니다:

리드가 할당: 리드에게 어떤 작업을 어떤 팀원에게 줄지 지시합니다
자체 클레임: 작업을 완료한 후, 팀원이 다음 미할당되고 차단되지 않은 작업을 스스로 선택합니다

작업 클레임은 여러 팀원이 동시에 같은 작업을 클레임하려 할 때의 경합 조건을 방지하기 위해 파일 잠금을 사용합니다.

팀원 종료

팀원의 세션을 우아하게 종료하려면:

Ask the researcher teammate to shut down

리드가 종료 요청을 보냅니다. 팀원은 승인하여 우아하게 종료하거나, 설명과 함께 거부할 수 있습니다.

팀 정리

작업이 완료되면 리드에게 정리를 요청하세요:

Clean up the team

주의:

항상 리드를 통해 정리하세요. 팀원이 정리를 실행하면 팀 컨텍스트가 올바르게 해석되지 않아 리소스가 불일치 상태로 남을 수 있습니다.

훅을 통한 품질 게이트 적용

훅을 사용하여 팀원이 작업을 마치거나 작업이 완료될 때 규칙을 적용할 수 있습니다:

TeammateIdle: 팀원이 유휴 상태가 되려 할 때 실행됩니다. 종료 코드 2로 반환하면 피드백을 전송하고 팀원이 계속 작업하게 합니다.
TaskCompleted: 작업이 완료로 표시될 때 실행됩니다. 종료 코드 2로 반환하면 완료를 막고 피드백을 전송합니다.

에이전트 팀의 작동 원리

이 섹션에서는 에이전트 팀의 아키텍처와 메커니즘을 다룹니다. 사용을 시작하려면 위의 에이전트 팀 제어하기를 참고하세요.

Claude가 에이전트 팀을 시작하는 방법

에이전트 팀이 시작되는 두 가지 방법이 있습니다:

사용자가 팀을 요청: Claude에게 병렬 작업이 효과적인 작업을 주고 명시적으로 에이전트 팀을 요청합니다. Claude가 지시에 따라 팀을 생성합니다.
Claude가 팀을 제안: Claude가 작업이 병렬 작업에 적합하다고 판단하면 팀 생성을 제안할 수 있습니다. 진행 전에 사용자의 확인을 받습니다.

두 경우 모두 사용자가 통제권을 갖습니다. Claude는 사용자의 승인 없이 팀을 생성하지 않습니다.

아키텍처

에이전트 팀은 다음으로 구성됩니다:

구성 요소	역할
팀 리드	팀을 생성하고, 팀원을 생성하며, 작업을 조율하는 메인 Claude Code 세션
팀원	각각 할당된 작업을 수행하는 별도의 Claude Code 인스턴스
작업 목록	팀원이 클레임하고 완료하는 공유 작업 항목 목록
메일박스	에이전트 간 소통을 위한 메시징 시스템

디스플레이 구성 옵션은 디스플레이 모드 선택을 참고하세요. 팀원의 메시지는 리드에게 자동으로 전달됩니다.

시스템은 작업 의존성을 자동으로 관리합니다. 팀원이 다른 작업이 의존하는 작업을 완료하면, 차단된 작업은 수동 개입 없이 차단이 해제됩니다.

팀과 작업은 로컬에 저장됩니다:

팀 설정: ~/.claude/teams/{team-name}/config.json
작업 목록: ~/.claude/tasks/{team-name}/

권한

컨텍스트와 소통

팀원 간 정보 공유 방식:

자동 메시지 전달: 팀원이 메시지를 보내면 수신자에게 자동으로 전달됩니다. 리드가 업데이트를 폴링할 필요가 없습니다.
유휴 알림: 팀원이 작업을 마치고 멈추면 리드에게 자동으로 알립니다.
공유 작업 목록: 모든 에이전트가 작업 상태를 확인하고 가능한 작업을 클레임할 수 있습니다.

팀원 메시징:

message: 특정 팀원 한 명에게 메시지를 보냅니다
broadcast: 모든 팀원에게 동시에 보냅니다. 비용이 팀 규모에 비례하여 증가하므로 아껴서 사용하세요.

토큰 사용량

사용 사례 예시

이 예시들은 에이전트 팀이 병렬 탐색이 가치를 더하는 작업을 어떻게 처리하는지 보여줍니다.

병렬 코드 리뷰 실행

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

각 리뷰어는 같은 PR에서 작업하되 다른 필터를 적용합니다. 리드는 모든 리뷰어가 완료된 후 발견 내용을 종합합니다.

경쟁 가설을 통한 조사

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

토론 구조가 핵심 메커니즘입니다. 순차적 조사는 앵커링 효과에 시달립니다: 한 가지 이론이 탐색되면 이후 조사가 그 이론에 편향됩니다.

여러 독립적인 조사자가 적극적으로 서로의 이론을 반증하려 할 때, 살아남은 이론이 실제 근본 원인일 가능성이 훨씬 높습니다.

모범 사례

팀원에게 충분한 컨텍스트 제공

Spawn a security reviewer teammate with the prompt: "Review the authentication module
at src/auth/ for security vulnerabilities. Focus on token handling, session
management, and input validation. The app uses JWT tokens stored in
httpOnly cookies. Report any issues with severity ratings."

적절한 팀 규모 선택

팀원 수에 대한 엄격한 제한은 없지만, 실질적인 제약이 있습니다:

토큰 비용이 선형적으로 증가: 각 팀원이 자체 컨텍스트 윈도우를 가지며 독립적으로 토큰을 소비합니다. 자세한 내용은 에이전트 팀 토큰 비용을 참고하세요.
조율 오버헤드 증가: 팀원이 많을수록 더 많은 소통, 작업 조율, 잠재적 충돌이 발생합니다
수확 체감: 일정 수준을 넘어서면 추가 팀원이 작업 속도를 비례적으로 높이지 못합니다

팀원당 5~6개의 작업을 두면 과도한 컨텍스트 전환 없이 모두 생산적으로 유지됩니다. 독립적인 작업이 15개라면 팀원 3명이 좋은 출발점입니다.

작업이 진정으로 동시 작업의 혜택을 받을 때만 규모를 키우세요. 집중력 있는 팀원 3명이 분산된 5명보다 나은 경우가 많습니다.

적절한 작업 크기 설정

너무 작은 경우: 조율 오버헤드가 이점을 초과합니다
너무 큰 경우: 팀원이 체크인 없이 너무 오래 작업하여 낭비되는 노력의 위험이 증가합니다
적절한 경우: 함수, 테스트 파일, 리뷰 등 명확한 산출물을 생성하는 자체 완결적인 단위

팁:

리드가 자동으로 작업을 분할하고 팀원에게 할당합니다. 충분한 작업이 생성되지 않는다면 작업을 더 작은 조각으로 나누도록 요청하세요. 팀원당 5~6개의 작업을 두면 모두 생산적으로 유지되며, 누군가 막히면 리드가 작업을 재할당할 수 있습니다.

팀원이 완료할 때까지 대기

때때로 리드가 팀원을 기다리지 않고 직접 작업을 구현하기 시작합니다. 이를 발견하면:

Wait for your teammates to complete their tasks before proceeding

리서치와 리뷰부터 시작하기

파일 충돌 방지

두 팀원이 같은 파일을 편집하면 덮어쓰기가 발생합니다. 각 팀원이 서로 다른 파일 세트를 담당하도록 작업을 분할하세요.

모니터링 및 조정

문제 해결

팀원이 나타나지 않음

Claude에게 팀 생성을 요청한 후 팀원이 나타나지 않는 경우:

인프로세스 모드에서는 팀원이 이미 실행 중이지만 보이지 않을 수 있습니다. Shift+Down을 눌러 활성 팀원을 순환해 보세요.
Claude에게 준 작업이 팀을 구성할 만큼 충분히 복잡한지 확인하세요. Claude는 작업에 따라 팀원 생성 여부를 결정합니다.
분할 패널을 명시적으로 요청한 경우, tmux가 설치되어 있고 PATH에서 사용 가능한지 확인하세요:
```
which tmux
```
iTerm2의 경우, it2 CLI가 설치되어 있고 iTerm2 환경설정에서 Python API가 활성화되어 있는지 확인하세요.

권한 프롬프트가 너무 많음

팀원이 오류 발생 시 멈춤

직접 추가 지시를 내리거나
교체 팀원을 생성하여 작업을 계속합니다

리드가 작업 완료 전에 종료

고아 tmux 세션

팀이 종료된 후 tmux 세션이 남아있다면 완전히 정리되지 않았을 수 있습니다. 세션을 나열하고 팀이 생성한 세션을 종료하세요:

tmux ls
tmux kill-session -t <session-name>

제한 사항

에이전트 팀은 실험적 기능입니다. 알아야 할 현재 제한 사항:

인프로세스 팀원의 세션 복원 불가: /resume과 /rewind는 인프로세스 팀원을 복원하지 않습니다. 세션 복원 후 리드가 더 이상 존재하지 않는 팀원에게 메시지를 보내려 할 수 있습니다. 이 경우 리드에게 새 팀원을 생성하라고 지시하세요.
작업 상태 지연 가능: 팀원이 때때로 작업을 완료로 표시하지 못하여 의존 작업이 차단됩니다. 작업이 멈춰 보이면 실제로 완료되었는지 확인하고 작업 상태를 수동으로 업데이트하거나 리드에게 팀원을 독촉하라고 지시하세요.
종료가 느릴 수 있음: 팀원은 현재 요청이나 도구 호출을 마친 후 종료하므로 시간이 걸릴 수 있습니다.
세션당 하나의 팀: 리드는 한 번에 하나의 팀만 관리할 수 있습니다. 새 팀을 시작하기 전에 현재 팀을 정리하세요.
중첩 팀 불가: 팀원은 자체 팀이나 팀원을 생성할 수 없습니다. 리드만 팀을 관리할 수 있습니다.
리드 고정: 팀을 생성한 세션이 수명 동안 리드입니다. 팀원을 리드로 승격하거나 리더십을 이전할 수 없습니다.
생성 시 권한 설정: 모든 팀원은 리드의 권한 모드로 시작합니다. 생성 후 개별 팀원 모드를 변경할 수 있지만, 생성 시점에 팀원별 모드를 설정할 수는 없습니다.
분할 패널은 tmux 또는 iTerm2 필요: 기본 인프로세스 모드는 어떤 터미널에서든 작동합니다. 분할 패널 모드는 VS Code 통합 터미널, Windows Terminal, Ghostty에서는 지원되지 않습니다.

팁:

CLAUDE.md는 정상 작동합니다: 팀원은 작업 디렉토리에서 CLAUDE.md 파일을 읽습니다. 이를 사용하여 모든 팀원에게 프로젝트별 안내를 제공하세요.

다음 단계

병렬 작업과 위임을 위한 관련 접근 방식을 살펴보세요:

경량 위임: 서브에이전트는 세션 내에서 리서치나 검증을 위한 도우미 에이전트를 생성합니다. 에이전트 간 조율이 필요 없는 작업에 더 적합합니다
수동 병렬 세션: Git worktrees를 사용하면 자동화된 팀 조율 없이 직접 여러 Claude Code 세션을 실행할 수 있습니다
접근 방식 비교: 서브에이전트 vs 에이전트 팀 비교에서 나란히 비교해 보세요

7. Claude Code 세션 팀 오케스트레이션

Claude Code 세션 팀 오케스트레이션

에이전트 팀을 사용해야 하는 경우

서브에이전트와의 비교

에이전트 팀 활성화

첫 번째 에이전트 팀 시작하기

에이전트 팀 제어하기

디스플레이 모드 선택

팀원과 모델 지정

팀원의 계획 승인 요구

팀원과 직접 대화하기

작업 할당과 클레임

팀원 종료

팀 정리

훅을 통한 품질 게이트 적용

에이전트 팀의 작동 원리

Claude가 에이전트 팀을 시작하는 방법

아키텍처

권한

컨텍스트와 소통

토큰 사용량

사용 사례 예시

병렬 코드 리뷰 실행

경쟁 가설을 통한 조사

모범 사례

팀원에게 충분한 컨텍스트 제공

적절한 팀 규모 선택

적절한 작업 크기 설정

팀원이 완료할 때까지 대기

리서치와 리뷰부터 시작하기

파일 충돌 방지

모니터링 및 조정

문제 해결

팀원이 나타나지 않음

권한 프롬프트가 너무 많음

팀원이 오류 발생 시 멈춤

리드가 작업 완료 전에 종료

고아 tmux 세션

제한 사항

다음 단계

7. Claude Code 세션 팀 오케스트레이션

Claude Code 세션 팀 오케스트레이션

에이전트 팀을 사용해야 하는 경우

서브에이전트와의 비교

에이전트 팀 활성화

첫 번째 에이전트 팀 시작하기

에이전트 팀 제어하기

디스플레이 모드 선택

팀원과 모델 지정

팀원의 계획 승인 요구

팀원과 직접 대화하기

작업 할당과 클레임

팀원 종료

팀 정리

훅을 통한 품질 게이트 적용

에이전트 팀의 작동 원리

Claude가 에이전트 팀을 시작하는 방법

아키텍처

권한

컨텍스트와 소통

토큰 사용량

사용 사례 예시

병렬 코드 리뷰 실행

경쟁 가설을 통한 조사

모범 사례

팀원에게 충분한 컨텍스트 제공

적절한 팀 규모 선택

적절한 작업 크기 설정

팀원이 완료할 때까지 대기

리서치와 리뷰부터 시작하기

파일 충돌 방지

모니터링 및 조정

문제 해결

팀원이 나타나지 않음

권한 프롬프트가 너무 많음

팀원이 오류 발생 시 멈춤

리드가 작업 완료 전에 종료

고아 tmux 세션

제한 사항

다음 단계