Claude Code Agent Teams 완벽 가이드: 에이전트 협업으로 생산성 극대화하기

2026년 2월, Claude Opus 4.6과 함께 출시된 Agent Teams는 여러 Claude Code 인스턴스가 하나의 팀으로 협업하는 실험적 기능입니다. 이 글에서는 Agent Teams의 핵심 개념부터 실전 활용까지 단계별로 살펴보겠습니다.

🤔 왜 Agent Teams가 필요한가?

단일 에이전트의 한계

Claude Code 하나로도 충분히 강력하지만, 현실의 복잡한 작업은 여러 관점이 동시에 필요합니다. 코드 리뷰를 예로 들면, 보안 전문가가 취약점을 검토하는 동안 성능 전문가는 병목 지점을 분석하고, 테스트 전문가는 커버리지를 확인해야 합니다. 단일 에이전트가 이 세 가지를 순차적으로 처리하면 시간도 오래 걸리고, 앞선 분석에 편향될 수 있습니다.

Agent Teams가 해결하는 문제

Agent Teams는 이 한계를 병렬 협업으로 극복합니다. 여러 Claude Code 인스턴스가 각각 독립된 전문가로 동작하면서, 서로 직접 메시지를 주고받고, 공유 작업 목록을 통해 자율적으로 조율합니다. 단순히 작업을 나눠서 시키는 것이 아니라, 팀원들이 발견한 사항을 실시간으로 공유하고, 서로의 이론에 도전하는 진짜 팀워크가 가능합니다.

🏗️ Agent Teams란?

핵심 아키텍처

Agent Teams는 네 가지 핵심 구성 요소로 이루어져 있습니다.

┌─────────────────────────────────────────────────┐
│                  팀 리더 (Team Lead)              │
│            작업 생성 · 팀원 스폰 · 조율               │
└──────┬──────────────┬──────────────┬────────────┘
       │              │              │
       ▼              ▼              ▼
  ┌─────────┐   ┌─────────┐   ┌─────────┐
  │  팀원 A  │◄─►│  팀원 B  │◄─►│  팀원 C  │   ◄── 직접 메시지 교환
  │ (보안)   │   │ (성능)   │   │ (테스트)  │
  └────┬────┘   └────┬────┘   └────┬────┘
       │             │             │
       ▼             ▼             ▼
  ┌─────────────────────────────────────────────┐
  │          공유 작업 목록 (Task List)            │
  │     pending → in_progress → completed       │
  └─────────────────────────────────────────────┘

Subagent와 무엇이 다른가?

기존 서브에이전트(Subagent)를 사용해 본 분이라면 “뭐가 다르지?”라고 생각하실 수 있습니다. 핵심 차이는 통신 구조에 있습니다.

선택 기준은 간단합니다. 워커들이 서로 통신할 필요가 있는가?

• No → Subagent로 충분합니다
• Yes → Agent Teams를 사용하세요

예를 들어 “이 파일에서 TODO를 찾아줘”는 Subagent가 적합하고, “보안/성능/테스트 관점에서 이 PR을 리뷰하고 서로의 발견 사항을 검증해줘”는 Agent Teams가 적합합니다.

🚀 시작하기

1단계: Agent Teams 활성화

Agent Teams는 현재 실험적 기능으로, 기본 비활성화 상태입니다. 활성화 방법은 세 가지입니다.

방법 1: settings.json (권장)

// ~/.claude/settings.json 또는 프로젝트의 .claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

방법 2: 셸 프로필에 추가

# ~/.bashrc 또는 ~/.zshrc에 추가
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

방법 3: 세션별 일회성 실행

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

💡 팁: 프로젝트 루트의 .claude/settings.json에 설정하면 해당 프로젝트에서만 Agent Teams를 활성화할 수 있어 편리합니다.

2단계: 표시 모드 선택

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

In-process 모드 (기본값)

모든 팀원이 메인 터미널 안에서 실행됩니다. 별도 설정 없이 바로 사용할 수 있으며, 키보드 단축키로 팀원 간 전환이 가능합니다.

Split-pane 모드 (분할 창)

각 팀원이 자체 터미널 창을 가지며, 모든 팀원의 작업을 동시에 볼 수 있습니다. tmux 또는 iTerm2가 필요합니다.

// settings.json에 추가
{
  "teammateMode": "tmux"
}

