Claude Code Agent Teams - 에이전트 팀 오케스트레이션 가이드

여러 Claude Code 인스턴스를 팀으로 조율하여 병렬 작업을 수행하는 방법 가이드

저자: Anthropic

Agent Teams는 여러 Claude Code 인스턴스가 협업하도록 조율하는 기능입니다

팀 리더가 작업 분배, 팀원들은 독립적으로 작업 후 결과를 공유합니다

Subagents와 달리 팀원끼리 직접 소통이 가능합니다

연구/리뷰, 병렬 디버깅, 새 모듈 개발에 최적화되어 있습니다

실험적 기능으로 기본 비활성화 상태입니다

Agent Teams 아키텍처

Agent Teams란?

Agent Teams는 여러 Claude Code 인스턴스가 팀으로 함께 작동하도록 조율하는 기능입니다.

핵심 구조:

팀 리더: 작업을 조율하고, 태스크를 할당하며, 결과를 종합합니다
팀원들: 각자 독립적인 컨텍스트 윈도우에서 작업합니다
공유 태스크 리스트: 팀원들이 작업을 가져가고 완료 표시를 합니다
메일박스: 에이전트 간 직접 메시징 시스템입니다

Subagents와의 차이점:

Subagents: 단일 세션 내에서 실행, 메인 에이전트에게만 보고
Agent Teams: 팀원끼리 직접 소통 가능, 리더를 거치지 않고 대화

언제 Agent Teams를 사용하나?

Agent Teams가 효과적인 경우

연구 및 리뷰: 여러 팀원이 문제의 다른 측면을 동시에 조사, 발견 공유 및 검증
새 모듈/기능 개발: 각 팀원이 별도의 부분을 담당, 충돌 없이 작업
경쟁 가설로 디버깅: 여러 이론을 병렬로 테스트하여 더 빠르게 답 수렴
크로스 레이어 조율: 프론트엔드, 백엔드, 테스트를 각각 다른 팀원이 담당

Agent Teams가 적합하지 않은 경우

순차적 작업 (이전 결과에 의존하는 작업)
같은 파일 수정 (충돌 위험)
의존성이 많은 작업 -> 단일 세션이나 Subagents가 더 효과적

Subagents vs Agent Teams 비교

항목	Subagents	Agent Teams
컨텍스트	자체 컨텍스트, 결과를 호출자에게 반환	자체 컨텍스트, 완전히 독립적
커뮤니케이션	메인 에이전트에게만 보고	팀원끼리 직접 메시지 가능
조율	메인 에이전트가 모든 작업 관리	공유 태스크 리스트로 자체 조율
적합한 작업	결과만 필요한 집중 작업	토론과 협업이 필요한 복잡한 작업
토큰 비용	낮음: 결과가 요약되어 반환	높음: 각 팀원이 별도 인스턴스

선택 기준은 팀원들이 서로 소통해야 하는지 여부입니다. 빠른 결과만 필요하면 Subagents를, 발견 공유와 상호 검증이 필요하면 Agent Teams를 선택합니다.

시작하기

1. Agent Teams 활성화

Agent Teams는 기본적으로 비활성화되어 있습니다. settings.json에서 활성화합니다:

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

2. 첫 팀 시작하기

자연어로 팀 생성을 요청합니다:

개발자들이 코드베이스에서 TODO 코멘트를 추적하는 CLI 도구를 설계하고 있습니다.
다양한 관점에서 탐색할 에이전트 팀을 만들어주세요:
- UX 담당 팀원
- 기술 아키텍처 담당 팀원
- 악마의 대변인 역할 팀원

Agent Teams 워크플로우

팀 제어하기

디스플레이 모드

In-process: 모든 팀원이 메인 터미널 안에서 실행. Shift+Up/Down으로 팀원 선택
Split panes: 각 팀원이 자체 pane 사용. tmux 또는 iTerm2 필요

위임 모드 (Delegate Mode)

Shift+Tab을 눌러 위임 모드로 전환하면 리더가 직접 구현하지 않고 조율에만 집중합니다.

태스크 관리

태스크 상태

Pending (대기): 아직 시작되지 않음
In Progress (진행 중): 팀원이 작업 중
Completed (완료): 작업 완료

태스크 클레임은 파일 잠금을 사용하여 경쟁 상태를 방지합니다. 종속성이 완료되지 않은 태스크는 클레임할 수 없으며, 종속 태스크 완료 시 자동으로 차단이 해제됩니다.

실전 사용 사례

예시 1: 병렬 코드 리뷰

PR #142를 리뷰할 에이전트 팀을 만들어주세요. 세 명의 리뷰어를 생성하세요:
- 보안 영향에 집중하는 리뷰어
- 성능 영향을 확인하는 리뷰어
- 테스트 커버리지를 검증하는 리뷰어

예시 2: 경쟁 가설로 디버깅

사용자들이 앱이 연결을 유지하지 않고 하나의 메시지 후 종료된다고 보고합니다.
5명의 에이전트 팀원을 생성하여 다른 가설을 조사하세요.
팀원들이 과학적 토론처럼 서로의 이론을 반증하려고 대화하게 하세요.

베스트 프랙티스

팀원에게 충분한 컨텍스트 제공: 팀원은 리더의 대화 이력을 이어받지 않습니다
태스크 크기를 적절하게: 팀원당 5-6개의 태스크가 이상적입니다
팀원이 완료할 때까지 대기: 리더가 먼저 구현을 시작하지 않도록 합니다
연구와 리뷰로 시작: 코드 작성이 필요 없는 작업부터 시도합니다
파일 충돌 방지: 각 팀원이 다른 파일 세트를 담당하도록 분할합니다
모니터링 및 조정: 팀을 너무 오래 방치하면 낭비 위험이 증가합니다

제한 사항

세션 재개 불가: /resume, /rewind가 in-process 팀원을 복원하지 않습니다
세션당 하나의 팀만 운영 가능합니다
중첩 팀 불가: 팀원은 자체 팀이나 팀원 생성이 불가합니다
Split pane은 tmux 또는 iTerm2가 필요합니다

Agent Teams는 단일 세션보다 훨씬 많은 토큰을 사용합니다. 연구/리뷰/새 기능 작업에서는 추가 토큰 가치가 있지만, 일상적인 작업에서는 단일 세션이 더 비용 효율적입니다.

원문: Claude Code Agent Teams