Claude Agent Teams 완전 가이드

서론

Claude Code의 Subagent를 사용해본 적이 있다면, 병렬 개발이 이미 충분히 강력하다고 느꼈을 것입니다. 하지만 Subagent에는 한계가 있습니다. 메인 Agent에게 결과를 보고하는 것만 가능하며, 서로 소통할 수 없습니다.

Agent Teams는 이 상황을 완전히 바꿉니다. 상상해보십시오. 한 Agent가 보안 감사를 담당하고, 다른 Agent가 성능 최적화를 담당하며, 세 번째 Agent가 테스트 커버리지를 담당합니다. 이들은 병렬로 작업할 수 있을 뿐만 아니라, 직접 대화하고, 서로 도전하며, 합의에 도달할 수 있습니다. 이것이 Agent Teams의 핵심 가치입니다.

Agent Teams 이해하기

Agent Teams의 아키텍처는 실제 개발 팀과 매우 유사합니다.

┌─────────────────────────────────────────────────────────┐
│                     여러분 (사용자)                        │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                    Team Lead                             │
│            (메인 Claude 인스턴스, 조율 담당)                │
└─────────────────────────────────────────────────────────┘
         │              │              │
         ▼              ▼              ▼
┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│ Teammate 1  │  │ Teammate 2  │  │ Teammate 3  │
│  보안 감사   │◄─►│  성능 최적화  │◄─►│  테스트 커버리지│
└─────────────┘  └─────────────┘  └─────────────┘
         │              │              │
         └──────────────┼──────────────┘
                        ▼
              ┌─────────────────┐
              │   공유 작업 목록   │
              └─────────────────┘

Subagent와의 차이점

간단히 말하면: Subagent는 작업을 수행하러 보내는 하청업체이고, Agent Teams는 같은 방에서 협업하는 프로젝트 팀입니다.

Agent Teams가 효과적인 이유

핵심 통찰: 전문화가 집중을 가져옵니다.

단일 Agent가 복잡한 다단계 작업을 처리할 때, 컨텍스트가 계속 팽창하여 자주 /clear로 초기화해야 합니다. Agent Teams는 각 Teammate가 좁은 전문 영역을 유지하도록 하여 컨텍스트를 깨끗하게 유지하고, 성능이 더 안정적입니다.

Agent Teams 활성화

Agent Teams는 현재 실험적 기능으로, 기본적으로 비활성화되어 있습니다. 수동으로 활성화해야 합니다.

방법 1: 환경 변수

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

방법 2: settings.json (권장, 영구 적용)

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

핵심 사용법

첫 번째 Agent Team 생성

활성화 후, 자연어로 Claude에게 팀 생성을 요청하면 됩니다.

agent team을 생성하여 PR #142를 리뷰해줘.
세 명의 리뷰어를 생성해줘:
- 보안 문제에 집중하는 리뷰어
- 성능 영향을 확인하는 리뷰어
- 테스트 커버리지를 검증하는 리뷰어
각자 리뷰하고 발견 사항을 보고하게 해줘.

키워드 팁: "create an agent team" 또는 "spawn an agent team"을 사용하십시오. "spawn agents"만 말하면 Subagent와 Agent Teams가 혼동될 수 있습니다.

표시 모드

Agent Teams는 두 가지 표시 모드를 지원합니다.

기본값은 auto입니다. tmux에서 실행 중이면 split panes를 사용하고, 그렇지 않으면 in-process를 사용합니다.

표시 모드 설정:

{
  "teammateMode": "in-process"
}

단일 세션에서 지정:

claude --teammate-mode in-process

자주 사용하는 단축키

Delegate Mode (중요)

Delegate Mode는 Agent Teams의 가장 중요한 기능 중 하나입니다.

Delegate Mode가 필요한 이유:

이 제한이 없으면, Lead가 자주 "일을 빼앗아" 합니다. 세 명의 Teammates가 작업을 기다리고 있는데, Lead가 직접 코드를 작성하기 시작합니다. Delegate Mode를 활성화하면, Lead는 순수한 프로젝트 매니저로 강제됩니다. 작업 관리, Teammates와의 소통, 출력 검토만 가능합니다.

# 팀 시작 후 즉시 Shift+Tab을 눌러 활성화

실전 사례

사례 1: 병렬 코드 리뷰

단일 리뷰어는 특정 유형의 문제에 깊이 빠지기 쉽습니다. 리뷰 차원을 독립된 영역으로 분리하면 보안, 성능, 테스트 커버리지 모두 동등한 관심을 받을 수 있습니다.

