에이전트 팀

여러 Claude Code 인스턴스를 팀으로 구성하여 공유 태스크, 에이전트 간 메시징, 중앙 관리를 통해 협업하는 기능입니다.

에이전트 팀이란?

에이전트 팀은 여러 Claude Code 인스턴스를 조율하여 함께 작업하게 합니다. 하나의 세션이 팀 리드 역할을 맡아 작업을 조율하고, 태스크를 할당하며, 결과를 종합합니다. 팀원들은 각자의 컨텍스트 윈도우에서 독립적으로 작업하며, 서로 직접 커뮤니케이션합니다.

서브에이전트와 달리, 에이전트 팀의 팀원들은 리드를 거치지 않고 개별 팀원에게 직접 메시지를 보낼 수 있습니다.

언제 사용할까?

에이전트 팀은 병렬 탐색이 실질적 가치를 더하는 작업에 가장 효과적입니다:

• 리서치 & 리뷰: 여러 팀원이 문제의 다른 측면을 동시에 조사하고, 서로의 발견을 공유하고 검증
• 새로운 모듈/기능: 팀원이 각자 별도의 영역을 담당하여 충돌 없이 개발
• 경쟁 가설 디버깅: 팀원들이 서로 다른 이론을 병렬로 테스트하여 더 빠르게 답을 찾음
• 크로스 레이어 조율: 프론트엔드, 백엔드, 테스트 등 각 레이어를 다른 팀원이 담당

서브에이전트와 비교

활성화 방법

settings.json에 환경변수를 설정하여 활성화합니다:

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

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

활성화 후, Claude에게 에이전트 팀 생성을 요청하고 태스크와 팀 구성을 자연어로 설명합니다.

CLI 도구를 설계하고 있어. 개발자들이 코드베이스에서 TODO 코멘트를 추적하는 도구야.
에이전트 팀을 만들어서 다양한 각도로 탐색해줘:
한 명은 UX, 한 명은 기술 아키텍처, 한 명은 반대 의견 역할.

Claude가 공유 태스크 리스트로 팀을 생성하고, 각 관점별 팀원을 스폰하고, 문제를 탐색한 뒤 결과를 종합합니다.

리드의 터미널에서 모든 팀원과 작업 현황을 확인할 수 있습니다. Shift+Down으로 팀원을 순환하며 직접 메시지를 보낼 수 있습니다.

팀 제어하기

리드에게 자연어로 원하는 것을 말하면 됩니다. 팀 조율, 태스크 할당, 위임을 처리합니다.

디스플레이 모드

기본값은 "auto"로, tmux 세션 내부에서 실행 중이면 split pane, 아니면 in-process를 사용합니다.

{
  "teammateMode": "in-process"
}

단일 세션에서 강제 지정:

claude --teammate-mode in-process

팀원 및 모델 지정

Claude가 태스크에 따라 팀원 수를 결정하거나, 직접 지정할 수 있습니다:

4명의 팀원으로 팀을 만들어서 이 모듈들을 병렬로 리팩토링해줘.
각 팀원은 Sonnet을 사용해.

계획 승인 요구

복잡하거나 위험한 작업에서 팀원이 구현 전에 계획을 세우도록 요구할 수 있습니다:

architect 팀원을 스폰해서 인증 모듈을 리팩토링해줘.
변경하기 전에 계획 승인을 받아야 해.

팀원이 계획을 완료하면 리드에게 승인 요청을 보냅니다. 리드가 승인하면 구현을 시작하고, 거부하면 피드백을 반영하여 계획을 수정합니다.

팀원과 직접 대화

각 팀원은 완전히 독립적인 Claude Code 세션입니다. 추가 지시, 후속 질문, 접근 방식 변경 등을 직접 보낼 수 있습니다.

• In-process 모드: Shift+Down으로 팀원 순환 후 메시지 입력
• Split pane 모드: 팀원의 pane을 클릭하여 직접 인터랙션

태스크 할당 및 클레임

공유 태스크 리스트가 팀 전체의 작업을 조율합니다. 태스크는 세 가지 상태를 가집니다: pending, in progress, completed. 태스크 간 의존성도 지원됩니다.

• 리드가 할당: 리드에게 어떤 태스크를 어떤 팀원에게 줄지 지시
• 셀프 클레임: 팀원이 작업을 완료한 후 다음 미할당 태스크를 자동으로 가져감

팀원 종료

researcher 팀원에게 종료를 요청해줘

리드가 종료 요청을 보내고, 팀원은 승인(정상 종료) 또는 거부(이유 설명)할 수 있습니다.

팀 정리

팀을 정리해줘

공유 팀 리소스를 제거합니다. 활성 팀원이 남아있으면 실패하므로, 먼저 팀원을 종료하세요.

훅으로 품질 게이트 적용

훅을 사용하여 팀원이 작업을 완료하거나 태스크가 끝날 때 규칙을 적용할 수 있습니다:

• TeammateIdle: 팀원이 유휴 상태가 되려 할 때 실행. 코드 2로 종료하면 피드백을 보내고 팀원이 계속 작업
• TaskCompleted: 태스크가 완료 처리될 때 실행. 코드 2로 종료하면 완료를 막고 피드백 전송

아키텍처

에이전트 팀은 다음 구성 요소로 이루어집니다:

팀과 태스크는 로컬에 저장됩니다:

• 팀 설정: ~/.claude/teams/{team-name}/config.json
• 태스크 리스트: ~/.claude/tasks/{team-name}/

권한

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

컨텍스트와 커뮤니케이션

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

정보 공유 방식:

