Claude Code Agent Teams 완전 정복

Claude Code Agent Teams 완전 정복

한 줄 요약: Claude Code의 Agent Teams 기능을 활용하면, 혼자서도 여러 AI 에이전트를 동시에 지휘하여 복잡한 프로젝트를 병렬로 처리할 수 있습니다. 이 글에서는 설치부터 실전 활용까지 단계별로 안내합니다.

1. Claude Code란?

Claude Code는 Anthropic이 만든 터미널 기반 AI 코딩 에이전트입니다. 채팅 UI가 아닌 터미널에서 직접 동작하며, 여러분의 코드베이스를 이해하고 파일을 편집하고, 터미널 명령어를 실행하고, Git 워크플로우까지 처리해 줍니다.

왜 Claude Code인가?

일반적인 AI 코딩 도구와의 차이를 정리하면 이렇습니다.

구분웹 기반 AI (ChatGPT, Claude.ai 등)IDE 확장 (Copilot, Cursor 등)Claude Code

동작 환경	브라우저	에디터 내부	터미널
파일 직접 수정	❌	⚠️ 제한적	✅ 직접 수정
터미널 명령 실행	❌	⚠️ 제한적	✅ 직접 실행
프로젝트 전체 이해	❌ (붙여넣기 필요)	부분적	✅ 자동 분석
멀티 에이전트	❌	❌	✅ Agent Teams

핵심은 “에이전트” 라는 점입니다. 단순히 코드를 추천하는 게 아니라, 목표를 이해하고 → 계획을 세우고 → 직접 실행하고 → 결과를 검증하는 전체 사이클을 자율적으로 수행합니다.

Claude Code 실행화면

2. Agent Teams란?

기본 개념

Agent Teams는 여러 개의 Claude Code 인스턴스가 하나의 팀으로 협업하는 멀티 에이전트 아키텍처입니다. 2026년 2월에 리서치 프리뷰로 공개되었습니다.

구조는 간단합니다:

• Team Lead(리드): 메인 Claude Code 세션. 팀을 만들고, 작업을 배분하고, 결과를 종합합니다.
• Teammates(팀원): 각각 독립된 Claude Code 인스턴스. 자기만의 컨텍스트 윈도우에서 작업합니다.
• Task List(태스크 리스트): 공유 작업 목록. 의존성을 자동 추적하고, 선행 작업이 끝나면 자동으로 다음 작업이 풀립니다.
• Mailbox(메일박스): 팀원끼리 직접 메시지를 주고받는 소통 시스템입니다.

왜 멀티 에이전트인가?

LLM에는 잘 알려진 약점이 있습니다. 컨텍스트가 길어질수록 집중력이 떨어진다는 것입니다. 하나의 에이전트에게 프론트엔드, 백엔드, 테스트, 배포까지 시키면 후반부로 갈수록 초반의 맥락을 잊어버립니다.

Agent Teams는 이 문제를 구조적으로 해결합니다. 각 팀원에게 좁은 범위와 깨끗한 컨텍스트를 부여하여 도메인별 추론 품질을 극대화합니다. 인간 팀이 분업하는 것과 같은 원리입니다.

5가지 핵심 장점

< 장점설명 >

1	병렬 처리	수일 걸릴 작업을 팀원들이 동시에 수행하여 수시간으로 압축
2	독립 컨텍스트	각 팀원이 자기 도메인에만 집중 → 품질 극대화
3	적대적 토론	복수 에이전트가 서로 가설을 반박하며 정확한 결론에 수렴
4	직접 소통	리드를 거치지 않고 팀원끼리 직접 메시지 교환 가능
5	자연어 구성	YAML/설정 파일 없이 자연어로 팀 구조를 설명하면 끝

 

3. 단일 세션, Subagent와의 차별점

Claude Code에는 세 가지 작업 방식이 있습니다. 각각 언제 쓰는지 명확히 구분하는 것이 중요합니다.

상세 비교표

비교 항목단일 세션SubagentAgent Teams

