DarkGarden

Topics

Sections

Claude Code Agent Teams 정리

10 min read

개요

Agent Teams는 여러 Claude Code 인스턴스가 팀으로 협업하는 실험적 기능이다. 하나의 세션이 Team Lead로 작업을 조율하고, 나머지 Teammates가 독립된 컨텍스트 윈도우에서 병렬로 작업하며 서로 직접 메시징한다.

Opus 4.6과 함께 research preview로 출시되었으며, 기본 비활성화 상태이다.

Subagent vs Agent Teams

SubagentAgent Teams
통신메인 에이전트에게만 결과 보고팀원끼리 직접 메시징
조율메인 에이전트가 관리공유 태스크 리스트로 자율 조율
컨텍스트단일 세션 내각자 독립 컨텍스트 윈도우
비용낮음 (결과 요약)높음 (각 팀원이 별도 인스턴스)
적합한 경우결과만 필요한 집중 작업토론/협업이 필요한 복잡 작업

Subagent는 심부름꾼, Agent Teams는 같은 방에서 소통하며 일하는 프로젝트 팀.

활성화 방법

기본 비활성화. 환경변수 또는 settings.json에 설정한다.

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

아키텍처

4개 구성요소

구성요소역할
Team Lead메인 세션. 팀 생성, 태스크 할당, 결과 종합
Teammates독립 Claude Code 인스턴스. 각자 컨텍스트 윈도우 보유
Shared Task List모든 에이전트가 볼 수 있는 중앙 작업 큐
Mailbox에이전트 간 메시징 시스템

저장 위치

  • Team config: ~/.claude/teams/{team-name}/config.json
  • Task list: ~/.claude/tasks/{team-name}/

컨텍스트와 통신

  • 각 팀원은 spawn 시 프로젝트 컨텍스트(CLAUDE.md, MCP 서버, skills)를 로드한다
  • Lead의 대화 히스토리는 이어받지 않는다
  • 통신 채널:
    • Message: 특정 팀원에게 전송
    • Broadcast: 전체 팀원에게 전송 (비용 주의)
    • Idle notification: 팀원 작업 완료 시 Lead에게 자동 알림
    • Shared task list: 전체 태스크 상태 공유

권한

  • 팀원은 Lead의 권한 설정을 상속받는다
  • --dangerously-skip-permissions 사용 시 모든 팀원도 동일 적용
  • spawn 이후 개별 팀원 모드 변경은 가능하지만, spawn 시점에는 불가

팀 시작 방법

자연어로 태스크와 팀 구조를 설명하면 Claude가 생성한다.

Create an agent team to refactor the payment module. Spawn three teammates:
one for the API layer, one for the database migrations, one for test coverage.
Have them coordinate through the shared task list.

모델 지정도 가능:

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

팀 생성 방식:

  1. 사용자 요청: 병렬 작업이 유리한 태스크에 팀 생성을 직접 요청
  2. Claude 제안: Claude가 팀이 유리하다고 판단하면 제안 → 사용자 승인 후 진행

디스플레이 모드

In-Process Mode (기본)

메인 터미널에서 모든 팀원이 실행된다. 별도 설정 불필요.

단축키기능
Shift+↑↓팀원 선택/메시지 전송
Enter팀원 세션 전체 보기
Escape팀원 현재 턴 중단
Ctrl+T태스크 리스트 토글

Split Pane Mode

각 팀원이 별도 터미널 패널에서 동시 출력. tmux 또는 iTerm2 필요.

tmux는 macOS에서 가장 잘 동작하며, iTerm2에서 tmux -CC가 권장 진입점이다.

설정

{
  "teammateMode": "in-process"  // "auto" | "tmux" | "in-process"
}

CLI 오버라이드:

claude --teammate-mode in-process
옵션동작
auto (기본)tmux 세션 안이면 split pane, 아니면 in-process
tmuxsplit pane 활성화, tmux/iTerm2 자동 감지
in-process메인 터미널에 강제

핵심 기능

Delegate Mode (Shift+Tab)

Lead가 코드를 직접 건드리지 않고 조율에만 집중하도록 제한한다. 팀 시작 후 Shift+Tab으로 활성화.

  • Lead는 spawn, messaging, shutdown, task 관리만 가능
  • 구현 작업은 팀원에게 위임