• 자동 메시지 전달: 팀원이 메시지를 보내면 수신자에게 자동 전달
• 유휴 알림: 팀원이 작업을 마치면 자동으로 리드에 알림
• 공유 태스크 리스트: 모든 에이전트가 태스크 상태를 확인하고 가용 작업을 클레임

메시지 유형:

• message: 특정 팀원 한 명에게 메시지 전송
• broadcast: 모든 팀원에게 동시 전송 (팀 크기에 비례하여 비용 증가, 절약 사용)

사용 예시

병렬 코드 리뷰

PR #142를 리뷰할 에이전트 팀을 만들어줘. 리뷰어 3명을 스폰해:
- 한 명은 보안 관련 영향에 집중
- 한 명은 성능 영향 확인
- 한 명은 테스트 커버리지 검증
각자 리뷰하고 결과를 보고해줘.

각 리뷰어가 동일한 PR을 다른 필터로 분석하고, 리드가 모든 결과를 종합합니다.

경쟁 가설 조사

사용자들이 앱이 한 번 메시지 후 연결이 끊긴다고 보고했어.
5명의 에이전트 팀원을 스폰해서 다른 가설들을 조사해줘.
서로 대화하면서 상대의 이론을 반증하려고 시도하게 해,
과학적 토론처럼. 합의된 내용을 findings 문서에 업데이트해줘.

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

모범 사례

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

팀원은 프로젝트 컨텍스트를 자동 로드하지만, 리드의 대화 기록은 상속하지 않습니다. 스폰 프롬프트에 태스크별 세부 사항을 포함하세요:

보안 리뷰어 팀원을 스폰해줘. 프롬프트: "src/auth/의 인증 모듈을
보안 취약점 관점에서 리뷰해줘. 토큰 처리, 세션 관리, 입력 검증에 집중해.
앱은 httpOnly 쿠키에 저장된 JWT 토큰을 사용해.
심각도 등급과 함께 이슈를 보고해줘."

적절한 태스크 크기 설정

• 너무 작으면: 조율 오버헤드가 이점을 초과
• 너무 크면: 팀원이 체크인 없이 너무 오래 작업하여 낭비 위험 증가
• 적절한 크기: 명확한 산출물을 만드는 자체 완결적 단위 (함수, 테스트 파일, 리뷰 등)

팀원 완료 대기

리드가 팀원을 기다리지 않고 직접 구현을 시작하는 경우:

팀원들이 태스크를 완료할 때까지 기다려줘

리서치와 리뷰부터 시작

에이전트 팀이 처음이라면 코드 작성이 필요 없는 명확한 경계의 작업부터 시작하세요: PR 리뷰, 라이브러리 리서치, 버그 조사 등.

파일 충돌 방지

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

모니터링 및 방향 조정

팀원의 진행 상황을 확인하고, 효과 없는 접근 방식을 리다이렉트하며, 결과를 실시간으로 종합하세요. 팀을 너무 오래 방치하면 낭비 위험이 증가합니다.

트러블슈팅

팀원이 나타나지 않는 경우

• In-process 모드에서는 이미 실행 중일 수 있습니다. Shift+Down을 눌러 확인
• 태스크가 팀을 만들 만큼 복잡한지 확인
• Split pane을 요청했다면 tmux가 설치되어 있는지 확인:

  which tmux

너무 많은 권한 프롬프트

팀원의 권한 요청이 리드에게 올라와 방해가 됩니다. 팀원을 스폰하기 전에 권한 설정에서 일반적인 작업을 사전 승인하세요.

팀원이 에러로 중단되는 경우

팀원의 출력을 확인(Shift+Down 또는 pane 클릭)한 후:

• 직접 추가 지시를 보내거나
• 대체 팀원을 스폰하여 작업 계속

리드가 작업 완료 전 종료

리드가 모든 태스크가 완료되기 전에 팀이 끝났다고 판단할 수 있습니다. 이 경우 계속 진행하라고 지시하세요.

고아 tmux 세션

팀 종료 후 tmux 세션이 남아있으면:

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

제한 사항

에이전트 팀은 실험적 기능입니다. 알려진 제한 사항:

• In-process 팀원의 세션 재개 불가: /resume과 /rewind가 in-process 팀원을 복원하지 않습니다. 세션 재개 후 리드가 존재하지 않는 팀원에게 메시지를 보내려 할 수 있습니다. 이 경우 새 팀원을 스폰하도록 지시하세요.
• 태스크 상태 지연: 팀원이 태스크를 완료 처리하지 않아 의존 태스크가 차단될 수 있습니다. 작업이 실제로 완료되었는지 확인하고 수동으로 상태를 업데이트하세요.
• 종료가 느릴 수 있음: 팀원이 현재 요청이나 도구 호출을 마쳐야 종료됩니다.
• 세션당 하나의 팀: 리드는 한 번에 하나의 팀만 관리합니다. 새 팀을 시작하려면 현재 팀을 정리하세요.
• 중첩 팀 불가: 팀원은 자체 팀이나 팀원을 스폰할 수 없습니다. 리드만 팀을 관리합니다.
• 리드 고정: 팀을 생성한 세션이 평생 리드입니다. 팀원을 리드로 승격하거나 리더십을 이전할 수 없습니다.
• 스폰 시 권한 설정: 모든 팀원이 리드의 권한 모드로 시작합니다. 스폰 후 개별 변경은 가능하지만 스폰 시점에는 불가합니다.
• Split pane은 tmux/iTerm2 필요: 기본 in-process 모드는 모든 터미널에서 동작합니다. Split pane은 VS Code 통합 터미널, Windows Terminal, Ghostty에서 지원되지 않습니다.