Claude Code Agent Teams: AI 여러 마리를 동시에 굴리는 법

Claude Code 세션 하나로 부족할 때가 있다. 보안 리뷰, 성능 분석, 테스트 커버리지를 동시에 돌리고 싶을 때. 프론트엔드, 백엔드, 테스트를 병렬로 작업하고 싶을 때.

Agent Teams는 여러 Claude Code 인스턴스를 팀으로 묶어서 병렬로 돌리는 실험적 기능이다. 팀 리더 하나가 작업을 배분하고, 팀원들이 각자 독립된 컨텍스트 윈도우에서 작업한다. 팀원끼리 직접 메시지를 주고받을 수도 있다.

환경변수 하나면 켜진다.

목차

• 활성화
• 서브에이전트와 뭐가 다른가
• 팀 구조
• 사용법: 자연어로 지시
  • 병렬 코드 리뷰
  • 경쟁 가설 디버깅
  • 모듈별 분업
• 팀원 간 통신
• 디스플레이 모드
• Plan Approval — 구현 전 계획 승인
• 비용: 단일 세션의 약 7배
• 알려진 제한사항
• 언제 쓰고 언제 안 쓰나
• 요약

활성화

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

또는 셸에서 직접:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

Claude Code v2.1.32 이상 필요. claude --version으로 확인.

서브에이전트와 뭐가 다른가

서브에이전트는 결과만 부모에게 보고한다. Agent Teams의 팀원은 서로 대화한다.

	서브에이전트	Agent Teams
컨텍스트	자체 윈도우, 결과만 부모에게 반환	자체 윈도우, 완전 독립
통신	부모에게만 보고	팀원끼리 직접 메시지
조율	메인 에이전트가 관리	공유 태스크 리스트 + 자율 조율
적합 용도	결과만 필요한 집중 작업	토론과 협업이 필요한 복잡한 작업
토큰 비용	낮음: 결과가 메인 컨텍스트에 요약	높음: 팀원마다 별도 인스턴스

팀 구조

구성요소	역할
Team Lead	팀 생성, 태스크 분배, 결과 종합
Teammates	각자 독립 Claude Code 인스턴스로 할당 태스크 수행
Task List	공유 태스크 목록 (pending → in-progress → completed) + 의존성 관리
Mailbox	에이전트 간 직접 메시지 시스템

리더는 고정이다. 승격이나 이양은 불가. 팀원은 자체 팀이나 팀원을 만들 수 없다(중첩 불가).

사용법: 자연어로 지시

팀 구성을 자연어로 설명하면 된다.

병렬 코드 리뷰

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.

이게 단일 세션과 결정적으로 다른 부분이다. 혼자 디버깅하면 첫 번째 가설에 앵커링된다. 여러 명이 서로 반박하면 살아남은 이론이 실제 원인일 확률이 훨씬 높다.

모듈별 분업

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

모델도 지정할 수 있다. 팀원에게는 Sonnet을 써서 비용을 줄이는 것이 공식 권장 사항이다.

팀원 간 통신

• message: 특정 팀원에게 1:1 메시지
• broadcast: 전체 팀원에게 동시 전송 (토큰 비용 주의)
• 메시지는 수신자에게 자동 전달 — 리더가 폴링할 필요 없음
• 팀원이 idle 상태가 되면 리더에게 자동 통보

리더가 spawn 시 팀원 이름을 지정하고, 이름으로 서로 메시지를 보낸다.

디스플레이 모드

모드	설명	요구 사항
In-process (기본)	메인 터미널에서 실행, Shift+Down으로 팀원 전환	없음
Split panes	팀원마다 별도 pane	tmux 또는 iTerm2

# 강제 in-process 모드
claude --teammate-mode in-process

Plan Approval — 구현 전 계획 승인

위험한 작업에는 팀원이 먼저 계획을 세우고, 리더가 승인해야 구현에 들어가도록 할 수 있다.

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

팀원이 읽기 전용 plan mode에서 계획 작성 → 리더가 리뷰 → 승인하면 구현 시작, 반려하면 피드백 받고 재작성.

비용: 단일 세션의 약 7배

공식 문서에 명시된 수치다. 팀원마다 자체 컨텍스트 윈도우를 갖기 때문에 토큰 사용량이 팀 크기에 비례해서 증가한다.

비용 절감 팁 (공식 권장):

• 팀원에 Sonnet 모델 사용 (Opus 대비 저렴)
• 팀 크기 3~5명으로 제한
• spawn 프롬프트를 간결하게 (CLAUDE.md, MCP 서버는 자동 로드됨)
• 작업 완료 후 반드시 cleanup (Clean up the team)
• 팀원당 5~6개 태스크가 최적

알려진 제한사항

제한	설명
세션 재개 불가	/resume, /rewind로 in-process 팀원 복원 안 됨
태스크 상태 지연	팀원이 완료 표시 누락 시 후속 태스크 block
종료 느림	현재 도구 호출 완료 후 종료
세션당 1팀	새 팀 전에 기존 팀 cleanup 필요
중첩 불가	팀원이 자체 팀 생성 불가
리더 고정	승격/이양 불가
Split pane 제한	VS Code 통합 터미널, Windows Terminal, Ghostty 미지원

언제 쓰고 언제 안 쓰나

쓸 때:

• 병렬 탐색이 가치 있는 작업 (코드 리뷰, 리서치, 가설 검증)
• 독립 모듈 개발 (프론트/백/테스트)
• 크로스레이어 작업 (각 레이어를 다른 팀원이 담당)

안 쓸 때:

• 순차적 작업 (A 끝나야 B 시작)
• 같은 파일을 여러 에이전트가 수정해야 할 때
• 단순/루틴 작업 (오버헤드 > 이득)

요약

• Agent Teams는 여러 Claude Code 인스턴스를 팀으로 묶어 병렬 작업하는 실험적 기능이다
• 환경변수 하나(CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)로 활성화
• 팀원끼리 직접 메시지를 주고받을 수 있다는 점이 서브에이전트와의 핵심 차이
• 토큰 비용은 단일 세션의 약 7배 — 팀원에 Sonnet 사용 권장
• 35명, 팀원당 56개 태스크가 최적

---

관련글:

• Claude Code KAIROS: 잠자는 동안 일하는 AI 백그라운드 에이전트의 구조 — 자율 에이전트의 내부 동작
• Claude Code ULTRAPLAN: 복잡한 설계를 클라우드에서 30분간 돌리는 구조 — 원격 실행으로 로컬 터미널 해방