Claude Code 에이전트 팀 완전정리: AI 팀을 만들어 협업하는 법

Claude Code 에이전트 팀 완전정리: AI 팀을 만들어 협업하는 법

코드 리뷰는 보안 전문가에게, API 구현은 백엔드 전문가에게, 테스트는 QA 전문가에게 — 각자 독립된 세션에서 작업하면서도 서로 대화하고 조율하는 AI 팀을 만들 수 있다면? Claude Code의 에이전트 팀(Agent Teams) 기능이 바로 그걸 해냅니다. 이 글에서는 에이전트 팀의 구조부터 실전 운영까지 완전 정리합니다.

 

Claude Code 에이전트 팀 완전정리

---

1. 에이전트 팀이란?

여러 Claude가 팀을 이루어 협업

에이전트 팀은 여러 개의 독립된 Claude Code 인스턴스가 하나의 팀을 구성해서 협업하는 기능입니다. 한 세션이 팀 리드가 되어 작업을 배분하고, 각 팀원(Teammate)이 자신의 영역을 독립적으로 처리하며, 서로 직접 메시지를 주고받습니다.

[팀 리드] ─── 작업 배분 ───▶ [팀원 A: 보안 리뷰]
    │                         [팀원 B: 성능 분석]
    │                         [팀원 C: 테스트 검증]
    │                              ↕ 직접 소통
    │◀───── 결과 종합 ────────────┘

서브에이전트와의 핵심 차이

항목	서브에이전트	에이전트 팀
구조	메인 세션 내 하위 프로세스	완전히 독립된 여러 세션
소통	메인에만 결과 보고	팀원끼리 직접 대화
작업 관리	메인이 모든 것 조율	공유 작업 목록으로 자율 조율
컨텍스트	요약만 메인에 전달	각자 독립된 전체 컨텍스트
토큰 비용	낮음	높음 (각자 독립 인스턴스)
최적 용도	결과만 필요한 독립 작업	토론/협력이 필요한 작업

핵심: 서브에이전트는 "일꾼"이고, 에이전트 팀은 "동료"입니다. 팀원들은 서로 대화하고, 반박하고, 합의를 만들어갑니다.

에이전트 팀이란?

---

2. 에이전트 팀 활성화와 구조

실험 기능 활성화

에이전트 팀은 현재 실험 기능입니다. 환경 변수로 활성화합니다.

# 환경 변수로 활성화
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

# 또는 settings.json에서
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

팀 구조 (아키텍처)

[팀 리드] ── 팀 생성, 작업 분배, 결과 종합
    │
    ├── [팀원 A] ── 독립 세션, 자기 영역 작업
    │       ↕ 메시지
    ├── [팀원 B] ── 독립 세션, 자기 영역 작업
    │       ↕ 메시지
    └── [팀원 C] ── 독립 세션, 자기 영역 작업

    [공유 작업 목록] ── 모든 에이전트가 확인/업데이트

팀 구성 요소

구성 요소	역할
팀 리드	팀을 생성하고 작업을 배분하는 메인 세션
팀원	각자 독립 세션에서 할당된 작업 수행
작업 목록	모든 에이전트가 공유하는 할 일 리스트
메일박스	에이전트 간 직접 메시지 시스템

파일 저장 구조

~/.claude/
├── teams/
│   └── {팀이름}/
│       └── config.json          # 팀 설정 + 멤버 정보
└── tasks/
    └── {팀이름}/                 # 공유 작업 목록
        ├── task-001.json
        ├── task-002.json
        └── ...

에이전트 팀 활성화와 구조

---

3. 팀 만들기와 운영

자연어로 팀 생성

에이전트 팀은 자연어 요청으로 만듭니다. 복잡한 설정 파일 없이 대화로 팀을 구성할 수 있습니다.

CLI 도구를 개발하려고 해. 에이전트 팀을 만들어서
UX 전문가, 기술 아키텍트, 그리고 비판적 검토자
세 명이 각각 다른 관점에서 분석해줘.