Plan Approval

팀원이 구현 전에 읽기 전용 모드로 계획을 먼저 세우고 Lead 승인 후 실행한다.

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

플로우:

  1. 팀원이 읽기 전용 모드로 계획 수립
  2. Lead에게 plan approval 요청 전송
  3. Lead가 승인 또는 피드백과 함께 거절
  4. 거절 시 수정 후 재제출
  5. 승인 시 구현 시작

직접 대화

Lead를 거치지 않고 개별 팀원에게 직접 메시지 가능.

  • In-process: Shift+↑↓로 팀원 선택 후 타이핑
  • Split pane: 해당 팀원 패널 클릭

태스크 관리

  • 태스크 상태: pending → in progress → completed
  • 의존성 지원: 선행 태스크 완료 시 자동 unblock
  • File locking으로 동시 claim 방지
  • Lead가 명시적 할당하거나 팀원이 자율적으로 claim

적합한 사용 사례

리서치/리뷰

여러 관점에서 동시 조사 후 상호 검증.

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage

새 모듈/기능

각 팀원이 별도 영역 담당, 파일 충돌 없이 병렬 개발.

경쟁 가설 디버깅 (킬러 유스케이스)

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.

여러 이론을 병렬 테스트하고 서로 반박하며 수렴 → anchoring bias 방지.

크로스 레이어 작업

frontend, backend, test를 각각 다른 팀원이 담당.

부적합한 경우

  • 순차적 작업
  • 같은 파일 편집
  • 의존성이 많은 작업

→ 단일 세션이나 subagent가 더 효율적.

팀 종료

개별 팀원 종료

Ask the researcher teammate to shut down

팀원은 현재 작업 완료 후 종료 (시간 소요 가능). 승인 또는 거절 가능.

팀 전체 정리

Clean up the team
  • 모든 팀원 종료 후 실행해야 함
  • 반드시 Lead를 통해 정리 (팀원이 직접 하면 안 됨)

Best Practices

  • 충분한 컨텍스트 제공: spawn prompt에 태스크별 세부사항 포함
  • 적절한 태스크 크기: 자기 완결적 단위, 팀원당 약 5~6개
  • 팀원 완료 대기: Lead가 팀원보다 먼저 진행하지 않도록
  • 리서치/리뷰 먼저: 감을 잡은 후 구현 작업으로 확장
  • 파일 충돌 방지: 팀원별로 다른 파일 담당
  • 진행 모니터링: 정기적으로 확인하고 방향 수정

트러블슈팅

문제해결
팀원이 안 보임Shift+↓ 확인, 태스크 복잡도 확인, tmux/iTerm2 설정 확인
권한 프롬프트 과다permission settings에서 공통 작업 사전 승인
팀원 에러로 중단추가 지시 또는 대체 팀원 spawn
Lead가 작업 완료 전 종료Lead에게 팀원 완료까지 대기하라고 지시
고아 tmux 세션tmux ls → tmux kill-session -t <name>

현재 제한사항

  • 세션 복원 불가: /resume, /rewind 시 in-process 팀원 복원 안 됨
  • 태스크 상태 지연: 팀원이 완료 표시를 빠뜨릴 수 있음
  • 느린 종료: 현재 작업 완료 후 종료
  • 세션당 1팀: 중첩 팀(nested teams) 불가
  • Lead 고정: 리더 교체/승격 불가
  • spawn 시점 권한 고정: 개별 팀원 권한은 spawn 이후에만 변경 가능
  • Split pane: tmux 또는 iTerm2만 지원
  • 토큰 비용: 팀원 수만큼 증가, broadcast는 더 높음

시작 가이드

  1. CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 설정

  2. 저위험 리뷰 태스크로 시작:

    Create an agent team to review PR #142. Spawn three reviewers:- One focused on security implications- One checking performance impact  - One validating test coverage

  3. 디버깅 태스크로 확장 (경쟁 가설 병렬 조사)

  4. 구현 태스크로 발전 (팀원별 파일 분리)

참고: 공식 문서 — https://code.claude.com/docs/en/agent-teams

그래프 뷰

Related Reports