에이전트 팀

에이전트 팀이란?

에이전트 팀(Agent Teams)은 여러 Claude Code 인스턴스를 하나의 팀으로 조율하는 모드입니다. 한 세션이 팀 리더 역할을 맡아 작업을 나누고 결과를 종합하며, 팀원들은 각자 독립된 컨텍스트 윈도우에서 작업하면서 서로 직접 메시지를 주고받습니다.

Claude Code 2.1.32 이상이 필요합니다. claude --version으로 확인하세요. 에이전트 팀은 실험 기능이고 기본적으로 비활성화되어 있으며, 세션 재개·작업 조율·종료 동작에 알려진 제한이 있습니다.

리더를 거치지 않고 개별 팀원과 직접 대화할 수도 있다는 점이 subagent와의 가장 큰 차이입니다.

공식 문서: Claude Code 세션 팀 조율하기 — code.claude.com/docs/ko/agent-teams

subagent와 어떻게 다른가

항목	subagent	에이전트 팀
컨텍스트	자체 컨텍스트 윈도우, 결과는 호출자에게 반환	자체 컨텍스트 윈도우, 완전히 독립적
통신	메인 에이전트에게만 결과 보고	팀원들이 서로 직접 메시지 전송
조율	메인 에이전트가 모든 작업 관리	공유 작업 목록으로 자체 조율
최적 용도	결과만 중요한 집중된 작업	토론·협업이 필요한 복잡한 작업
토큰 비용	낮음 — 결과만 메인 컨텍스트로 요약	높음 — 각 팀원이 별도 Claude 인스턴스

빠르고 집중된 워커가 필요할 때는 subagent를, 팀원들이 발견을 공유하고 서로 반박하며 자체적으로 조율해야 할 때는 에이전트 팀을 사용합니다.

활성화하기

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 환경 변수를 1로 설정합니다. 셸 환경 변수에 직접 추가하거나 ~/.claude/settings.json에서 설정할 수 있습니다.

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

첫 팀 만들기

활성화 후, Claude에게 자연어로 팀 구조와 작업을 설명하면 됩니다. 다음 예시는 세 역할이 서로 기다리지 않고 독립적으로 탐색할 수 있어 잘 동작합니다.

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Create an agent team to explore this from different angles: one
teammate on UX, one on technical architecture, one playing devil's advocate.

리더의 터미널에는 모든 팀원과 각자가 작업 중인 내용이 나열됩니다. Shift+Down으로 팀원들을 순환하며 직접 메시지를 보낼 수 있고, 마지막 팀원 다음에는 다시 리더로 돌아옵니다.

작업이 끝나면 리더에게 정리를 요청합니다.

Clean up the team

표시 모드 — in-process vs 분할 창

에이전트 팀은 두 가지 표시 모드를 지원합니다.

• in-process — 모든 팀원이 메인 터미널 안에서 실행됩니다. Shift+Down으로 순환하고 입력해서 메시지를 보냅니다. 어떤 터미널에서도 동작하며 추가 설정이 필요 없습니다.
• 분할 창(split panes) — 각 팀원이 별도 창을 가집니다. 모든 팀원의 출력을 한눈에 보고, 창을 클릭해 직접 상호작용할 수 있습니다. tmux 또는 iTerm2가 필요합니다.

기본값은 "auto"로, 이미 tmux 세션 안에서 실행 중이면 분할 창을, 아니면 in-process를 사용합니다. "tmux"로 설정하면 분할 창 모드를 강제하고 터미널에 따라 tmux 또는 iTerm2를 자동 감지합니다. ~/.claude/settings.json에서 재정의합니다.

{
  "teammateMode": "in-process"
}

단일 세션에서만 in-process로 강제하려면 플래그로 전달합니다.

claude --teammate-mode in-process

분할 창 모드는 tmux 또는 it2 CLI가 설치된 iTerm2가 필요합니다. 분할 창은 VS Code 통합 터미널, Windows Terminal, Ghostty에서는 지원되지 않습니다.

iTerm2 + tmux 셋업 (가장 간단한 조합)

분할 창은 tmux 단독 또는 iTerm2 + it2 CLI 두 가지 경로 중 하나만 충족하면 됩니다 — 둘을 같이 깔 필요가 없습니다. 공식 문서가 안내하는 가장 단순한 조합은 iTerm2 안에서 tmux -CC로 tmux 컨트롤 모드를 띄우는 방식으로, 이 경로에서는 it2 CLI나 iTerm2 Python API 설정이 필요하지 않습니다. tmux는 운영체제마다 동작 차이가 있고 전통적으로 macOS에서 가장 잘 동작합니다.