Claude가 자동으로:

• 팀을 생성하고
• 3명의 팀원을 스폰하고
• 공유 작업 목록을 설정하고
• 작업을 조율합니다

팀 구성 지정

인증 모듈을 리팩토링할 4명의 팀을 만들어줘.
각 팀원은 Sonnet 모델을 사용해.

계획 승인 모드

아키텍트 팀원을 생성해서 인증 모듈을 리팩토링해줘.
변경하기 전에 계획 승인을 받도록 해.

팀원이 읽기 전용 Plan 모드로 작업 → 리드가 계획을 승인/거부 → 승인 후 실행

팀 종료

# 팀원 종료 요청
"리서처 팀원에게 종료하라고 해"

# 팀 정리 (반드시 리드에서 실행)
"팀을 정리해줘"

주의: 팀 정리는 반드시 리드 세션에서 실행하세요. 팀원이 정리하면 리소스가 꼬일 수 있습니다.

팀 만들기와 운영

---

4. 팀원 간 소통 방식

3가지 소통 채널

에이전트 팀의 핵심은 팀원 간 직접 소통입니다. 서브에이전트와 달리 팀원들이 서로 대화할 수 있습니다.

1) 다이렉트 메시지

message <팀원이름>: 인증 모듈에서 토큰 만료 로직 어떻게 되어 있어?

특정 팀원에게 직접 메시지를 보냅니다. 리드를 거치지 않고 팀원 간 직접 통신합니다.

2) 브로드캐스트

broadcast: 모든 팀원들, 인증 방식이 JWT에서 세션 쿠키로 바뀌었어.

모든 팀원에게 동시에 메시지를 보냅니다. 비용이 팀 크기에 비례하므로 중요한 공지에만 사용하세요.

3) 공유 작업 목록

모든 에이전트가 작업 상태를 실시간으로 확인할 수 있습니다.

작업 상태:
✅ 완료 - DB 스키마 설계 (팀원 A)
🔄 진행 중 - API 엔드포인트 구현 (팀원 B)
⏳ 대기 - 프론트엔드 연동 (의존: API 엔드포인트)
⏳ 대기 - 통합 테스트 (의존: 프론트엔드 연동)

소통 흐름

팀원 A ──── 메시지 ───▶ 팀원 B (다이렉트)
                ↓ (리드도 확인 가능)
리드    ── 브로드캐스트 ──▶ 모든 팀원
팀원 B ──── 메시지 ───▶ 팀원 C (다이렉트)

팀원 간 소통 방식

---

5. 화면 모드

인프로세스 모드 (기본)

모든 팀원이 하나의 터미널 안에서 실행됩니다. 어떤 터미널에서든 동작합니다.

단축키	기능
Shift+Down	팀원 순환 (다음 팀원 보기)
Enter	현재 팀원의 전체 세션 보기
Escape	팀원의 현재 작업 중단
Ctrl+T	작업 목록 토글
텍스트 입력	현재 활성 팀원에게 메시지

스플릿 패널 모드

각 팀원이 별도의 패널에서 실행됩니다. 모든 팀원의 출력을 동시에 볼 수 있습니다.

# tmux 사용
claude --teammate-mode tmux

# iTerm2 사용 (it2 CLI 필요)
claude --teammate-mode auto

조작	기능
패널 클릭	해당 팀원으로 포커스
텍스트 입력	포커스된 팀원에게 메시지
각 패널	완전한 Claude Code 세션

설정 방법

// settings.json
{
  "teammateMode": "in-process"    // 또는 "tmux", "auto"
}

스플릿 패널은 tmux 또는 iTerm2가 필요합니다. VS Code 통합 터미널이나 Windows Terminal에서는 인프로세스 모드를 사용하세요.

화면 모드

---

6. 작업 관리와 분배

작업 상태

상태	설명
대기 (Pending)	아직 시작하지 않은 작업
진행 중 (In Progress)	팀원이 가져가서 작업 중
완료 (Completed)	작업 완료

