Agent Teams 활용 가이드

Claude Code의 Agent Teams 기능을 활용하여 여러 에이전트가 병렬로 협업하는 방법을 안내합니다.

개요

Agent Teams는 하나의 "lead" 에이전트가 여러 "teammate" 에이전트에게 작업을 분배하여 병렬로 처리하는 기능입니다.

활성화 방법

Settings에서 활성화

// .claude/settings.json
{
  "agentTeams": {
    "enabled": true
  }
}

또는 환경변수로 활성화

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

Display Mode 설정

--teammate-mode CLI 플래그 또는 teammateMode 설정:

• auto (기본): tmux 감지 시 split, 아니면 in-process
• in-process: 단일 터미널 내 표시
• tmux: tmux/iTerm2 split panes

키보드 단축키

• Shift+Down: teammate 순환 전환
• Ctrl+T: task list 토글
• Enter: 작업 상세 보기
• Escape: 인터럽트

아키텍처

┌─────────────────────────────────────────┐
│                  Lead Agent              │
│  (사용자 요청 수신, 작업 분배, 결과 통합)    │
└──────┬──────────┬──────────┬────────────┘
       │          │          │
  ┌────▼───┐ ┌───▼────┐ ┌───▼────┐
  │Teammate│ │Teammate│ │Teammate│
  │   A    │ │   B    │ │   C    │
  └────────┘ └────────┘ └────────┘

Lead Agent

• 사용자의 요청을 분석하고 하위 작업으로 분해
• Task tool을 통해 teammate에게 작업 할당
• 각 teammate의 결과를 수집하여 통합 응답 생성
• 전체 작업의 진행 상태 관리

Teammate Agent

• Lead가 할당한 특정 작업 수행
• 독립적인 컨텍스트에서 실행 (fork)
• 결과를 Lead에게 반환
• 자체 도구 사용 가능 (Read, Write, Bash 등)

Task List 시스템

Agent Teams는 내장 Task List로 작업을 관리합니다:

TaskCreate → 작업 생성 (pending)
TaskUpdate → 상태 변경 (in_progress → completed)
TaskList   → 전체 작업 목록 조회
TaskGet    → 개별 작업 상세 조회

작업 상태 흐름

pending → in_progress → completed
                     ↘ deleted

의존성 관리

• addBlocks: 이 작업이 완료되어야 시작할 수 있는 작업
• addBlockedBy: 이 작업 시작 전 완료되어야 하는 작업

Display Mode

Inline (기본)

• 모든 에이전트의 출력이 순차적으로 표시
• 진행 상황을 실시간으로 확인 가능

Parallel View

• 각 에이전트의 작업이 별도 패널로 표시
• 병렬 진행 상태를 한눈에 파악

효과적인 사용 사례

1. 병렬 코드 리뷰

Lead: "이 PR의 3개 모듈을 리뷰해주세요"
  ├── Teammate A: auth 모듈 리뷰 (security-reviewer)
  ├── Teammate B: API 모듈 리뷰 (code-reviewer)
  └── Teammate C: UI 컴포넌트 리뷰 (code-reviewer)

2. 멀티모듈 동시 개발

Lead: "사용자 관리 기능을 추가하세요"
  ├── Teammate A: DB 스키마 + 마이그레이션
  ├── Teammate B: API 엔드포인트
  └── Teammate C: 프론트엔드 UI

3. 경쟁적 디버깅

Lead: "이 버그의 원인을 찾아주세요"
  ├── Teammate A: 로그 분석 접근
  ├── Teammate B: 코드 추적 접근
  └── Teammate C: 재현 시도 접근
→ 가장 먼저 원인을 찾은 결과 채택

4. 문서 + 코드 동시 작업

Lead: "API를 추가하고 문서도 업데이트하세요"
  ├── Teammate A: API 구현
  └── Teammate B: 문서 업데이트 (doc-updater)

5. 테스트 병렬 실행

Lead: "전체 테스트를 실행하고 실패하는 것들을 수정하세요"
  ├── Teammate A: 단위 테스트 실행 + 수정
  ├── Teammate B: 통합 테스트 실행 + 수정
  └── Teammate C: E2E 테스트 실행 + 수정

Best Practices

작업 분배 원칙

1. 독립적 작업만 병렬화: 서로 의존하는 작업은 순차 실행
2. 적절한 분할 크기: 너무 작은 작업은 오버헤드, 너무 큰 작업은 병렬화 이점 없음
3. 명확한 산출물 정의: 각 teammate가 무엇을 반환해야 하는지 명시
4. 충돌 방지: 같은 파일을 여러 teammate가 동시 수정하지 않도록 분배

에이전트 선택

• 전문 에이전트를 teammate로 활용 (security-reviewer, tdd-guide 등)
• 간단한 작업에는 haiku 모델, 복잡한 작업에는 sonnet/opus
• maxTurns 설정으로 비용 제어

결과 통합

• Lead가 각 teammate 결과를 검증 후 통합
• 충돌하는 결과가 있으면 Lead가 판단하여 해결
• 최종 결과를 사용자에게 요약하여 전달

비용 고려사항

비용 절감 팁

• 단순 조사/분석 → haiku
• 코드 작성 → sonnet
• 아키텍처 결정 → opus
• run_in_background: true로 비동기 실행

제한사항

1. 파일 충돌: 여러 teammate가 같은 파일을 수정하면 마지막 수정이 덮어씀
2. 컨텍스트 격리: teammate는 서로의 작업을 볼 수 없음 (Lead를 통해서만)
3. 에러 전파: teammate의 에러가 다른 teammate에 영향을 줄 수 있음
4. rate limit: 동시 API 호출 수 제한에 주의
5. 디버깅 어려움: 병렬 실행 시 문제 추적이 복잡해질 수 있음