Claude Code 세션 팀 조율하기

Claude Code 세션 팀 조율하기 (Orchestrate teams of Claude Code sessions)

여러 Claude Code 인스턴스를 팀으로 함께 작업하도록 조율하며, 공유 작업, 에이전트 간 메시징, 중앙 관리가 특징입니다. 에이전트 팀은 병렬 탐색이 진짜 가치를 더하는 리서치·리뷰·신규 모듈·경쟁 가설 디버깅 등에 가장 효과적입니다. 다만 실험 기능이라 기본적으로 비활성화되어 있으며 단일 세션보다 훨씬 많은 토큰을 씁니다.

출처: 공식문서

본문

에이전트 팀은 실험 기능이며 기본적으로 비활성화되어 있습니다. [settings.json](/docs/en/settings) 또는 환경에서 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`을 설정해 활성화하세요. 그 변수 없이는 세션 시작 시 팀이 구성되지 않고, 팀 디렉터리가 쓰이지 않으며, Claude가 팀원을 생성하거나 제안하지 않습니다. 에이전트 팀에는 세션 재개, 작업 조율, 종료 동작에 관한 [알려진 한계](#한계)가 있습니다.

에이전트 팀은 함께 작업하는 여러 Claude Code 인스턴스를 조율하게 합니다. 한 세션이 팀 리드 역할을 하며 작업을 조율하고, 과제를 배정하고, 결과를 종합합니다. 팀원들은 각자 자체 컨텍스트 창에서 독립적으로 작업하며 서로 직접 소통합니다. 리드를 거치지 않고 어떤 팀원에게도 직접 말할 수 있습니다.

팀을 구성하기 전에 더 가벼운 옵션이 해결하는지 확인하세요. 서브에이전트는 단일 세션 안에서 동작하며, 세션 간 메시징으로 Claude는 직접 실행하는 세션 사이에서 발견 내용을 전달할 수 있습니다.

이 페이지는 v2.1.178 기준의 에이전트 팀을 설명합니다. `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`가 설정되면 팀원 생성은 더 이상 설정 단계가 필요 없고, 세션 종료 시 정리가 자동으로 일어납니다. v2.1.178 이전에는 먼저 Claude에게 팀을 만들고 이름 짓도록 요청했고, Claude는 `TeamCreate`와 `TeamDelete` 도구로 구성하고 제거했습니다. 두 도구 모두 더 이상 존재하지 않습니다. Agent 도구의 `team_name` 입력은 받아들여지지만 무시되며, `TaskCreated`, `TaskCompleted`, `TeammateIdle` [훅 페이로드](/docs/en/hooks#taskcreated)의 `team_name` 필드는 세션에서 파생된 이름을 담으며 폐기되었습니다.

에이전트 팀을 써야 할 때

에이전트 팀은 병렬 탐색이 진짜 가치를 더하는 작업에 가장 효과적입니다. 전체 시나리오는 사용 사례 예시를 보세요. 가장 강력한 사용 사례는:

리서치와 리뷰: 여러 팀원이 문제의 다른 측면을 동시에 조사한 후 서로의 발견을 공유하고 도전할 수 있음
새 모듈이나 기능: 팀원이 각자 별개 조각을 서로 밟지 않고 소유할 수 있음
경쟁 가설 디버깅: 팀원이 다른 이론을 병렬로 테스트하고 더 빨리 답에 수렴
레이어 간 조율: 프런트엔드, 백엔드, 테스트에 걸친 변경을 각기 다른 팀원이 소유

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

서브에이전트와 비교

에이전트 팀과 서브에이전트 모두 작업을 병렬화하게 하지만 동작이 다릅니다. 팀 없이 서로 메시지를 주고받는 별도 세션은 세션 간 메시징을 보세요.

	서브에이전트	에이전트 팀
컨텍스트	자체 컨텍스트 창. 결과는 호출자에게 반환	자체 컨텍스트 창. 완전히 독립
소통	호출자에게 결과 반환. Claude가 생성 시 이름을 붙인 서브에이전트는 서로 메시지도 가능	팀원이 서로 직접 메시지
조율	메인 에이전트가 모든 작업 관리	메시지를 통한 자기 조율 + Task 도구를 가진 에이전트를 위한 공유 작업 목록
최적	결과만 중요한 집중 작업	토론과 협업이 필요한 복잡한 작업
토큰 비용	낮음: 결과가 메인 컨텍스트로 요약됨	높음: 각 팀원이 별도 Claude 인스턴스

결과를 보고하는 빠르고 집중된 워커가 필요하면 서브에이전트를 쓰세요. 팀원이 발견을 공유하고 서로 도전하며 스스로 조율해야 하면 에이전트 팀을 쓰세요.

에이전트 팀 활성화

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

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

에이전트 팀을 활성화하면 평범한 위임도 바뀝니다. Claude는 스스로 서브에이전트 이름을 붙일 수 있고, 에이전트 팀이 활성화된 동안 Claude가 이름을 붙인 서브에이전트는 팀원으로 시작하므로 요청하지 않아도 팀이 형성될 수 있습니다. 자세한 내용은 Claude가 에이전트 팀을 시작하는 방식을, 동작을 끄려면 Claude가 서브에이전트 대신 팀원 생성을 보세요.

팀원 생성에는 인터랙티브 세션도 필요합니다. -p 플래그의 비인터랙티브 모드(Agent SDK 세션 포함)에서는 Claude가 팀원을 생성하지 않으며, Claude가 이름을 붙인 서브에이전트는 에이전트 팀이 활성화되어도 일반 서브에이전트로 실행됩니다.

첫 에이전트 팀 시작하기

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

이 예시는 세 역할이 독립적이고 서로 기다리지 않고 문제를 탐색할 수 있어 잘 동작합니다:

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

여기서부터 Claude는 Task 도구를 가진 세션의 공유 작업 목록을 채우고, 각 관점에 팀원을 생성하고, 문제를 탐색하게 하며, 끝나면 발견을 종합합니다.

Claude는 팀을 만들지 않고 서브에이전트를 쓸 수도 있습니다. 서브에이전트는 팀원과 같은 에이전트 패널에 나타나므로 패널만으로 팀이 형성됐는지 확인할 수 없습니다. 대신 서브에이전트가 생성됐다면 다시 요청하고 명시적으로 에이전트 팀을 요구하세요.

리드의 터미널은 프롬프트 입력 아래 에이전트 패널에 팀원을 나열합니다. 패널에서:

위·아래 화살표: 팀원 선택
Enter: 선택한 팀원의 트랜스크립트를 열고 직접 메시지
Escape: 선택 해제. 팀원 트랜스크립트를 보는 동안 Escape는 그 팀원의 현재 턴을 중단

v2.1.199부터 어떤 팀원이나 서브에이전트가 여전히 작업 중이면 유휴 팀원의 행이 패널에 남아, 트랜스크립트를 검토하거나 더 많은 작업을 보내기 위해 선택할 수 있습니다. 패널의 모든 에이전트가 유휴가 되면 유휴 행은 30초 후 숨고 팀원의 다음 턴에 다시 나타납니다. 숨는 동안 팀원은 실행되고 주소 지정 가능한 상태로 남습니다. v2.1.181~v2.1.198에서는 다른 팀원이 여전히 작업 중이어도 유휴 행이 자기 턴 종료 30초 후 숨었습니다. v2.1.181 이전 버전에서는 유휴 행이 숨지 않습니다.

한 번에 3명 이상의 팀원이 유휴면 처음 세 명 너머의 행들이 접혀 2 idle agents처럼 접힌 팀원 수를 세는 단일 행이 됩니다. 그것을 선택하고 Enter를 눌러 접힌 행을 펼치거나 Esc를 눌러 다시 접으세요. 작업 중인 팀원, 실패한 팀원, 보고 있는 팀원은 항상 자기 행을 유지합니다.

각 팀원을 자체 분할 창에 두려면 표시 모드 선택을 보세요.

에이전트 팀 제어

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

표시 모드 선택

에이전트 팀은 두 가지 표시 모드를 지원합니다:

인프로세스 (In-process): 모든 팀원이 메인 터미널 안에서 실행됩니다. 에이전트 패널에서 위·아래 화살표로 팀원을 선택한 후 Enter를 눌러 보고 직접 메시지를 입력하세요. 어떤 터미널에서도 동작하며 추가 설정이 필요 없습니다.
분할 창 (Split panes): 각 팀원이 자체 창을 가집니다. 모두의 출력을 한 번에 보고 창을 클릭해 직접 상호작용할 수 있습니다. tmux 또는 iTerm2 필요.

`tmux`는 특정 운영체제에서 알려진 한계가 있으며 전통적으로 macOS에서 가장 잘 동작합니다. iTerm2에서 `tmux -CC`를 쓰는 것이 `tmux`로 들어가는 권장 진입점입니다.

기본값은 "in-process"입니다. v2.1.179 이전 기본값은 "auto"였으므로, 이전에 분할 창을 열던 업그레이드 세션은 모드를 명시적으로 설정하지 않으면 이제 한 터미널에 머뭅니다. "auto"로 설정하면 이미 tmux 세션 안에서 실행 중이거나, it2 CLI가 설치된 iTerm2 터미널일 때 분할 창을 활성화하고 그 외에는 인프로세스로 폴백합니다. "tmux" 설정은 분할 창 모드를 활성화하고 터미널에 따라 tmux를 쓸지 iTerm2를 쓸지 자동 감지합니다.

v2.1.186부터 "iterm2"로 설정하면 iTerm2 네이티브 분할 창을 명시적으로 씁니다. 이 모드는 it2 CLI가 필요하며 it2가 없으면 설치 명령과 함께 오류를 보여줍니다. 터미널이 iTerm2이고 폴백으로 tmux를 쓸 수 있을 때 "auto" 또는 "tmux" 아래에서 it2를 설치하거나 tmux로 전환하겠다는 설정 프롬프트가 나타납니다.

기본값을 덮으려면 ~/.claude/settings.json에 teammateMode를 설정하세요:

{
  "teammateMode": "auto"
}

단일 세션에 대해 모드를 설정하려면 플래그로 전달하세요:

claude --teammate-mode auto

--teammate-mode 플래그는 실험적이며 claude --help에 나타나지 않습니다.

분할 창 모드는 tmux 또는 it2 CLI가 있는 iTerm2가 필요합니다. 수동 설치:

tmux: 시스템 패키지 매니저로 설치. 플랫폼별 지침은 tmux wiki 참조
iTerm2: it2 CLI를 설치한 후 iTerm2 → Settings → General → Magic → Enable Python API에서 Python API 활성화

팀원과 모델 지정

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

Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.

Claude Code는 다음 중 먼저 적용되는 것으로 각 팀원의 모델을 고릅니다:

생성 프롬프트가 그 팀원에 대해 명명한 모델.
서브에이전트 정의에서 생성한 팀원의 경우 정의의 model(inherit는 리드의 모델 선택).
inherit 이외의 값으로 설정된 CLAUDE_CODE_SUBAGENT_MODEL.
리드의 현재 모델.

CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1을 설정하면 처음 두 소스는 적용되지 않습니다. Claude Code는 CLAUDE_CODE_SUBAGENT_MODEL이 inherit 이외의 값으로 설정되면 모든 팀원의 모델을 그것에서, 그 외에는 리드의 현재 모델에서 고릅니다. Claude Code v2.1.257 이상 필요.

v2.1.251 이전에는 CLAUDE_CODE_SUBAGENT_MODEL이 이 순서에서 첫 번째였습니다.

`teammateDefaultModel`은 v2.1.234에서 제거되었습니다. Claude Code는 남은 값을 무시합니다. 대신 프롬프트에서 모델을 이름 지으세요.

Claude Code는 팀원에 선택한 모델을 조직의 availableModels 허용 목록에 대조합니다. 허용 목록이 값을 차단하면 Claude Code는 다른 모델로 대체합니다:

opus 같은 패밀리 별칭: Anthropic API와 Claude Platform on AWS에서 Claude Code는 허용 목록이 허용하는 그 패밀리의 최신 버전으로 팀원을 실행합니다. 대체가 작동하지 않는 프로바이더 고유 모델 ID를 쓰는 프로바이더에서는 차단된 별칭이 다음 불릿의 다른 차단된 값처럼 폴백합니다
기타 차단된 값(대체가 작동하지 않는 프로바이더의 패밀리 별칭, 허용된 버전이 없는 패밀리 포함): Claude Code는 대신 리드의 모델로 팀원을 실행합니다. CLAUDE_CODE_SUBAGENT_MODEL을 설정했다면 Claude Code는 이 같은 규칙 아래에서 그 모델을 먼저 시도합니다

팀원은 리드의 노력 수준을 상속합니다. 분할 창 모드에서는 v2.1.186부터 적용됩니다. 이전 버전은 리드의 세션 노력을 분할 창 팀원에게 전달하지 않았습니다.

팀원이 구현 전 계획하게 하기

복잡하거나 위험한 작업에는 팀원이 구현 전에 계획하게 할 수 있습니다. 리드가 plan mode에 있는 동안 Claude가 생성한 팀원은 계획이 준비될 때까지 읽기 전용 plan mode에서 작업합니다. 먼저 리드를 plan mode로 전환한 다음 팀원을 요청하세요:

Spawn an architect teammate to refactor the authentication module.

팀원이 계획을 끝내면 리드에게 계획 승인 요청을 보냅니다. Claude Code는 요청이 도착하는 즉시 리드 세션에서 계획을 승인하며, 리드가 검토하지 않습니다. 팀원의 편집과 명령은 여전히 권한에 설명된 권한 프롬프트를 거칩니다. 승인되면 팀원은 plan mode를 나가 구현을 시작합니다.

팀원에게 직접 말하기

각 팀원은 완전하고 독립적인 Claude Code 세션입니다. 어떤 팀원에게든 직접 메시지로 추가 지침을 주고, 후속 질문을 하고, 접근을 재지정할 수 있습니다.

인프로세스 모드: 에이전트 패널에서 위·아래 화살표로 팀원을 선택한 후 Enter를 눌러 세션을 보고 메시지를 보내세요. 선택한 팀원에 x를 눌러 중지하세요. Ctrl+T로 작업 목록을 토글하세요.
분할 창 모드: 팀원의 창을 클릭해 세션과 직접 상호작용하세요. 각 팀원은 자체 터미널의 전체 보기를 가집니다.

인프로세스 팀원을 보는 동안 일반 텍스트와 스킬은 그 팀원으로 가지만, 내장 명령은 여전히 리드 세션에서 실행됩니다.

팀원의 모델과 fast mode는 생성 시 고정되므로 /model과 /fast는 리드의 설정만 바꿉니다. v2.1.199부터 팀원을 보는 동안 두 명령 중 하나를 입력하면 변경이 리드에 적용된다는 알림이 표시됩니다. 이전 버전은 표시 없이 리드에 적용했습니다. /effort는 여전히 보는 팀원의 이후 턴에 적용됩니다. 팀원이 리드의 노력 수준을 따르기 때문입니다.

작업 배정과 청구

공유 작업 목록이 팀 전체의 작업을 조율합니다. 리드가 작업을 만들고 팀원이 그것을 처리합니다. 작업에는 세 상태가 있습니다: 보류, 진행 중, 완료. 작업은 다른 작업에 의존할 수도 있습니다: 미해결 의존성이 있는 보류 작업은 그 의존성이 완료될 때까지 청구할 수 없습니다.

Task 도구가 없는 에이전트는 공유 작업 목록 대신 메시지로 조율합니다.

리드는 작업을 명시적으로 배정하거나 팀원이 스스로 청구할 수 있습니다:

리드 배정: 어느 팀원에게 어떤 작업을 줄지 리드에게 말하세요
자기 청구: 작업을 끝낸 후 팀원은 스스로 다음 미배정·미차단 작업을 집어 듭니다

작업 청구는 여러 팀원이 동시에 같은 작업을 청구하려 할 때 레이스 조건을 막기 위해 파일 잠금을 사용합니다.

팀원 종료

팀원의 세션을 정중히 끝내려면 이름으로 지칭하세요. 예를 들어 researcher라는 팀원이 있다면:

Ask the researcher teammate to shut down

리드가 종료 요청을 보냅니다. 팀원은 승인해 정중히 종료하거나 설명과 함께 거부할 수 있습니다.

팀의 공유 디렉터리는 세션이 끝날 때 자동으로 정리되므로 별도 정리 단계가 없습니다. 어느 디렉터리가 제거되고 어느 것이 재개된 세션에 남는지는 아키텍처를 보세요.

훅으로 품질 게이트 강제

훅으로 팀원이 작업을 끝내거나 작업이 생성·완료될 때 규칙을 강제하세요:

TeammateIdle: 팀원이 유휴로 가려 할 때 실행. 코드 2로 종료하면 피드백을 보내고 팀원을 계속 작업하게 함
TaskCreated: 작업이 생성될 때 실행. 코드 2로 종료하면 생성을 막고 피드백을 보냄
TaskCompleted: 작업이 완료로 표시될 때 실행. 코드 2로 종료하면 완료를 막고 피드백을 보냄

에이전트 팀이 동작하는 방식

이 절은 에이전트 팀 뒤의 아키텍처와 메커니즘을 다룹니다. 사용을 시작하려면 위의 에이전트 팀 제어를 보세요.

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

팀을 시작하려면 팀원을 요청하세요. 에이전트 팀이 활성화된 동안 Claude가 Agent 도구를 name과 함께 호출하면 팀원을 시작합니다. 단, 호출이 포크이거나 호출 자체에 isolation을 전달하면 예외입니다. Claude Code는 시작을 확인하라고 묻지 않습니다.

Claude는 나중에 메시지를 보내기 위해 평범한 서브에이전트에도 스스로 이름을 붙입니다. 그 호출들도 같은 규칙을 따르므로, 요청하지 않아도 팀이 형성될 수 있습니다. 서브에이전트를 원한다면 에이전트 팀 끄기를 하세요.

아키텍처

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

구성 요소	역할
팀 리드	팀원을 생성하고 작업을 조율하는 메인 Claude Code 세션
팀원	각자 배정된 작업을 하는 별도 Claude Code 인스턴스
작업 목록	팀원이 청구하고 완료하는 작업 항목의 공유 목록
메일박스	에이전트 간 소통용 메시징 시스템

각 에이전트의 메일박스는 ~/.claude/teams/{team-name}/inboxes/{agent-name}.json의 JSON 파일입니다. Claude Code는 메일박스 파일을 읽을 때마다 모든 항목을 검증합니다. 메시지 형식과 일치하지 않는 항목은 오류로 보고되고 파일에서 제거됩니다. 유효한 메시지는 여전히 전달됩니다. v2.1.207 이전에는 잘못된 단일 메일박스 항목이 매초 반복 오류를 일으키고 직접 파일을 삭제할 때까지 그 메일박스의 전달을 막았습니다.

Claude Code는 메시지가 일반 텍스트든 계획 승인·종료 요청 같은 구조화 프로토콜 메시지든, 수신자 메일박스 파일에 대한 쓰기가 성공할 때만 메시지를 보냈다고 보고합니다. 쓰기가 실패하면(예: 디스크가 가득 차거나 메일박스 디렉터리가 쓰기 불가능), 보내는 에이전트가 오류를 받고 아무것도 보내지 않습니다. 오류 메시지와 복구 단계는 팀원 인박스에 쓰기 실패를 보세요.

Claude Code는 작업 의존성을 자동으로 관리합니다: 팀원이 다른 작업이 의존하는 작업을 완료하면 사용자의 어떤 조치 없이 의존 작업을 차단 해제합니다.

팀과 작업은 세션에서 파생된 이름 아래 로컬에 저장됩니다. 이름은 session-에 이어 세션 ID의 처음 8자를 붙인 것입니다:

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

Claude Code는 세션 시작 시 이 둘을 자동으로 생성하고 팀원이 합류하거나 유휴로 가거나 떠날 때 업데이트합니다. 팀 설정 디렉터리는 세션이 끝날 때 제거됩니다. 작업 목록 디렉터리는 로컬에 남고 절대 업로드되지 않으므로 재개된 세션이 작업을 유지합니다. 보존은 세션 트랜스크립트에 대해 이미 제어하는 cleanupPeriodDays와 동일하게 보존 정리 규칙을 따릅니다.

팀 설정은 세션 ID, tmux 팬 ID 같은 런타임 상태를 담으므로 손으로 편집하거나 사전 작성하지 마세요. 다음 상태 업데이트에서 변경이 덮어써집니다.

재사용 가능한 팀원 역할을 정의하려면 서브에이전트 정의를 쓰세요.

팀 설정은 각 구성원의 이름과 에이전트 ID를 가진 members 배열을 담습니다. 리드의 항목은 항상 team-lead 에이전트 유형을 가집니다. 팀원의 항목은 생성 시 리드가 이름 지은 에이전트 유형(내장 유형 또는 서브에이전트 정의)을 가지며, 리드가 이름을 지지 않으면 필드를 생략합니다. 팀원은 이 파일을 읽어 다른 팀원을 발견할 수 있습니다.

팀 설정의 프로젝트 수준 동치는 없습니다. 프로젝트 디렉터리의 .claude/teams/teams.json 같은 파일은 설정으로 인식되지 않습니다. Claude는 그것을 평범한 파일로 취급합니다.

팀원에 서브에이전트 정의 사용

어느 표시 모드에서든 팀원을 생성할 때 프로젝트, 사용자, 관리 서브에이전트 스코프의 서브에이전트 유형을 참조할 수 있습니다. 이를 통해 security-reviewer나 test-runner 같은 역할을 한 번 정의하고 위임된 서브에이전트와 에이전트 팀 팀원으로 모두 재사용할 수 있습니다.

서브에이전트 정의를 쓰려면 팀원을 생성하라고 요청할 때 이름을 지으세요:

Spawn a teammate using the security-reviewer agent type to audit the auth module.

Claude Code는 지명한 서브에이전트 정의를 읽고 이 부분들을 팀원에 적용합니다. 어떤 부분이 팀원의 표시 모드에 의존하면 항목이 그렇게 말합니다:

tools: Claude Code는 팀원을 정의의 tools 목록의 도구로 제한합니다. 인프로세스 팀원에게는 SendMessage를 그 목록에 더하고, Task 도구를 가진 세션에서는 TaskCreate, TaskGet, TaskList, TaskUpdate도 더합니다.
model: 생성 프롬프트가 명명하지 않을 때 어느 표시 모드에서든 Claude Code는 정의의 model을 사용합니다. Claude Code가 팀원 모델을 고르는 방법을 보세요.
본문: 인프로세스 팀원에게 Claude Code는 정의의 본문을 기본 시스템 프롬프트에 추가 지침으로 덧붙입니다. 분할 창 팀원에게는 기본 시스템 프롬프트 대신 본문을 사용합니다.
skills: Claude Code는 어느 표시 모드에서든 정의의 skills를 팀원에 적용하지 않습니다. 팀원은 프로젝트와 사용자 설정에서 스킬을 로드합니다.
mcpServers: 분할 창 팀원에게 Claude Code는 그 필드에 대한 규칙 아래에서 정의의 mcpServers를 적용합니다. 이 규칙은 --agent로 시작된 세션도 덮습니다. 인프로세스 팀원은 필드를 무시하고 프로젝트·사용자 설정에서 MCP 서버를 로드합니다.

권한

팀원은 리드의 권한 모드로 시작하지만, 상속하지 않는 dontAsk 모드는 예외입니다. 리드가 --dangerously-skip-permissions로 실행하면 모든 팀원도 그렇게 합니다. 생성 후 개별 팀원의 권한 모드를 바꿀 수 있지만, 생성 시점에 팀원별 권한 모드를 설정할 수는 없습니다.

팀원 권한 프롬프트는 리드 세션에 나타나므로 거기서 직접 승인하세요. 계획 승인은 설계된 예외입니다: 리드 세션은 별도 프롬프트 없이 팀원 계획 승인을 부여합니다.

에이전트 간 메시지

한 에이전트가 SendMessage로 다른 에이전트에게 메시지를 보내면 Claude Code는 수신 에이전트에게 그 메시지가 (사용자가 아니라) 다른 Claude 세션에서 왔다고 알립니다. 팀원은 사용자 대신 권한 프롬프트를 승인하거나 동의를 제공할 수 없으며, 거부당한 동작을 다른 팀원에게 중계해 검사를 우회할 수도 없습니다. 같은 규칙이 팀을 완전히 벗어난 다른 Claude Code 세션 중 하나에서 온 메시지에도 적용됩니다.

auto mode에서 분류기는 에이전트 간 메시지에 두 가지 검사를 적용합니다:

다른 에이전트에서 중계된 승인 주장을 사용자의 확인이 아닌 신뢰할 수 없는 입력으로 취급합니다.
일반 메시지든 종료 요청·계획 승인 응답 같은 구조화 프로토콜 메시지든, Claude Code가 전달하기 전에 각 메시지를 검토합니다. 차단된 메시지는 수신자에게 도달하지 않습니다.

컨텍스트와 소통

각 팀원은 자체 컨텍스트 창을 가집니다. 생성될 때 팀원은 일반 세션과 같은 프로젝트 컨텍스트(CLAUDE.md, MCP 서버, 스킬)를 로드합니다. 또한 리드에서 생성 프롬프트를 받습니다. 리드의 대화 이력은 이어지지 않습니다.

팀원이 정보를 공유하는 방법:

자동 메시지 전달: 팀원이 메시지를 보내면 수신자에게 자동으로 전달됩니다. 리드가 업데이트를 폴링할 필요가 없습니다.
유휴 알림: 팀원이 끝내고 멈추면 자동으로 리드에게 알리고 최종 답변을 포함합니다. API 오류로 턴이 끝난 팀원은 실패했음을 리드에게 알리고 오류 텍스트를 포함합니다.
공유 작업 목록: Task 도구를 가진 에이전트는 작업 상태를 보고 사용 가능한 작업을 청구할 수 있습니다.
팀원 메시징: 이름으로 특정 팀원 하나에게 메시지를 보냅니다. 모두에게 닿으려면 수신자마다 메시지를 하나씩 보내세요.

리드는 생성할 때 각 팀원에 이름을 붙이고, 어떤 팀원도 그 이름으로 다른 팀원에게 메시지를 보낼 수 있습니다. 이후 프롬프트에서 참조할 예측 가능한 이름을 얻으려면 생성 지침에서 각 팀원을 뭐라고 부를지 리드에게 말하세요.

토큰 사용량

에이전트 팀은 단일 세션보다 훨씬 많은 토큰을 씁니다. 각 팀원은 자체 컨텍스트 창을 가지며 토큰 사용량은 활성 팀원 수에 따라 늘어납니다. 리서치, 리뷰, 새 기능 작업에서는 추가 토큰이 보통 가치가 있습니다. 일상 작업에서는 단일 세션이 더 비용 효과적입니다. 사용 지침은 에이전트 팀 토큰 비용을 보세요.

인프로세스 팀원의 요청은 메인 대화의 캐시 TTL 버킷 밖에 있으므로 Claude 구독을 포함해 기본적으로 5분 동안 캐시를 유지합니다. 한 시간 유지하려면 subagentPromptCacheTtl을 1h로 설정하세요. API는 1시간 캐시 쓰기를 더 높은 요금으로 청구합니다.

사용 사례 예시

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

병렬 코드 리뷰 실행

단일 리뷰어는 한 번에 한 유형의 문제로 쏠리는 경향이 있습니다. 리뷰 기준을 독립 도메인으로 나누면 보안, 성능, 테스트 커버리지가 모두 동시에 충분한 주의를 받습니다. 프롬프트는 각 팀원에게 서로 겹치지 않도록 뚜렷한 렌즈를 배정합니다:

Spawn three teammates to review PR #142:
- 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."

적절한 팀 규모 선택

팀원 수에 하드 한계는 없지만 실용적 제약이 적용됩니다:

토큰 비용은 선형으로 확장: 각 팀원은 자체 컨텍스트 창을 가지며 독립적으로 토큰을 소비합니다. 자세한 내용은 에이전트 팀 토큰 비용 참조
조율 오버헤드 증가: 팀원이 많을수록 소통, 작업 조율, 충돌 가능성이 늘어남
수익 체감: 어느 지점을 넘으면 추가 팀원이 작업을 비례하게 빨라지지 않음

대부분의 워크플로에서 3~5명의 팀원으로 시작하세요. 이는 병렬 작업과 관리 가능한 조율을 균형 잡습니다. 독립 작업이 15개라면 팀원 3명이 좋은 출발점입니다.

팀원이 동시에 작업하는 혜택을 받을 때만 늘리세요. 집중된 팀원 3명이 흩어진 5명보다 자주 더 낫습니다.

작업을 적절히 크기 조정

너무 작음: 조율 오버헤드가 혜택을 초과
너무 큼: 체크인 없이 팀원이 너무 길게 작업해 낭비 위험 증가
딱 맞음: 함수, 테스트 파일, 리뷰 같은 명확한 산출물을 만드는 자족 단위

리드는 작업을 나누어 팀원에게 자동으로 배정합니다. 충분한 작업을 만들지 않으면 작업을 더 작은 조각으로 나누라고 요청하세요. 팀원당 5~6개 작업이 모두를 생산적으로 유지하고 누군가 막히면 리드가 작업을 재배정하게 합니다.

팀원이 끝나기를 기다리기

때로 리드는 기다리지 않고 스스로 작업을 구현하기 시작합니다. 이를 발견하면:

Wait for your teammates to complete their tasks before proceeding

리서치와 리뷰로 시작

에이전트 팀이 처음이라면 명확한 경계가 있고 코드 작성이 필요 없는 작업(PR 리뷰, 라이브러리 리서치, 버그 조사)으로 시작하세요. 이 작업들은 병렬 구현과 함께 오는 조율 문제 없이 병렬 탐색의 가치를 보여줍니다.

파일 충돌 피하기

두 팀원이 같은 파일을 편집하면 덮어쓰기가 생깁니다. 각 팀원이 다른 파일 집합을 소유하도록 작업을 나누세요.

모니터링과 조종

팀원의 진행을 확인하고, 안 되는 접근을 재지정하고, 발견이 들어올 때 종합하세요. 팀을 너무 오래 방치하면 낭비 위험이 커집니다.

트러블슈팅

팀원이 나타나지 않음

팀원을 생성하라고 요청한 후 나타나지 않으면:

인프로세스 모드에서는 팀원이 프롬프트 입력 아래 에이전트 패널에 나타납니다. 위·아래 화살표로 선택하고 Enter를 눌러 보세요.
유휴 후 사라진 팀원 행은 중지된 것이 아니라 숨겨진 것입니다. 전체 패널이 유휴가 된 후 30초에 유휴 행이 숨고 팀원의 다음 턴에 다시 나타납니다. 유휴 팀원이 3명 이상이면 남는 행들이 Enter로 펼치는 단일 N idle agents 행으로 접힙니다. 이름으로 팀원에게 메시지를 보내 숨은 행을 되살리세요.
Claude에게 준 작업이 팀을 정당화할 만큼 복잡한지 확인하세요. Claude는 작업에 따라 팀원을 생성할지 결정합니다.
분할 창을 명시적으로 요청했다면 tmux가 설치되고 PATH에 있는지 확인하세요:
```
which tmux
```
iTerm2는 it2 CLI가 설치되고 iTerm2 환경설정에서 Python API가 활성화됐는지 확인하세요.

Claude가 서브에이전트 대신 팀원 생성

에이전트 팀이 활성화된 동안 리드 세션에서 Claude가 이름을 붙인 서브에이전트는 팀원으로 시작합니다. Claude는 스스로 서브에이전트 이름을 붙일 수 있으므로, 팀 작업으로 프레이밍한 적 없는 위임 중에도 일어날 수 있습니다.

이름 붙은 서브에이전트를 다시 서브에이전트로 시작하게 하려면 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS를 0으로 설정해 에이전트 팀을 끄세요:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0"
  }
}

새 세션을 시작할 필요는 없습니다: Claude Code는 저장 시 설정 파일의 env 값을 실행 중인 세션에 다시 적용하고, Claude가 서브에이전트를 생성할 때마다 변수를 다시 읽으므로 다음에 Claude가 이름을 붙인 서브에이전트는 서브에이전트로 시작합니다.

사용자 settings.json에서 변수를 0으로 설정하면 셸 export를 덮습니다. 다른 설정 소스가 여전히 에이전트 팀을 활성화할 수 있습니다:

우선순위가 높은 설정 파일: 프로젝트 설정, 로컬 설정, --settings 페이로드가 사용자 설정 다음에 적용되므로 그 중 하나에서 변수를 1로 설정하는 env 항목이 이깁니다. 설정 우선순위를 보세요.
관리 설정: managed settings는 다른 모든 소스 뒤에 적용됩니다. 조직이 거기서 에이전트 팀을 활성화했다면 관리자에게 관리 값을 바꾸라고 요청하세요.

변경 후에도 Claude는 서브에이전트 이름을 계속 지을 수 있고, 그 이름은 SendMessage 주소로 계속 동작합니다. Claude는 완료 시 각 서브에이전트의 결과를 받습니다.

권한 프롬프트가 너무 많음

팀원 권한 요청이 리드로 올라와 마찰을 만들 수 있습니다. 팀원을 생성하기 전에 권한 설정에서 일반 작업을 미리 승인해 중단을 줄이세요.

에이전트가 일찍 멈춤

팀원은 회복 대신 오류를 만난 후 멈출 수 있습니다. 인프로세스 모드에서 에이전트 패널의 팀원을 선택하고 Enter를 누르거나 분할 모드에서 팬을 클릭해 출력을 확인한 후:

직접 추가 지침을 주기
작업을 계속할 교체 팀원 생성

리드나 다른 팀원의 메시지는 실패한 API 요청 재시도를 기다리는 인프로세스 팀원을 깨워 전체 재시도 지연을 기다리지 않고 즉시 재시도하게 합니다.

리드도 일찍 멈출 수 있습니다. 모든 작업이 실제로 완료되기 전에 팀이 끝났다고 판단하는 것입니다. 그렇다면 계속하라고 말하세요.

고아 tmux 세션

Claude Code 세션이 끝난 후 tmux 세션이 남으면 완전히 정리되지 않았을 수 있습니다. 세션을 나열하고 팀이 만든 것을 끝내세요:

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

한계

에이전트 팀은 실험적입니다. 알아두어야 할 현재 한계:

인프로세스 팀원으로 세션 재개 불가: /resume과 /rewind는 인프로세스 팀원을 복원하지 않습니다. 세션을 재개한 후 리드가 더 이상 존재하지 않는 팀원에게 메시지를 시도할 수 있습니다. 그렇다면 새 팀원을 생성하라고 리드에게 말하세요.
작업 상태가 지연될 수 있음: 팀원이 작업을 완료로 표시하지 않아 의존 작업을 막을 수 있습니다. 작업이 막힌 것처럼 보이면 작업이 실제로 끝났는지 확인하고 상태를 수동으로 업데이트하거나 리드에게 팀원을 재촉하라고 말하세요.
종료가 느릴 수 있음: 팀원은 종료 전에 현재 요청이나 도구 호출을 끝내므로 시간이 걸릴 수 있습니다.
세션당 팀 하나: 한 세션은 정확히 한 팀을 가지며 그 세션에 범위가 정해집니다. 추가 명명된 팀을 만들거나 세션 간 팀을 공유할 수 없습니다.
중첩 팀 없음: 팀원은 자기 팀원을 생성할 수 없습니다. 오직 리드만 팀을 관리할 수 있습니다.
인프로세스 팀원의 백그라운드 서브에이전트 없음: 인프로세스 팀원의 자체 서브에이전트는 포그라운드에서 실행됩니다. 팀원의 백그라운드 작업이 리드 프로세스보다 오래 살 수 없기 때문입니다. 팀원이 background: true를 설정한 정의의 서브에이전트를 생성하면 Claude Code가 오류를 반환합니다. 팀원의 run_in_background: true 요청도 Claude Code가 포그라운드·백그라운드를 고르는 방식에 설명된 대로 오류 또는 조용한 포그라운드 실행으로 실패합니다. 메인 대화에서 시작된 서브에이전트는 백그라운드 기본값을 따릅니다.
리드는 고정: 메인 세션은 수명 동안 리드입니다. 팀원을 리드로 승격하거나 리더십을 이전할 수 없습니다.
권한은 생성 시 설정: 팀원은 권한에 설명된 권한 모드로 시작합니다. 생성 후 개별 팀원의 권한 모드를 바꿀 수 있지만 생성 시점에 팀원별 권한 모드를 설정할 수는 없습니다.
분할 창은 tmux 또는 iTerm2 필요: 기본 인프로세스 모드는 어떤 터미널에서도 동작합니다. 분할 창 모드는 VS Code 통합 터미널, Windows Terminal, Ghostty에서 지원되지 않습니다.

다음 단계

병렬 작업과 위임의 관련 접근법 탐색:

가벼운 위임: 서브에이전트는 에이전트 간 조율이 필요 없는 작업에 더 좋은, 세션 안의 리서치·검증용 헬퍼 에이전트를 생성
자체 세션 간 메시징: 세션 간 메시징은 직접 실행하는 세션 사이에서 Claude가 발견 내용을 전달하게 함
수동 병렬 세션: Git 워크트리는 자동 팀 조율 없이 직접 여러 Claude Code 세션을 실행하게 함

Claude Code 세션 팀 조율하기