또는 CLI에서 직접 지정할 수도 있습니다.

claude --teammate-mode in-process   # 강제로 in-process 모드

⚠️ 주의: 분할 창 모드는 VS Code 통합 터미널, Windows Terminal, Ghostty에서는 지원되지 않습니다.

3단계: 첫 팀 만들기

특별한 API 호출이 필요 없습니다. 자연어로 Claude에게 팀 생성을 요청하면 됩니다.

이 프로젝트의 코드를 리뷰할 에이전트 팀을 만들어줘.
보안 전문가, 성능 전문가, 테스트 전문가 3명을 스폰해줘.

Claude가 자동으로 팀을 생성하고, 각 전문가를 스폰하고, 작업을 분배합니다.

🔧 핵심 API와 사용법

Agent Teams는 7가지 핵심 도구(프리미티브)로 작동합니다. 내부적으로 Claude가 사용하는 도구들이지만, 작동 원리를 이해하면 더 효과적으로 팀을 조율할 수 있습니다.

1. TeamCreate — 팀 생성

팀 네임스페이스를 초기화하고 디스크에 조율 인프라를 만듭니다.

{
  "team_name": "blog-qa",
  "description": "블로그 QA를 수행하는 팀"
}

실행 결과로 다음 파일이 생성됩니다.

~/.claude/teams/blog-qa/config.json   ← 팀 설정 (멤버 목록 등)
~/.claude/tasks/blog-qa/              ← 공유 작업 목록 디렉토리

2. TaskCreate — 작업 생성

팀원들에게 할당할 작업 단위를 정의합니다.

{
  "subject": "QA: 코어 페이지 응답 확인",
  "description": "localhost:4321의 주요 페이지들이 HTTP 200을 반환하고 유효한 HTML인지 확인",
  "activeForm": "코어 페이지 응답 테스트 중"
}

💡 팁: description에 구체적인 지시사항을 포함하세요. 팀원은 CLAUDE.md를 자동 로드하지만 리더의 대화 기록은 상속하지 않으므로, 작업 설명이 가장 중요한 컨텍스트입니다.

3. TaskUpdate — 작업 상태 업데이트

팀원이 작업을 청구하고, 진행 상태를 변경합니다.

// 작업 청구 (시작)
{ "taskId": "1", "status": "in_progress", "owner": "qa-pages" }

// 작업 완료
{ "taskId": "1", "status": "completed" }

작업 상태는 세 단계로 진행됩니다: pending → in_progress → completed

작업 간 종속성도 설정할 수 있어, 선행 작업이 완료되어야 후속 작업이 시작됩니다.

4. TaskList — 작업 목록 조회

전체 작업의 상태와 소유자를 확인합니다.

// 반환 예시
[
  {
    "id": "1",
    "subject": "코어 페이지...",
    "status": "completed",
    "owner": "qa-pages"
  },
  {
    "id": "2",
    "subject": "링크 검증...",
    "status": "in_progress",
    "owner": "qa-links"
  },
  { "id": "3", "subject": "SEO 검사...", "status": "pending", "owner": "" }
]

5. Task (team_name 매개변수) — 팀원 스폰

팀 멤버십을 가진 독립 Claude Code 세션으로 팀원을 생성합니다.

{
  "description": "QA: 코어 페이지 응답 확인",
  "prompt": "localhost:4321의 주요 페이지들이 HTTP 200을 반환하는지 curl로 확인하세요...",
  "subagent_type": "general-purpose",
  "name": "qa-pages",
  "team_name": "blog-qa",
  "model": "sonnet"
}

💡 팁: 연구/검토 작업에는 비용이 낮은 sonnet 모델을, 복잡한 구현에는 opus를 사용하세요.

6. SendMessage — 메시지 전송

Agent Teams를 Subagent와 구별하는 핵심 기능입니다. 팀원들이 서로 직접 소통합니다.

// 특정 팀원에게 1:1 메시지
{
  "type": "message",
  "recipient": "team-lead",
  "content": "Task #1 완료. 16개 페이지 모두 정상입니다.",
  "summary": "코어 페이지 전체 통과"
}

// 전체 팀원에게 브로드캐스트 (비용이 크므로 꼭 필요할 때만!)
{
  "type": "broadcast",
  "content": "치명적 버그 발견. 모든 작업 중단 요청.",
  "summary": "치명적 버그 발견"
}