작업 분배 방식

리드가 직접 할당

보안 리뷰 작업을 보안 리뷰어 팀원에게 할당해줘

팀원이 자율적으로 가져가기

팀원이 현재 작업을 끝내면 다음 미할당 작업을 자동으로 가져갑니다. 의존성이 해결되지 않은 작업은 자동으로 차단됩니다.

작업 크기 가이드

크기	문제	적절한 예시
너무 작음	조율 비용 > 작업 가치	❌ 변수 하나 이름 바꾸기
너무 큼	오래 돌고 체크인 없음	❌ 전체 모듈 리팩토링
적절함	자급자족 + 명확한 결과물	✅ 함수 1개 + 테스트 작성

팀원당 5~6개의 작업이 가장 생산적입니다.

파일 충돌 방지

❌ 잘못된 분배:
- 팀원 A: src/utils.js 수정
- 팀원 B: src/utils.js 수정
→ 파일 덮어쓰기 발생!

✅ 올바른 분배:
- 팀원 A: src/auth/tokens.js
- 팀원 B: src/auth/sessions.js
- 팀원 C: src/auth/permissions.js
→ 충돌 없이 병렬 진행

작업 관리와 분배

---

7. 훅으로 품질 게이트 만들기

TeammateIdle 훅

팀원이 유휴 상태가 되려 할 때 실행됩니다. 작업 완료 조건을 강제할 수 있습니다.

{
  "hooks": {
    "TeammateIdle": [
      {
        "type": "command",
        "command": "~/.claude/hooks/check-build.sh"
      }
    ]
  }
}

#!/bin/bash
# check-build.sh
if [ ! -f "./dist/output.js" ]; then
  echo "빌드 산출물이 없습니다. 빌드를 먼저 실행하세요." >&2
  exit 2  # 유휴 방지, 팀원이 계속 작업
fi
exit 0  # 유휴 허용

TaskCompleted 훅

작업이 완료로 표시될 때 실행됩니다.

#!/bin/bash
# verify-tests.sh
if ! npm test 2>&1; then
  echo "테스트가 통과하지 않았습니다. 수정 후 완료해주세요." >&2
  exit 2  # 완료 방지, 팀원이 계속 작업
fi
exit 0  # 완료 허용

훅 종료 코드

종료 코드	동작
0	허용 (유휴/완료 승인)
2	거부 + stderr 메시지를 피드백으로 전달
JSON {"continue": false}	팀원 완전 중지

훅으로 품질 게이트 만들기

---

8. 비용 관리와 최적화

비용 구조

에이전트 팀은 각 팀원이 독립된 Claude 인스턴스이므로, 비용이 팀 크기에 비례합니다.

비용 ≈ 팀원 수 × 개별 세션 비용
Plan 모드 팀의 경우 약 7배의 토큰 사용

비용 최적화 전략

전략	방법	효과
모델 선택	팀원에 Sonnet 사용	비용 대비 성능 균형
팀 크기	3~5명이 적절	조율 오버헤드 최소화
작업 범위	작업을 집중적으로 설계	컨텍스트 낭비 방지
즉시 정리	작업 끝나면 팀 정리	유휴 비용 방지
스폰 프롬프트	200~500단어로 집중	초기 컨텍스트 절약

비용 확인

# 현재 세션의 토큰 사용량 확인
/cost

팀 크기별 가이드

팀 크기	적합한 작업	예상 소요 시간
3~5명	대부분의 워크플로우	10~30분
6~10명	대규모 프로젝트	20~60분
10명+	권장하지 않음	조율 오버헤드 과다

비용 관리와 최적화

---

9. 실전 활용 패턴

패턴 1: 병렬 코드 리뷰

PR #142를 리뷰할 에이전트 팀을 만들어줘:
- 보안 관점 리뷰어
- 성능 관점 리뷰어
- 테스트 커버리지 리뷰어
각자 리뷰하고 결과를 보고해줘.