1. tmux 설치

brew install tmux

설치 후 PATH에서 동작하는지 확인합니다.

which tmux

2. iTerm2에서 tmux -CC로 진입

iTerm2를 새로 띄운 뒤 tmux -CC로 tmux 컨트롤 모드 세션을 시작합니다.

tmux -CC

iTerm2가 tmux 세션을 네이티브 창·탭으로 표시합니다. 이 상태에서 Claude Code를 실행하면 분할 창 모드가 자동으로 활성화됩니다 — 추가 설정은 필요 없습니다.

3. 동작 확인

teammateMode가 "auto" 또는 "tmux"인 상태에서 에이전트 팀을 만들어 보면, 각 팀원이 별도의 iTerm2 창으로 분리되어 열리는 것을 확인할 수 있습니다. 분할 창이 안 열리면 which tmux로 tmux가 PATH에 있는지 확인합니다.

tmux 없이 iTerm2만 쓰는 경우

tmux를 설치하고 싶지 않다면 iTerm2의 Python API를 통해 분할 창을 띄우는 별도 경로가 있습니다. 이 경우에만 it2 CLI 설치와 Python API 활성화가 필요합니다.

1. iTerm2 메뉴에서 Settings → General → Magic → Enable Python API를 활성화

2. it2 CLI 설치 — uv 또는 pip 중 편한 쪽 사용

   uv tool install it2

   uv가 없다면 pip install it2로 대체할 수 있습니다. it2는 macOS에서 iTerm2 3.3.0 이상과 Python 3.10 이상을 요구합니다.

대부분의 경우 위의 tmux + tmux -CC 방식이 더 단순하고 안정적이므로 이쪽을 먼저 시도하는 것을 권장합니다.

in-process 모드 단축키

분할 창 없이 메인 터미널 안에서만 사용할 때 알아두면 좋은 단축키입니다.

단축키	동작
Shift+Down	팀원들을 순환 (마지막 다음 리더로)
Enter	선택한 팀원의 세션 진입
Escape	현재 턴 중단
Ctrl+T	작업 목록 토글

팀 제어하기

리더에게 자연어로 지시하면 팀 조율, 작업 할당, 위임을 알아서 처리합니다.

팀원 수와 모델 지정

Claude가 작업에 따라 팀원 수를 자동으로 결정하지만, 직접 지정할 수도 있습니다.

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

계획 승인 요구

복잡하거나 위험한 작업은 팀원이 구현 전 계획을 세우고 리더 승인을 받도록 강제할 수 있습니다. 팀원은 리더 승인이 떨어질 때까지 읽기 전용 plan mode에서 동작합니다.

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

리더가 자율적으로 승인 결정을 내리므로, 판단 기준을 프롬프트에 넣어두면 좋습니다 (예: “테스트 커버리지가 포함된 계획만 승인”, “DB 스키마를 수정하는 계획은 거부”).

팀원과 직접 대화

각 팀원은 완전히 독립된 Claude Code 세션입니다. 추가 지시를 주거나 후속 질문을 하거나 접근을 재지정할 때 직접 메시지를 보냅니다.

• in-process — Shift+Down으로 순환 후 입력. Enter로 세션 진입, Escape로 현재 턴 중단, Ctrl+T로 작업 목록 토글
• 분할 창 — 팀원의 창을 클릭해 직접 상호작용. 각 팀원은 자기 터미널의 전체 보기를 가짐

작업 할당과 자체 요청

공유 작업 목록이 팀 전체 작업을 조율합니다. 작업은 대기 중 / 진행 중 / 완료 세 상태를 가지고 다른 작업에 의존할 수 있습니다. 의존성이 미해결이면 의존 작업이 완료될 때까지 요청할 수 없습니다.

• 리더 할당 — 리더에게 어느 작업을 어느 팀원에게 줄지 명시
• 자체 요청 — 작업을 마친 팀원이 다음 미할당·미차단 작업을 스스로 선택

작업 요청에는 파일 잠금이 적용되어 여러 팀원이 동시에 같은 작업을 가져가는 경합을 막습니다.

팀원 종료와 팀 정리

팀원 세션을 우아하게 종료하려면:

Ask the researcher teammate to shut down

리더가 종료 요청을 보내면 팀원은 승인하고 종료하거나 사유와 함께 거부할 수 있습니다. 작업이 모두 끝나면 리더에게 팀 정리를 요청합니다.