agent team을 생성하여 이 PR을 리뷰해줘. 세 명의 리뷰어를 생성해줘:
- 보안 리뷰어: 인증, 권한, 인젝션 취약점 검사
- 성능 리뷰어: 알고리즘 복잡도, 데이터베이스 쿼리, 캐싱 전략 분석
- 테스트 리뷰어: 테스트 커버리지, 경계 조건, 오류 처리 검증

각자 리뷰한 후, 발견한 문제에 대해 서로 토론하게 해줘.

사례 2: 경쟁적 가설 디버깅

근본 원인이 불명확할 때, 단일 Agent는 그럴듯한 설명을 하나 찾으면 멈추는 경향이 있습니다. Teammates가 서로 도전하게 하면 이 문제를 피할 수 있습니다.

사용자가 앱에서 메시지를 하나 보내면 연결을 유지하지 않고 종료된다고 보고했습니다.

5개의 agent teammates를 생성하여 다른 가설을 조사하게 해줘. 서로 토론하며
서로의 이론을 반박하도록 하고, 과학적 토론처럼 진행해줘. 합의된 발견 사항을
조사 보고서에 업데이트해줘.

핵심 메커니즘: 토론 구조입니다. 여러 독립적인 조사자가 적극적으로 서로의 이론을 뒤집으려 시도하며, 최종적으로 살아남는 가설이 진정한 근본 원인일 가능성이 더 높습니다.

사례 3: 콘텐츠 대량 생산

비기술적 작업의 전형적인 활용입니다. 하나의 입력을 여러 출력으로 변환합니다.

agent team을 생성하여 이 영상 스크립트를 네 개 플랫폼의 콘텐츠로 변환해줘:
- LinkedIn 기사 작성자
- Twitter 스레드 작성자
- Newsletter 작성자
- 블로그 글 작성자

스크립트 위치: /content/scripts/video-20.md

각 Teammate가 독립적으로 작성하면서도 콘텐츠 일관성을 유지합니다.

사례 4: QA 품질 검사 클러스터

블로그 웹사이트의 품질 검사에 5개의 Agent를 배포하여 서로 다른 측면을 병렬로 테스트합니다.

agent team을 생성하여 블로그에 대한 전면적인 품질 검사를 수행해줘:
- Agent 1: 핵심 페이지 테스트 (홈페이지, 소개 페이지, 연락처 페이지)
- Agent 2: 글 페이지 테스트 (렌더링, 네비게이션, SEO 메타데이터)
- Agent 3: 링크 검사 (내부 링크, 외부 링크, 깨진 링크)
- Agent 4: SEO 검증 (제목, 설명, 구조화된 데이터)
- Agent 5: 접근성 테스트 (ARIA 라벨, 대비도, 키보드 네비게이션)

우선순위별로 정렬된 문제 보고서를 생성해줘.

효과: 원래 사람이 순차적으로 실행해야 했던 전면 검사를 몇 분 만에 완료합니다. 각 Agent가 자신의 영역에 집중하고, 마지막에 우선순위별로 정렬된 문제 목록으로 종합합니다.

사례 5: 다중 라운드 토론 모드

유용한 프롬프트 패턴으로, Teammates가 회의하듯 토론하게 합니다.

Agent Teams를 사용하여 4명의 teammates를 생성하고 [기술 결정]에 대해 토론하게 해줘.
3라운드 토론을 진행해줘. 각 라운드에서 teammates가 서로 교류하게 해줘.
한 teammate는 전담으로 Red Team 관점을 맡아 비판적 의견을 제시하게 해줘.

이 패턴은 아키텍처 결정, 기술 선택 등 다각도 비교가 필요한 시나리오에 특히 적합합니다.

사례 6: C 컴파일러 프로젝트

Anthropic은 16개의 Agent를 사용하여 Linux 커널을 컴파일할 수 있는 C 컴파일러를 처음부터 구축했습니다.

최종 결과물: x86, ARM, RISC-V에서 부팅 가능한 Linux 6.9를 빌드할 수 있는 Rust 컴파일러입니다.

팀 관리

Teammates 및 모델 지정

Claude가 작업에 따라 자동으로 생성할 Teammates 수를 결정하지만, 명시적으로 지정할 수도 있습니다.

4명의 teammates를 생성하여 이 모듈들을 병렬로 리팩토링해줘.
각 teammate는 Sonnet 모델을 사용해줘.

계획 승인 요청

복잡하거나 위험도가 높은 작업의 경우, Teammates에게 실행 전에 먼저 계획을 수립하도록 요청할 수 있습니다.

아키텍트 teammate를 생성하여 인증 모듈을 리팩토링해줘.
변경을 수행하기 전에 계획 승인을 요청해줘.

