Claude Code의 Agent 팀 기능은 여러 Claude Code 인스턴스들이 협력하여 공유된 작업을 수행하고, 상호 간에 메시지를 주고받으며, 중앙 집중식으로 관리될 수 있도록 Orchestration하는 experimental feature이다. 이 기능은 기본적으로 비활성화되어 있으며, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 환경 변수를 통해 활성화할 수 있다.

활용 시점 및 Subagent와의 비교:
Agent 팀은 여러 agents가 병렬적으로 문제를 탐색하는 것이 효율적인 작업에 가장 적합하다. 예를 들어, 연구 및 검토, 새 모듈 또는 기능 개발, 경쟁 가설을 통한 Debugging, 그리고 frontend, backend, test를 아우르는 Cross-layer coordination 등에 유용하다. 하지만, 단일 세션이나 Subagent 방식에 비해 Coordination overhead가 크고 Token 사용량이 현저히 많다.
Subagent는 호출자(caller)에게만 결과를 보고하며, 메인 agent가 모든 작업을 관리하는 반면, Agent 팀의 Teammate들은 완전히 독립적인 Context window를 가지며 서로 직접 메시지를 주고받는다. Subagent는 결과만 중요한 Focused task에 적합하고 Token cost가 낮지만, Agent 팀은 Teammate 간의 논의와 협업이 필요한 복잡한 작업에 적합하며 Token cost가 높다.

Agent 팀의 작동 방식 (Core Methodology):
Agent 팀은 Team lead, Teammates, Task list, 그리고 Mailbox의 네 가지 핵심 구성요소로 이루어진다.

1. Team lead: 사용자의 메인 Claude Code 세션으로, Agent 팀을 생성하고 Teammate를 Spawning하며 전체 작업을 조율한다.
2. Teammates: Lead에 의해 생성된 독립적인 Claude Code 인스턴스들이다. 각각 고유한 Context window를 가지며 할당된 작업을 수행한다. Teammate들은 CLAUDE.md, MCP servers, skills 등 Lead와 동일한 Project context를 로드하지만, Lead의 Conversation history는 상속받지 않는다.
3. Task list: Lead와 Teammate들이 공유하는 작업 목록이다. 작업은 pending, in progress, completed 상태를 가지며, 작업 간의 Dependency도 관리된다. Lead가 명시적으로 작업을 할당하거나 Teammate들이 스스로 다음 작업을 Claim할 수 있다. 작업 Claim 시 File locking을 사용하여 Race condition을 방지한다.
4. Mailbox: Agent들 간의 통신을 위한 메시징 시스템이다. Teammate들은 message 명령어를 사용하여 특정 Teammate에게 메시지를 보내거나, broadcast 명령어를 통해 모든 Teammate에게 동시에 메시지를 보낼 수 있다. 메시지는 자동으로 수신자에게 전달되며, Lead는 업데이트를 Polling할 필요가 없다. Teammate가 작업을 마치고 멈추면 자동으로 Lead에게 Idle notification을 보낸다.

팀 구성 및 작업 관리는 자연어 프롬프트를 통해 이루어진다. 사용자는 Lead에게 원하는 팀 구조와 작업을 설명하면, Lead가 그에 맞춰 Teammate를 Spawning하고 작업을 조율한다.
Teammate들의 Display mode는 in-process (메인 터미널 내에서 Shift+Up/Down으로 전환) 또는 split panes (tmux나 iTerm2 필요, 각 Teammate가 별도의 Pane을 가짐) 중 선택할 수 있다.
복잡하거나 위험한 작업의 경우, plan approval을 요구하여 Teammate가 작업을 실행하기 전 Lead의 승인을 받도록 할 수 있다. Lead는 Teammate의 계획을 검토하고 승인하거나 Feedback과 함께 거부한다.
Delegate mode는 Lead가 코드 변경에 직접 참여하지 않고, 오직 Teammate Spawning, 메시징, 종료, Task 관리 등 Coordination-only tools만 사용하도록 제한한다.
Agent 팀의 설정 및 Task 목록은 로컬 파일 시스템(~/.claude/teams/{team-name}/config.json, ~/.claude/tasks/{team-name}/)에 저장된다. config.json에는 members 배열이 포함되어 Teammate들이 다른 팀 멤버를 발견할 수 있게 한다.
Teammate들은 Lead의 Permission 설정을 상속받으며, 필요에 따라 개별 Teammate의 모드를 변경할 수 있다.

Token 사용량:
Agent 팀은 각 Teammate가 독립적인 Context window를 가지므로, 단일 세션보다 Token 사용량이 현저히 많다. Token 사용량은 활성 Teammate 수에 비례하여 증가한다.

주요 제약사항 (Limitations):
Agent 팀은 아직 experimental 단계이며, in-process Teammate와의 Session resumption 불가, Task 상태 지연, 종료 속도, 세션당 하나의 팀만 관리 가능, Nested team 불가능, Lead agent 고정, Permission 설정 방식 등의 제약사항이 존재한다.