에이전트 팀 (Agent Teams)
기준일: 2026-07-13 난이도: 고급 공식 기준: Agent Teams, Agents and parallel work
Agent Teams는 여러 Claude Code 세션을 하나의 팀으로 조정하는 실험적 기능입니다. 팀 리드는 공유 작업 목록을 관리하고, teammate는 각자 독립된 context window에서 일하며 서로 메시지를 주고받을 수 있습니다.
핵심 개념
| 구성 요소 | 역할 |
|---|---|
| Team lead | teammate를 생성하고 작업을 조정·통합하는 현재 세션 |
| Teammate | 독립 context window를 가진 별도 Claude Code 세션 |
| Shared task list | 대기·진행·완료 상태와 의존성을 공유하는 작업 목록 |
| Mailbox | lead와 teammate, teammate 사이의 메시지 전달 |
Agent Teams는 기본적으로 꺼져 있습니다. 현재 공식 문서 기준으로 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1을 설정해야 합니다. 팀 runtime 상태는 Claude Code가 자동 생성하므로 프로젝트에 임의의 팀 JSON/YAML registry를 미리 만들면 안 됩니다.
선택 기준
| 상황 | 권장 방식 |
|---|---|
| 결과만 필요한 좁은 조사·검증 | Subagent |
| 여러 세션을 한 화면에서 감독 | Agent view |
| 작업자끼리 직접 토론·조정해야 함 | Agent Teams |
| 대량 작업을 스크립트로 동적 분산 | Dynamic workflows |
Agent Teams는 각 teammate가 별도 context와 토큰을 사용하므로 단일 세션보다 비용과 조정 부담이 큽니다. 같은 파일을 여러 teammate가 수정하거나 순차 의존성이 강한 작업에는 적합하지 않습니다.
실습
사용자 설정 또는 환경 변수에서 실험 기능을 켭니다.
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
그다음 자연어로 독립 역할과 결과 형식을 지정합니다.
세 명의 teammate를 생성해 이 변경을 병렬 검토해줘.
- security-reviewer: 인증과 비밀정보 노출
- test-reviewer: 회귀 테스트와 누락 경계
- performance-reviewer: 렌더링과 번들 영향
각자 파일을 수정하지 말고 파일:줄 근거를 남겨.
모두 끝난 뒤 중복을 제거하고 심각도 순으로 통합해줘.
Claude Code는 첫 teammate가 생성될 때 팀을 구성합니다. 공식 문서상 팀 설정과 task 목록은 ~/.claude/teams/{team-name}/config.json, ~/.claude/tasks/{team-name}/ 아래에 runtime 데이터로 저장되며 직접 편집하는 설정 표면이 아닙니다.
표시 모드
in-process: 기본값. 한 터미널의 agent panel에서 teammate를 선택합니다.auto: tmux 또는 iTerm2 환경이면 split pane을 사용하고, 아니면 in-process로 동작합니다.tmux,iterm2: 해당 split pane 방식을 명시합니다.
단일 세션에서 표시 모드를 바꾸려면 공식 플래그를 사용합니다.
claude --teammate-mode auto
도구에 입력할 프롬프트
이 작업을 Agent Teams에 맡기기 적합한지 먼저 판단해줘.
독립적으로 병렬화할 수 있는 작업만 teammate에 배정하고,
각 teammate의 파일 소유권과 완료 조건을 명시해줘.
같은 파일을 두 teammate가 수정하지 않게 하고,
모든 teammate가 끝날 때까지 기다린 뒤 결과를 검증해줘.
체크리스트
- Agent Teams가 실험 기능임을 이해했다.
- 기능 활성화 환경 변수를 공식 이름으로 설정했다.
- 순차 작업이 아니라 독립 작업을 배정했다.
- teammate별 파일 소유권과 완료 조건을 정했다.
- teammate가 lead의 대화 기록을 자동 상속하지 않는 점을 고려했다.
- 권한 요청은 lead에서 직접 검토했다.
- 모든 teammate가 끝난 뒤 통합 테스트를 실행했다.
다음 단계
- 서브 에이전트에서 재사용 가능한 역할을 정의합니다.
- 권한 관리에서 teammate에 전달되는 권한을 제한합니다.
- 최신 운영 기능 맵에서 Agent view와 Dynamic workflows를 비교합니다.