Teammate가 계획을 완료하면 Lead에게 승인 요청을 보냅니다. Lead가 검토 후 승인하거나 수정 의견을 반려할 수 있습니다.

Teammates에게 직접 대화하기

각 Teammate는 완전한 Claude Code 세션입니다. 어떤 Teammate에게든 직접 메시지를 보낼 수 있습니다.

• In-process 모드: Shift+Down으로 전환한 후 메시지 입력
• Split-pane 모드: 해당 창을 직접 클릭

Teammates 종료

보안 감사 teammate를 종료해줘

Lead가 종료 요청을 보내며, Teammate는 승인하거나 거부(이유 설명 포함)할 수 있습니다.

팀 정리

완료 후, Lead에게 리소스 정리를 요청합니다.

팀을 정리해줘

중요: 항상 Lead를 통해 정리하십시오. Teammates에게 정리를 맡기면 리소스 상태가 불일치할 수 있습니다.

모범 사례

팀 규모 관리

규모 권장 사항:

경험 법칙: 각 Teammate에게 5-6개의 작업을 할당하는 것이 적절합니다. 15개의 독립적인 작업이 있다면, 3명의 Teammates가 좋은 출발점입니다.

작업 세분화

• 너무 작음: 조율 오버헤드가 이점을 초과
• 너무 큼: Teammates가 너무 오래 작업하여 체크포인트가 없고, 낭비 위험 증가
• 적절함: 독립적이고 완결되며, 산출물이 명확한 작업 단위 (함수 하나, 테스트 파일 하나, 리뷰 보고서 하나)

파일 충돌 방지

두 Teammates가 같은 파일을 편집하면 덮어쓰기가 발생합니다. 작업을 분배할 때 각 Teammate가 다른 파일 집합을 담당하도록 하십시오.

Teammate 1: src/auth/ 디렉토리 담당
Teammate 2: src/api/ 디렉토리 담당
Teammate 3: src/utils/ 디렉토리 담당

모니터링 및 안내

정기적으로 Teammates의 진행 상황을 확인하고, 부적절한 방향을 적시에 수정하십시오. 팀을 너무 오래 무감독으로 실행하면 낭비 위험이 증가합니다.

Lead가 Teammates를 기다리지 않고 직접 작업을 구현하기 시작하면:

teammates가 작업을 완료한 후에 진행해줘

충분한 컨텍스트 제공

Teammates는 프로젝트 컨텍스트(CLAUDE.md, MCP servers, skills)를 자동으로 로드하지만, Lead의 대화 히스토리는 상속하지 않습니다. 생성 시 충분한 작업 세부 정보를 제공하십시오.

보안 감사 teammate를 생성하되, 다음과 같은 프롬프트를 제공해줘:
"src/auth/ 디렉토리의 인증 모듈 보안 취약점을 감사해줘.
토큰 처리, 세션 관리, 입력 검증에 중점을 둬줘.
앱은 httpOnly 쿠키에 저장된 JWT 토큰을 사용합니다.
발견 사항 보고 시 심각도 등급을 첨부해줘."

자기 보고 검증 패턴

작업 설명에 명확한 검증 기준을 포함하여, Teammates가 완료 후 자체 점검하도록 합니다.

작업 완료 시 Lead에게 보고해줘:
1. 어떤 파일을 검사했는지
2. 어떤 문제를 발견했는지
3. 어떤 수정을 했는지
4. 검증 기준(테스트 통과, lint 경고 없음 등)이 충족되었는지

이 패턴은 Lead의 검증 작업량을 줄이면서, 작업이 "완료된 것처럼 보이는" 것이 아닌 진정으로 완료되었는지 확인합니다.

고급 기법

Hooks를 사용한 강제 품질 게이트

Hooks를 통해 Teammates가 작업을 완료할 때 규칙을 강제 적용합니다.

{
  "hooks": {
    "TeammateIdle": [
      {
        "command": "your-validation-script.sh"
      }
    ],
    "TaskCompleted": [
      {
        "command": "your-quality-check.sh"
      }
    ]
  }
}

• TeammateIdle: Teammate가 유휴 상태에 진입하기 직전에 실행됩니다. exit code 2를 반환하면 피드백을 보내고 Teammate가 작업을 계속하게 할 수 있습니다
• TaskCompleted: 작업이 완료로 표시될 때 실행됩니다. exit code 2를 반환하면 완료를 차단하고 피드백을 보낼 수 있습니다

사전 승인 권한

Teammate의 권한 요청이 Lead에게 전달되어 빈번한 중단을 야기할 수 있습니다. 생성 전에 일반적인 작업을 사전 승인하십시오.