에이전트 수	1개	1개 + 보조 N개	1개(리드) + 팀원 N개
컨텍스트	하나의 윈도우	각자 윈도우, 결과만 반환	각자 윈도우, 완전히 독립
소통 방식	없음	메인에게만 보고 (단방향)	팀원 간 직접 교환 (양방향)
조율 방식	수동	메인이 모든 것 관리	공유 태스크 리스트로 자기 조율
팀원 간 토론	❌	❌	✅ 가능
사용자 직접 소통	✅	❌ 메인 경유만	✅ 개별 팀원과 직접 대화
태스크 의존성	수동	수동	자동 추적 + 자동 언블록
토큰 비용	1×	~1.5×	~5× (팀원당)
세션 재개	✅	✅	❌ /resume 미지원
적합한 작업	단순 작업	집중된 단일 작업	복잡한 병렬 탐색 + 협업

한눈에 보는 선택 가이드

작업이 들어왔을 때 → 이 질문을 던져보세요:

Q1. 파일 1~2개 수정하는 단순 작업인가?
    → Yes: 단일 세션

Q2. "이거 조사해서 결과만 알려줘"인가?
    → Yes: Subagent

Q3. 여러 관점에서 동시에 탐색/토론이 필요한가?
    → Yes: Agent Teams

Q4. 프론트/백엔드/테스트를 동시에 병렬 개발해야 하는가?
    → Yes: Agent Teams

핵심 원칙: Agent Teams는 토큰 비용이 ~5배입니다. 병렬 탐색이 진정한 가치를 제공하는 복잡한 작업에만 사용하세요. 단순 작업에 팀을 만드는 것은 낭비입니다.

4. 실제 동작을 위한 준비물

4-1. 사전 요구사항

시작하기 전에 필요한 것들입니다:

항목요구사항

OS	macOS, Linux, WSL (Windows)
Claude 구독	Claude Pro 또는 Max 플랜 (또는 Anthropic API 콘솔)
터미널	기본 터미널, iTerm2, Warp 등 (VS Code 내장 터미널은 split-pane 미지원)
tmux	선택사항 — split-pane 모드 사용 시 필요

4-2. Claude Code 설치

2026년 2월 기준, Anthropic은 네이티브 설치를 권장합니다. npm 설치 방식은 레거시로 분류됩니다.

방법 A: 네이티브 설치 (권장)

# macOS / Linux
curl -fsSL https://claude.ai/install.sh | bash

# Windows (PowerShell)
irm https://claude.ai/install.ps1 | iex

설치 후 확인:

claude --version

방법 B: npm 설치 (레거시)

Node.js 18 이상이 필요합니다.

npm install -g @anthropic-ai/claude-code

⚠️ sudo npm install -g는 절대 사용하지 마세요. 권한 문제가 발생합니다.

설치 검증

claude doctor

claude doctor를 실행하면 설치 상태, 인증, 환경 설정을 자동으로 진단해 줍니다.

인증 설정

처음 실행 시 OAuth 인증 화면이 나타납니다:

# 프로젝트 디렉토리로 이동 후
cd ~/my-project
claude

Claude Pro/Max 계정으로 로그인하면 됩니다. API 키를 사용하는 경우:

export ANTHROPIC_API_KEY="sk-ant-xxxxx"

4-3. Agent Teams 활성화

Agent Teams는 실험적 기능이므로 기본값이 비활성화입니다. 아래 세 가지 방법 중 하나를 선택하세요.

방법 A: settings.json (권장 — 영구 설정)

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

방법 B: 쉘 환경변수 (영구)

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

방법 C: 일회성 실행

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

활성화 확인은 간단합니다. Claude Code를 실행한 뒤 “에이전트 팀을 만들어줘”라고 요청했을 때 팀이 생성되면 성공입니다.

4-4. tmux 설치 (선택사항 — split-pane 모드)

tmux는 터미널 멀티플렉서로, 하나의 터미널 창을 여러 패널로 분할할 수 있게 해줍니다. Agent Teams의 split-pane 모드를 사용하면 각 팀원의 작업 화면을 동시에 볼 수 있어 모니터링이 훨씬 편합니다.

💡 tmux 없이도 Agent Teams는 사용 가능합니다. 기본 in-process 모드는 어떤 터미널에서든 동작합니다. tmux는 “더 편하게 보기 위한” 선택사항입니다.

tmux 설치

# macOS
brew install tmux