각 리뷰어가 같은 PR을 다른 관점에서 분석합니다. 리드가 세 관점을 종합해서 최종 리뷰를 작성합니다.

패턴 2: 경쟁 가설 조사

앱이 메시지 하나 보낸 후 종료되는 버그가 있어.
5명의 팀원을 만들어서 각각 다른 가설을 조사해줘.
서로 상대방의 이론을 반박하면서 토론하도록 해.
합의가 나오면 결과 문서를 업데이트해줘.

단일 에이전트는 첫 번째 그럴듯한 설명에 고착되기 쉽습니다. 여러 팀원이 서로 반박하면서 살아남는 이론이 진짜 원인일 가능성이 높습니다.

패턴 3: 풀스택 기능 개발

알림 시스템을 구현할 3인 팀을 만들어줘:
- 프론트엔드: UI 컴포넌트와 상태 관리
- 백엔드: API 엔드포인트와 DB 스키마
- 테스트: 유닛 테스트와 통합 테스트
공유 작업 목록으로 조율해줘.

패턴 4: 대규모 리팩토링

인증 시스템을 병렬로 리팩토링할 4인 팀:
- 세션 관리 전문가
- 토큰 처리 전문가
- 권한 체크 전문가
- 통합 테스트 전문가

좋은 스폰 프롬프트 작성법

❌ 나쁜 예: "인증 모듈 리팩토링해줘"

✅ 좋은 예: "src/auth/의 인증 모듈을 리팩토링해줘.
JWT 토큰을 localStorage에서 httpOnly 쿠키로 변경.
2주간 하위 호환성 유지. 테스트는 src/auth/__tests__에 있어.
OAuth 소셜 로그인 플로우는 건드리지 마.
함수 하나 리팩토링할 때마다 진행 상황 보고해줘."

실전 활용 패턴

---

10. 주의사항과 FAQ

현재 제한사항 (실험 기능)

제한	설명
세션 재개 불가	/resume, /rewind로 인프로세스 팀원 복원 불가
작업 상태 지연	팀원이 완료 표시를 빠뜨려서 의존 작업 차단 가능
종료 지연	팀원이 현재 요청을 마쳐야 종료 가능
세션당 1팀	새 팀 만들기 전에 기존 팀 정리 필수
중첩 불가	팀원이 자기 팀/팀원을 만들 수 없음
리드 고정	팀을 만든 세션이 영구적으로 리드
스플릿 패널 제한	tmux 또는 iTerm2 필요 (VS Code 터미널 미지원)

FAQ

Q: 에이전트 팀은 언제 써야 하나요?
A: 팀원 간 토론이나 협력이 필요한 작업에 사용합니다. 단순한 병렬 작업이라면 서브에이전트가 더 효율적입니다.

Q: 팀원이 다른 팀원의 대화 내용을 볼 수 있나요?
A: 아닙니다. 각 팀원은 완전히 독립된 컨텍스트를 가집니다. 직접 메시지를 통해서만 정보를 공유할 수 있습니다.

Q: 팀원이 안 보일 때는?
A: 인프로세스 모드에서는 Shift+Down으로 팀원을 순환하세요. 백그라운드에서 실행 중일 수 있습니다.

Q: CLAUDE.md는 팀원에게도 적용되나요?
A: 네, CLAUDE.md, MCP 서버, 스킬은 모든 팀원에게 자동으로 상속됩니다.

Q: 팀원끼리 같은 파일을 수정하면?
A: 파일 덮어쓰기가 발생할 수 있습니다. 작업을 파일 단위로 분배하거나 워크트리를 사용하세요.

Q: 리드가 먼저 종료되면?
A: 팀원들이 메시지를 보낼 수 없게 됩니다. 반드시 팀원을 먼저 종료한 뒤 리드를 종료하세요.

---

 

면책 조항: 이 글은 정보 제공 목적으로 작성되었습니다. Claude Code의 기능과 요금은 Anthropic의 정책에 따라 변경될 수 있으며, 최신 정보는 공식 문서를 확인해 주세요.