{
  "permissions": {
    "allow": [
      "Read(*)",
      "Write(src/**)",
      "Bash(npm test)"
    ]
  }
}

Worktree와 결합

Agent Teams는 Worktree와 함께 사용할 수 있으며, 각 Teammate가 자신의 worktree에서 작업합니다.

agent team을 생성하되, 각 teammate가 독립된 worktree에서 작업하여
파일 충돌을 피하게 해줘.

서드파티 오케스트레이션 도구

네이티브 Agent Teams 외에도, 커뮤니티에서 개발한 오케스트레이션 도구들이 있습니다.

이러한 도구들은 Agent Teams 실험적 기능 외에 대안을 제공하지만, 더 많은 수동 설정이 필요합니다. 네이티브 Agent Teams가 요구 사항을 충족한다면, 공식 기능을 우선 사용하는 것을 권장합니다.

현재 제한사항

Agent Teams는 아직 실험적 기능이므로, 제한사항을 이해하는 것이 중요합니다.

비용 고려사항

Agent Teams의 Token 소모는 단일 세션보다 현저히 높습니다.

비용 분석:

• 각 Teammate는 완전히 독립된 Claude 인스턴스로, 자체 컨텍스트를 가짐
• Teammates 간의 통신도 Token을 소모
• Lead가 모든 Teammates를 조율해야 하므로 추가 오버헤드 발생

언제 가치가 있는가:

• 병렬 탐색이 필요한 연구 작업
• 다각도 리뷰 (보안, 성능, 테스트)
• 토론을 통해 합의에 도달해야 하는 결정
• 순차적으로 완료할 수 있는 일반 작업에는 부적합
• 상호 통신이 필요 없는 병렬 작업에는 부적합 (Subagent가 더 경제적)

사용 경험

언제 Agent Teams를 사용하는가

판단 기준은 다음과 같습니다.

1. 작업에 다양한 관점이 필요: 서로 다른 영역의 전문 지식 (보안 + 성능 + 테스트)
2. 토론과 합의가 필요: 경쟁적 가설, 아키텍처 결정
3. 병렬 탐색에 가치가 있음: 여러 구현 방안 비교

단순히 병렬 실행만 필요하고 상호 통신이 불필요하다면, Subagent나 Worktree가 더 적합합니다.

연구와 리뷰부터 시작하기

Agent Teams를 처음 사용한다면, 코드 작성이 필요 없는 작업부터 시작하십시오. PR 리뷰, 기술 방안 연구, 버그 조사 등입니다. 이런 작업은 명확한 경계를 가지며, 병렬 탐색의 가치를 보여주면서 병렬 구현에 따른 조율 과제를 피할 수 있습니다.

다른 기능과의 조합

마치며

Agent Teams는 AI 보조 개발의 새로운 패러다임을 대표합니다. "하나의 AI 어시스턴트"에서 "하나의 AI 팀"으로의 전환입니다.

Anthropic은 16개의 Agent를 사용하여 2주간 $20,000을 들여 10만 줄의 코드로 된 C 컴파일러를 만들었습니다. 이 프로젝트의 핵심 교훈은: 테스트 품질이 무엇보다 중요하다는 것입니다. Agent는 주어진 문제를 자율적으로 해결하므로, 작업 검증기가 거의 완벽해야 합니다. 그렇지 않으면 Agent가 잘못된 문제를 해결하게 됩니다.

세 가지 핵심 요점을 기억하십시오.

시작은 간단합니다.

agent team을 생성하여 [당신의 작업]을 해줘

관련 읽을거리:

• Claude Worktree 완전 가이드 — Worktree와 Agent Teams의 조합 이해하기
• Claude Subagent 완전 가이드 — Subagent와 Agent Teams의 사용 시나리오 비교
• Tmux 빠른 시작 가이드 — Tmux를 사용한 다중 Agent 세션 관리

참고 자료:

• Claude Code 공식 문서 - Agent Teams
• Building a C compiler with a team of parallel Claudes
• Claude Code Agent Teams: The Complete Guide
• Multi-Agent Orchestration: Running 10+ Claude Instances in Parallel

영상 튜토리얼:

• 7 Unexpected Use Cases for Claude Code Agent Teams — 7가지 비기술적 활용 사례 데모
• Claude Code Multi-Agent Workflows — 다중 에이전트 워크플로 상세 해설
• Agent Teams Orchestration Deep Dive — 팀 오케스트레이션 심층 분석
• Claude Code Agent Teams Setup Guide — 완전한 설정 튜토리얼