# Ubuntu / Debian
sudo apt-get install tmux

# CentOS / RHEL
sudo yum install tmux

tmux 모드 설정

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "teammateMode": "tmux"
}

teammateMode 값동작

"auto" (기본값)	tmux 세션 안이면 split-pane, 아니면 in-process
"tmux"	split-pane 강제 활성화 (tmux 또는 iTerm2 자동 감지)
"in-process"	모든 팀원이 메인 터미널 안에서 동작

tmux로 Agent Teams 시작하기

# 1. tmux 세션 시작
tmux

# 2. Claude Code 실행
cd ~/my-project
claude

# 3. 팀 생성 요청 (자연어로)
# "에이전트 팀을 만들어서 이 프로젝트를 분석해줘"

split-pane 모드 주의사항

split-pane 모드는 아래 환경에서는 동작하지 않습니다:

• ❌ VS Code 내장 터미널
• ❌ Windows Terminal
• ❌ Ghostty

위 환경에서는 --teammate-mode in-process를 사용하세요.

4-5. 디스플레이 모드 비교

모드장점단점추천 상황

in-process (기본)	어떤 터미널에서든 동작	팀원 전환이 수동 (Shift+↑↓)	처음 시작할 때, VS Code 사용 시
split-pane (tmux)	모든 팀원 동시 확인 가능	tmux/iTerm2 필요	팀원 3명 이상, 모니터링 중요할 때

5. 실전 활용 예시 — 프롬프트로 동작시키기

이제 실제로 Agent Teams를 사용해 봅시다. 아래는 바로 복사해서 사용할 수 있는 프롬프트 예시들입니다.

[ 예시 1 ] : 웹앱 병렬 개발

가장 대표적인 활용 사례입니다. 프론트엔드, 백엔드, 테스트를 각각 다른 팀원이 동시에 작업합니다.

할 일 관리 웹앱을 만들어줘. 에이전트 팀을 구성해서 병렬로 개발해줘.

- 팀원 1: React 프론트엔드 (컴포넌트, 상태 관리, UI)
- 팀원 2: Express 백엔드 (REST API, DB 연결, 인증)
- 팀원 3: 테스트 코드 (E2E 테스트, API 통합 테스트)

각 팀원은 서로 다른 폴더에서 작업하고,
API 인터페이스가 확정되면 팀원들끼리 공유해줘.

포인트: “서로 다른 폴더에서 작업”이라고 명시하는 것이 중요합니다. 같은 파일을 여러 팀원이 수정하면 덮어쓰기가 발생합니다.

[ 예시 2 ] : 경쟁 가설 디버깅

Agent Teams의 가장 강력한 활용처입니다. 단일 에이전트는 첫 번째로 그럴듯한 원인을 찾으면 거기에 고착되지만, 복수 에이전트는 서로 반박하며 정확한 원인을 찾아냅니다.

프로덕션 API가 간헐적으로 500 에러를 반환하고 있어.
에이전트 팀을 만들어서 경쟁 가설로 디버깅해줘.

- 팀원 1: DB 커넥션 풀 고갈 가설 조사
- 팀원 2: 캐싱 레이어 레이스 컨디션 가설 조사
- 팀원 3: 요청 핸들러 메모리 누수 가설 조사

각 팀원은 로그 파일과 코드를 분석한 뒤, 
서로 증거를 공유하고 어떤 가설이 맞는지 토론해줘.
가장 유력한 원인이 확인되면 수정 방안까지 제시해줘.

[ 예시 3 ] : 다관점 코드 리뷰

PR #42에 대한 코드 리뷰를 에이전트 팀으로 진행해줘.

- 팀원 1 (보안 리뷰어): 인증, 입력 검증, XSS/SQL Injection 취약점 점검
- 팀원 2 (성능 리뷰어): 쿼리 최적화, N+1 문제, 메모리 사용량 분석
- 팀원 3 (테스트 리뷰어): 테스트 커버리지, 엣지 케이스, 통합 테스트 확인

각자 리뷰 결과를 공유하고, 최종 리뷰 리포트를 하나로 종합해줘.

[ 예시 4 ] : 설계 탐색 (코드 작성 전 리서치)