Clean up the team

정리는 반드시 리더가 실행해야 합니다. 팀원은 자기 팀 컨텍스트를 올바르게 해소하지 못해 리소스가 일관성 없는 상태로 남을 수 있습니다.

작동 원리

에이전트 팀은 다음 네 가지 구성 요소로 이루어집니다.

구성 요소	역할
팀 리더	팀을 만들고 팀원을 생성하며 작업을 조율하는 메인 Claude Code 세션
팀원	할당된 작업을 처리하는 별도의 Claude Code 인스턴스
작업 목록	팀원이 요청·완료하는 공유 작업 항목 목록
메일박스	에이전트 간 메시징 시스템

팀과 작업은 로컬에 저장됩니다.

• 팀 구성: ~/.claude/teams/{team-name}/config.json
• 작업 목록: ~/.claude/tasks/{team-name}/

팀 구성은 세션 ID와 tmux 창 ID 같은 런타임 상태를 보유하므로 수동으로 편집하거나 사전 작성하지 않습니다 — 다음 상태 업데이트에서 덮어써집니다.

각 팀원은 자기 컨텍스트 윈도우에서 동작합니다. 생성 시 일반 세션과 동일하게 CLAUDE.md, MCP server, skill을 로드하지만 리더의 대화 기록은 전달되지 않습니다. 작업별 세부 정보는 생성 프롬프트에 명시적으로 포함해야 합니다.

subagent 정의를 팀원으로 재사용

팀원을 생성할 때 프로젝트·사용자·플러그인·CLI 정의 등 모든 범위의 subagent 유형을 이름으로 참조할 수 있습니다. 한 번 정의한 역할(security-reviewer, test-runner 등)을 위임된 subagent와 팀원 양쪽에서 재사용하기 위함입니다.

Spawn a teammate using the security-reviewer agent type to audit the auth module.

팀원은 정의의 tools 허용 목록과 model을 따르며, 정의 본문은 시스템 프롬프트에 추가 지시로 덧붙습니다(대체 아님). SendMessage나 작업 관리 도구 같은 팀 조율 도구는 tools가 다른 도구를 제한해도 항상 사용할 수 있습니다.

다만 subagent 정의의 skills와 mcpServers frontmatter 필드는 팀원으로 실행될 때 적용되지 않습니다. 팀원은 일반 세션과 동일하게 프로젝트·사용자 설정에서 skill과 MCP server를 로드합니다 — subagent 정의에만 묶어둔 skill·MCP가 있다면 팀원에서는 동작하지 않으니 주의합니다.

추천 사용 사례

병렬 코드 리뷰

단일 리뷰어는 한 번에 한 가지 유형의 문제로 기우는 경향이 있습니다. 리뷰 기준을 독립 도메인으로 분할해 보안·성능·테스트 커버리지가 동시에 충분히 검토되도록 합니다.

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.

경쟁 가설 디버깅

원인이 불명확할 때 단일 에이전트는 그럴듯한 설명 하나에 머물기 쉽습니다. 팀원을 명시적으로 적대적으로 만들면 서로의 이론을 반박하면서 진짜 원인에 수렴합니다.

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. Update the findings doc with whatever consensus emerges.

순차 조사는 한 이론이 먼저 탐색되면 후속 조사가 그쪽으로 편향되는 앵커링에 취약합니다. 여러 독립 조사자가 적극적으로 서로를 반박할 때 살아남는 이론이 실제 근본 원인일 가능성이 훨씬 높습니다.

hooks로 품질 게이트

팀원 작업 종료, 작업 생성·완료 시점에 규칙을 강제할 때 hooks를 사용합니다. 종료 코드 2로 종료하면 피드백을 보내고 동작을 차단합니다.

Hook	시점	종료 코드 2의 효과
TeammateIdle	팀원이 유휴 상태로 들어가려 할 때	피드백을 보내고 팀원을 계속 작업하게 함
TaskCreated	작업이 생성될 때	생성을 차단하고 피드백 전달
TaskCompleted	작업이 완료로 표시될 때	완료를 차단하고 피드백 전달

모범 사례