메시지 유형은 다섯 가지입니다.

• message: 특정 팀원에게 1:1 메시지
• broadcast: 전체 팀원에게 동시 전송
• shutdown_request: 팀원에게 종료 요청
• shutdown_response: 종료 요청에 대한 승인/거부
• plan_approval_response: 계획 승인/거부

7. TeamDelete — 팀 삭제

모든 팀원 종료 후 팀 파일과 작업 목록을 정리합니다.

⚠️ 주의: 반드시 리더를 통해 정리하세요. 팀원이 직접 TeamDelete를 실행하면 리소스가 비정상 상태로 남을 수 있습니다.

📖 실전 예제: 블로그 QA 스웜

Agent Teams의 실제 위력을 보여주는 예제입니다. 블로그 사이트를 5명의 에이전트가 동시에 QA 테스트하는 시나리오를 살펴보겠습니다.

프롬프트 하나로 시작

내 블로그(localhost:4321)를 QA해줘.
5명의 팀원을 만들어서 병렬로 테스트해줘.

리더가 자동으로 수행하는 작업

1. 사이트 접근성 확인 (localhost:4321이 응답하는지)
2. blog-qa 팀 생성
3. 5명의 Sonnet 에이전트 병렬 스폰

작업 분배

결과

• 소요 시간: 프롬프트 입력에서 우선순위별 보고서까지 약 3분
• 토큰 사용량: 리더 + 5명의 팀원 합계 약 800k 토큰
• 발견 사항: 각 팀원이 독립적으로 검사하여 다양한 관점의 이슈를 동시에 포착

단일 에이전트가 같은 작업을 순차적으로 수행했다면 훨씬 오래 걸렸을 것이고, 한 분야에 치우친 검사가 되었을 가능성이 높습니다.

✅ 모범 사례

1. 팀원에게 충분한 컨텍스트 제공

팀원은 CLAUDE.md와 MCP 서버를 자동으로 로드하지만, 리더의 대화 기록은 상속하지 않습니다. 스폰할 때 작업별 세부 사항을 구체적으로 전달해야 합니다.

# ❌ 부족한 컨텍스트
인증 모듈을 리뷰해줘.

# ✅ 충분한 컨텍스트
src/auth/ 디렉토리의 인증 모듈을 보안 관점에서 리뷰해줘.
JWT 토큰을 httpOnly 쿠키에 저장하는 방식을 사용 중이야.
토큰 처리, 세션 관리, 입력 검증에 집중하고,
발견된 이슈는 심각도 등급과 함께 보고해줘.

2. 적절한 작업 크기 유지

💡 팁: 팀원당 5~6개 작업을 유지하면 모두가 생산적으로 일하고, 리더가 필요 시 작업을 재할당할 수 있습니다.

3. 파일 충돌 방지

두 팀원이 같은 파일을 동시에 편집하면 덮어쓰기가 발생합니다. 각 팀원이 서로 다른 파일 집합을 담당하도록 작업을 분배하세요.

# ❌ 충돌 위험
팀원 A: src/utils/auth.ts 수정
팀원 B: src/utils/auth.ts 수정

# ✅ 충돌 회피
팀원 A: src/utils/jwt.ts 담당
팀원 B: src/utils/sessions.ts 담당
팀원 C: src/middleware/auth.ts 담당

4. Plan-Then-Parallelize 패턴

토큰 낭비를 최소화하는 2단계 워크플로우입니다. “계획 80%, 실행 20%” 원칙의 핵심입니다.

1단계: 계획 (저비용)

Plan 모드로 코드베이스를 탐색하고 작업을 분해합니다. 이 단계에서는 약 10k 토큰만 소모됩니다.

Plan 모드로 인증 리팩토링을 계획해줘.
파일 구조, 종속성, 작업 분배 방안을 정리해줘.

2단계: 검토 후 실행 (고비용)

승인된 계획을 팀에게 전달하여 병렬로 구현합니다.

# Wave 1 (병렬 실행)
- 팀원 A: jwt.ts 추출
- 팀원 B: sessions.ts 추출
- 팀원 C: middleware.ts 추출

# Wave 2 (Wave 1 완료 후)
- Barrel exports 및 import 업데이트

