에이전트 팀

복잡한 작업을 위해 여러 Claude Code 에이전트가 함께 협업합니다

실험적 기능

에이전트 팀이란?

실험적

에이전트 팀은 여러 Claude Code 에이전트가 복잡한 작업에서 협업할 수 있는 실험적 기능입니다. 리드 에이전트가 팀원들을 조율하며, 공유 태스크 리스트와 메일박스 시스템을 통해 작업을 분배합니다.

에이전트 팀은 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 환경 변수를 활성화해야 합니다.

에이전트 팀 활성화

terminal
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

에이전트 팀은 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 환경 변수를 활성화해야 합니다.

팀 아키텍처

리드 에이전트

작업을 분해하고, 팀원에게 할당하며, 결과를 종합하는 오케스트레이터

팀원

할당된 하위 작업을 병렬로 처리하는 독립적인 에이전트 인스턴스

태스크 리스트

리드가 생성하고 팀원들이 선택하는 공유 작업 목록

메일박스

상태 업데이트와 결과를 위한 리드와 팀원 간 통신 채널

팀 설정

/teams 명령어 또는 SDK를 통해 프로그래밍 방식으로 에이전트 팀을 구성합니다.

1

팀 구성 정의

2

통신 패턴 구성

3

작업 배분 전략 설정

4

실행 및 모니터링

팀 만들기

팀원 정의가 포함된 팀 리드 에이전트를 정의하세요. 각 팀원은 자체 모델, 도구, 지시를 가집니다.

팀 크기

권장 팀 크기: 3-5 에이전트

작업 수

팀원당 5-6개 작업이 최적 처리량

예시: 팀 생성 프롬프트
> I need to refactor the authentication module.
> Split the work into 3 tasks:
>   1. Update the login flow (agent 1)
>   2. Migrate session management (agent 2)
>   3. Add OAuth2 support (agent 3)
> Use tmux mode so I can watch each agent work.

팀원 제어

팀 리드가 작업을 할당하고, 진행을 모니터링하며, 팀원을 리디렉트할 수 있습니다. 팀원은 작업이 완료되거나 도움이 필요할 때 메일박스를 통해 보고합니다.

팀원은 기본적으로 팀 리드의 권한 설정을 상속합니다

디스플레이 모드

인프로세스 모드

모든 에이전트가 단일 터미널 세션에서 실행됩니다. 적은 수의 에이전트로 간단한 조율 작업에 적합합니다.

권장

Tmux 모드

각 에이전트가 별도의 tmux 패널에서 실행되어, 동시에 작업하는 모든 에이전트를 시각적으로 확인할 수 있습니다. 복잡한 멀티 에이전트 워크플로우에 권장됩니다.

Tmux 모드 설정
# Install tmux (if not already installed)
# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux

# Start Claude with Agent Teams + tmux mode
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

iTerm2 분할 패널: macOS 사용자를 위한 네이티브 iTerm2 분할 패널

활용 사례

대규모 리팩토링

일관성을 유지하면서 여러 모듈을 동시에 리팩토링하도록 에이전트를 조율

병렬 테스트

여러 환경 또는 구성에서 테스트 스위트를 병렬로 실행

종합 코드 리뷰

보안, 성능, 스타일, 정확성에 대해 각각 다른 리뷰어를 배정

멀티서비스 개발

조율된 API로 프론트엔드와 백엔드 서비스를 동시에 개발

활용 사례

병렬 코드 리뷰

여러 에이전트가 코드베이스의 다른 부분을 동시에 리뷰 — 하나는 보안, 다른 하나는 성능, 또 다른 하나는 스타일을 확인.

경쟁 가설 디버깅

버그에 대한 다른 가설을 병렬로 조사하기 위해 여러 에이전트를 생성. 근본 원인을 먼저 찾는 에이전트가 승리.

대규모 리팩토링

대규모 리팩토링 작업을 에이전트에 분배, 각각 다른 모듈이나 파일 그룹을 처리.

모범 사례

  • 소규모 팀(2-3 에이전트)으로 시작하고 필요에 따라 확장하세요
  • 각 팀원에게 명확하고 집중된 작업과 잘 정의된 경계를 부여하세요
  • 2개 이상의 에이전트를 실행할 때는 tmux 모드를 사용하여 가시성을 높이세요
  • 조율 문제를 위해 메일박스를 정기적으로 모니터링하세요
  • 장시간 실행되는 작업에 적절한 타임아웃을 설정하세요
  • 리드 에이전트를 사용하여 팀원 출력을 검증하고 통합하세요

모범 사례 - 상세 가이드

팀을 작게 유지하세요 (3-5 에이전트) — 큰 팀은 조율 오버헤드가 더 큽니다

작업을 독립적으로 만드세요 — 에이전트는 자주 조율할 필요가 없을 때 가장 잘 작동합니다

각 팀원에게 명확하고 자체 완결적인 지시를 주세요

태스크 리스트를 사용하여 진행을 모니터링하고 할당을 조정하세요

에이전트가 같은 파일을 수정할 때 격리를 위해 git worktree를 사용하세요

제한사항

실험적 기능이며 변경될 수 있음

각 에이전트가 독립적인 컨텍스트를 가짐 — 공유 메모리 없음

복잡한 에이전트 간 조율은 불안정할 수 있음

여러 에이전트 실행은 비례적으로 API 비용이 증가