• 충분한 컨텍스트 제공 — 팀원은 CLAUDE.md·MCP·skill을 자동으로 로드하지만 리더의 대화 기록은 상속하지 않습니다. 생성 프롬프트에 작업별 세부 정보(파일 경로, 사용 라이브러리, 보고 형식)를 명시합니다.
• 3~5명 팀 크기에서 시작 — 토큰 비용이 선형으로 증가하고 조율 오버헤드가 커집니다. 팀원당 5~6개 작업을 유지합니다.
• 작업을 적정 크기로 — 너무 작으면 조율 비용이 이득을 넘고, 너무 크면 체크인 없이 너무 오래 작업해 낭비 위험이 커집니다. 함수, 테스트 파일, 검토처럼 자체 완결된 단위가 적당합니다.
• 파일 충돌 회피 — 두 팀원이 같은 파일을 편집하면 덮어쓰기가 발생합니다. 각 팀원이 다른 파일 집합을 소유하도록 작업을 나눕니다.
• 모니터링·조율 — 팀을 무인으로 너무 오래 돌리지 않습니다. 작동하지 않는 접근은 재지정하고, 결과가 들어올 때마다 종합합니다.
• 연구·검토 작업으로 시작 — 처음이라면 PR 리뷰, 라이브러리 조사, 버그 조사처럼 코드 작성이 필요 없는 작업으로 시작해 병렬 탐색의 가치를 먼저 체감합니다.

알려진 제한

에이전트 팀은 실험 기능입니다. 다음 제한을 알아두세요.

• in-process 팀원의 세션 재개 미지원 — /resume과 /rewind는 in-process 팀원을 복원하지 않습니다. 재개 후 리더가 더 이상 존재하지 않는 팀원에게 메시지를 보내려고 할 수 있습니다. 이 경우 새 팀원 생성을 지시합니다.
• 작업 상태 지연 가능성 — 팀원이 작업을 완료로 표시하지 못해 의존 작업이 막힐 수 있습니다. 막힌 듯하면 실제 작업 완료 여부를 확인하고 수동으로 상태를 업데이트하거나 리더에게 팀원을 재촉하라고 지시합니다.
• 종료가 느릴 수 있음 — 팀원은 현재 요청·도구 호출을 마친 뒤 종료됩니다.
• 세션당 한 팀 — 리더는 한 번에 한 팀만 관리합니다. 새 팀을 시작하기 전에 현재 팀을 정리합니다.
• 중첩 팀 불가 — 팀원은 자기 팀이나 팀원을 생성할 수 없습니다. 리더만 팀을 관리합니다.
• 리더 고정 — 팀을 만든 세션이 수명 동안 리더입니다. 팀원을 리더로 승격하거나 리더십을 이전할 수 없습니다.
• 권한은 생성 시 고정 — 모든 팀원은 리더의 권한 모드로 시작합니다. 생성 후 개별 팀원 모드를 바꿀 수는 있지만 생성 시점에 팀원별로 다르게 설정할 수는 없습니다.
• 분할 창은 tmux 또는 iTerm2 한정 — 기본 in-process는 어디서나 동작합니다. 분할 창은 VS Code 통합 터미널, Windows Terminal, Ghostty에서 지원되지 않습니다.

문제 해결

팀원이 보이지 않을 때

• in-process 모드라면 이미 실행 중이지만 화면에 없을 수 있습니다. Shift+Down으로 활성 팀원을 순환합니다.

• Claude가 작업이 팀을 보증할 만큼 복잡하지 않다고 판단했을 수 있습니다. 작업 설명을 구체화합니다.

• 분할 창을 명시 요청했다면 tmux가 PATH에 있는지 확인합니다.

  which tmux

• tmux 없이 iTerm2 단독 모드로 쓰고 있다면 it2 CLI 설치와 Python API 활성화 여부를 확인합니다.

권한 프롬프트가 너무 많을 때

팀원의 권한 요청은 모두 리더로 올라옵니다. 팀을 생성하기 전에 권한 설정에서 자주 쓰는 동작을 사전 승인해 중단을 줄입니다.

팀원이 오류로 멈췄을 때

팀원은 오류를 만나면 복구하지 않고 멈출 수 있습니다. 출력을 확인한 뒤 직접 추가 지시를 주거나 대체 팀원을 생성합니다.

고아 tmux 세션

팀이 끝났는데 tmux 세션이 남아 있다면 정리가 완전히 되지 않은 것입니다. 세션을 나열하고 팀이 만든 세션을 종료합니다.

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

다음 단계

• Subagent로 작업 분리하기 — 결과만 받으면 되는 가벼운 위임 패턴
• Plan mode — 계획 승인 요구를 활용할 때 함께 보면 좋은 가이드
• Hooks 자동화 — TeammateIdle 등 팀 조율 hook 활용