# Wave 3 (Wave 2 완료 후)
- 테스트 업데이트

5. 연구/검토부터 시작

Agent Teams를 처음 사용한다면 코드 작성이 필요 없는 작업으로 시작하세요.

• PR 리뷰
• 라이브러리 연구
• 버그 원인 조사

병렬 구현의 파일 충돌 문제 없이 병렬 탐색의 가치를 체험할 수 있습니다.

⚠️ 주의사항 및 제한사항

알려진 제한

1. In-process 팀원 세션 재개 불가: /resume이나 /rewind가 in-process 팀원을 복원하지 않습니다
2. 세션당 하나의 팀만 가능: 새 팀을 시작하려면 현재 팀을 먼저 정리해야 합니다
3. 중첩 팀 불가: 팀원은 자신만의 팀이나 팀원을 생성할 수 없습니다
4. 리더 고정: 팀을 만든 세션이 리더이며, 리더십을 이전할 수 없습니다
5. 느린 종료: 팀원은 현재 처리 중인 요청이 완료된 후에야 종료됩니다

토큰 비용 인식

Agent Teams는 각 팀원이 독립된 Claude 인스턴스이므로 토큰 사용량이 많습니다. 비용 대비 효과가 좋은 경우와 나쁜 경우를 구분하세요.

효과적인 경우:

• 교차 계층 기능 개발 (프론트엔드 + 백엔드 + 테스트)
• 다양한 관점이 필요한 QA
• 경쟁 가설로 디버깅
• 종속성이 있는 병렬 작업

비효율적인 경우:

• 작은 버그 수정 → 솔로 세션 사용
• 단순 파일 탐색/검색 → Subagent 사용
• 순차적 작업이나 동일 파일 편집

문제 해결 가이드

🔍 실제 활용 사례

사례 1: 병렬 코드 리뷰

단일 리뷰어는 한 번에 한 가지 유형의 문제에 치우치는 경향이 있습니다. 검토 기준을 독립적인 도메인으로 분할하면 보안, 성능, 테스트 커버리지가 동시에 철저한 검토를 받습니다.

PR #142를 리뷰할 에이전트 팀을 만들어줘.
3명의 리뷰어를 스폰해줘:
- 보안 관점 검토 전문가
- 성능 영향 분석 전문가
- 테스트 커버리지 검증 전문가
각각 리뷰하고 발견 사항을 보고하게 해줘.

사례 2: 경쟁 가설 디버깅

근본 원인이 불명확한 버그를 조사할 때, 팀원들을 의도적으로 적대적으로 만들어 과학적 토론 구조를 활용할 수 있습니다.

사용자들이 앱이 한 번의 메시지 후 종료된다고 보고하고 있어.
5명의 에이전트를 스폰해서 각각 다른 가설을 조사하게 해줘.
팀원들이 서로의 이론을 반박하는 과학적 토론 형식으로 진행하고,
합의된 결론을 문서에 정리해줘.

이 방식은 앵커링 편향을 방지합니다. 순차적 조사에서는 첫 번째 이론에 편향되기 쉽지만, 여러 독립적인 조사자가 서로의 이론을 반박하면 살아남는 이론이 실제 근본 원인일 가능성이 훨씬 높습니다.

사례 3: 이 블로그의 코드리뷰

실제로 이 블로그 프로젝트에서 Agent Teams를 활용하여 종합 코드리뷰를 수행한 경험이 있습니다. 3명의 전문가 팀을 구성했습니다.

• Frontend Architect: UI/UX, 컴포넌트 구조, Tailwind CSS 검토
• TypeScript & Performance: 타입 안전성, 성능 최적화, 빌드 파이프라인
• Security & DevOps: Docker 보안, CI/CD, 의존성 취약점

결과: 23개 파일에서 Critical 4개, High 5개, Medium 6개, Low 5개의 이슈를 발견하고 수정했습니다. 정렬 로직이 3곳에 중복되어 있던 문제, Docker 빌드의 보안 취약점, OG 이미지 생성 시 폰트 중복 다운로드 문제 등 단일 리뷰어가 놓치기 쉬운 교차 영역 이슈를 효과적으로 포착할 수 있었습니다.

🎯 Hooks로 품질 게이트 만들기

Agent Teams에 특화된 두 가지 훅 이벤트를 활용하면 팀원의 작업 품질을 자동으로 관리할 수 있습니다.