코드를 작성하기 전 여러 관점에서 설계를 탐색할 때 유용합니다.

개발자용 TODO 코멘트 추적 CLI 도구를 설계하려고 해.
에이전트 팀으로 다양한 관점에서 탐색해줘.

- 팀원 1 (UX 전문가): 사용자 경험, CLI 인터페이스 설계, 출력 포맷
- 팀원 2 (아키텍트): 기술 아키텍처, 파서 설계, 성능 최적화
- 팀원 3 (악마의 대변인): 각 제안의 약점 지적, 엣지 케이스, 경쟁 도구와 비교

탐색이 끝나면 최적 설계안을 하나로 종합해줘.

[ 예시 5 ] : 코드베이스 분석 리포트

이 프로젝트의 코드베이스를 분석하는 에이전트 팀을 만들어줘.

- 팀원 1: 백엔드 분석 (API 구조, DB 스키마, 비즈니스 로직)
- 팀원 2: 프론트엔드 분석 (컴포넌트 구조, 상태 관리, 라우팅)
- 팀원 3: 인프라 분석 (의존성, 빌드 설정, 배포 파이프라인)

분석 결과를 docs/analysis.md 파일 하나에 종합해줘.

팁: 여러 팀원의 결과를 하나의 파일에 모아야 할 때는 마지막에 명시적으로 지정하면 리드가 종합해 줍니다.

팀 운영 시 유용한 키보드 단축키

단축키기능모드

Shift + ↑/↓	팀원 선택/전환	in-process
Enter	선택한 팀원 세션 보기	in-process
Escape	팀원 작업 중단	in-process
Ctrl + T	태스크 리스트 토글	in-process
Shift + Tab	리드를 위임 모드로 전환 (코드 작성 금지)	공통

팀 정리 및 추가 작업

작업이 끝나면 리드가 자동으로 팀을 정리합니다. 만약 추가 작업이 필요하면:

• 단순 추가 작업: 같은 세션에서 단일 에이전트로 처리
• 복잡한 추가 작업: “새로운 팀을 만들어줘”라고 요청하여 새 팀 구성

⚠️ /resume과 /rewind로는 이전 팀을 복원할 수 없습니다. 해산된 팀은 새로 만들어야 합니다.

작업 완료 후, 자동으로 팀을 정리한 모습

마무리: Best Practice Checklist

Agent Teams를 효과적으로 사용하기 위한 실전 팁을 정리합니다.

이렇게 하세요 ✅

• 읽기 전용 작업(코드 리뷰, 리서치)부터 시작하세요. 조율 패턴을 익힌 뒤 병렬 구현으로 확장하세요.
• 팀원당 5~6개 태스크를 배분하세요. 너무 적으면 조율 오버헤드가 크고, 너무 많으면 체크인 없이 방치됩니다.
• 각 팀원이 서로 다른 파일을 소유하도록 분리하세요. 같은 파일을 두 팀원이 수정하면 덮어쓰기가 발생합니다.
• 스폰 프롬프트에 충분한 컨텍스트를 포함하세요. 팀원은 리드의 대화 기록을 상속받지 않습니다.
• 주기적으로 체크인하세요. 방치 시간이 길어질수록 낭비가 증가합니다.

이것은 피하세요 ❌

• 단순 버그 수정에 Agent Teams 사용 → 단일 세션으로 충분
• 같은 파일을 여러 팀원이 동시 수정 → 파일 소유권 분리 필수
• 순차적으로 처리해야 하는 작업 → 병렬화 이점 없음
• 팀을 만들고 방치 → 정기 모니터링 필수

비용 참고

Agent Teams는 팀원당 약 5배의 토큰을 소비합니다. Claude Max 구독을 사용하면 별도 API 비용 없이 사용할 수 있지만, 사용량 제한이 있으므로 복잡한 작업에만 선별적으로 활용하는 것을 추천합니다.

📌 Agent Teams 공식 문서: code.claude.com/docs/en/agent-teams

이 기능은 현재 리서치 프리뷰 상태이며, 세션 재개, 태스크 조율, 종료 동작 등에 알려진 제한사항이 있습니다. Anthropic이 지속적으로 개선하고 있으니, 공식 문서를 수시로 확인하세요.