TeammateIdle 훅

팀원이 유휴 상태로 전환되기 전에 실행됩니다. exit code 2로 종료하면 팀원이 계속 작업합니다.

#!/bin/bash
# 빌드 아티팩트가 없으면 유휴 전환 차단
if [ ! -f "./dist/output.js" ]; then
  echo "빌드 결과물이 없습니다. 빌드를 완료한 후 중지하세요." >&2
  exit 2  # 팀원이 계속 작업하도록 차단
fi
exit 0

TaskCompleted 훅

작업이 완료로 표시될 때 실행됩니다. 테스트 통과 여부를 확인하는 품질 게이트로 활용할 수 있습니다.

#!/bin/bash
INPUT=$(cat)
TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')

# 테스트가 통과해야만 작업 완료를 허용
if ! npm test 2>&1; then
  echo "테스트 실패. 수정 후 완료하세요: $TASK_SUBJECT" >&2
  exit 2  # 완료를 차단
fi
exit 0

💡 실전 팁 모음

1. “계획 80%, 실행 20%”: 에이전트에게 위임하기 전에 충분히 계획하는 것이 가장 중요합니다. 잘못된 방향의 병렬 실행은 토큰만 낭비합니다.

2. 활동 ≠ 가치: 에이전트가 열심히 일하고 있다고 좋은 것이 아닙니다. 코드 양보다 정확성에 집중하세요.

3. CLAUDE.md를 적극 활용하세요: 팀원들은 CLAUDE.md를 자동으로 읽습니다. 프로젝트별 규칙, 코딩 컨벤션, 금지 사항을 여기에 정리하면 팀원들에게 자동으로 컨텍스트가 전달됩니다.

4. 핵심 역량은 분해력: Agent Teams를 잘 쓰려면 “문제를 에이전트 팀이 실행할 수 있는 구조로 분해하는 능력”이 핵심입니다. 좋은 분해는 파일 충돌을 피하고, 명확한 결과물을 정의하고, 적절한 종속성을 설정합니다.

5. 위임 모드를 활용하세요: Shift+Tab으로 위임 모드를 활성화하면 리더가 직접 코드를 작성하지 않고 조율에만 집중하게 됩니다. 리더가 팀원을 기다리지 않고 직접 구현을 시작하는 문제를 방지합니다.

6. 점진적으로 확장하세요: 코드 리뷰 → 교차 계층 검토 → 대규모 리팩토링 순서로 규모를 키워가세요. 처음부터 5명의 팀으로 복잡한 구현을 시도하면 조율 비용이 가치를 초과할 수 있습니다.

마치며

Agent Teams는 Claude Code의 활용 범위를 단일 에이전트에서 팀 단위 협업으로 확장합니다. 핵심은 세 가지입니다.

1. 적절한 사용처 선택: 모든 작업에 팀이 필요한 것은 아닙니다. 서로 소통이 필요한 복잡한 작업에서 진가를 발휘합니다.
2. 충분한 계획: “계획 80%, 실행 20%” 원칙을 지키세요. 계획 단계의 10k 토큰이 실행 단계의 800k 토큰의 방향을 결정합니다.
3. 점진적 확장: 검토/연구 작업으로 시작하여 경험을 쌓은 후 구현 작업으로 확장하세요.

아직 실험적 기능이지만, 멀티 에이전트 협업의 가능성을 직접 체험해 볼 수 있는 가장 실용적인 도구입니다. 작은 리뷰 작업부터 시작해 보시길 권합니다.

참고 자료

공식 문서

• Orchestrate teams of Claude Code sessions (영문) ↗
• Claude Code 세션 팀 조율하기 (한국어) ↗
• Create custom subagents (영문) ↗
• Hooks reference (영문) ↗

블로그 및 튜토리얼

• AddyOsmani.com - Claude Code Swarms ↗ — 아키텍처, 패턴, 실전 팁 종합
• From Tasks to Swarms: Agent Teams in Claude Code (alexop.dev) ↗ — 7가지 프리미티브 상세 분석, 블로그 QA 실사례
• Claude Code Agent Teams: Setup in 5 Minutes (Serenities AI) ↗ — 빠른 설정 가이드
• Claude Code Agent Teams Workflows (Geeky Gadgets) ↗ — 워크플로우 패턴