Agent Teams로 병렬 협업하기

⏱️ 20분

⚠️ 실험적 기능

여러 독립적인 Claude Code 세션을 조율해서 병렬 협업하는 방법을 배웁니다.

⚠️ 중요: 실험적 기능
🎯 Agent Teams란?
💡 언제 사용하나?
1. Agent Teams가 적합한 경우
2. 단일 세션이 더 나은 경우
🚀 첫 번째 팀 만들기
1. 기본 사용법
2. 표시 모드
🎨 실용적인 예제
🔧 팀 제어하기
📚 모범 사례
🛠️ 고급 기능
1. Subagent 정의 재사용
2. 저장 위치
⚠️ 문제 해결
📊 토큰 비용
⚠️ 제한사항
✅ 완료
1. 다음 단계

⚠️ 중요: 실험적 기능

Agent Teams는 실험적 기능으로 기본적으로 비활성화되어 있습니다.

활성화 방법:

# 환경 변수 설정
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

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

알려진 제한사항:

In-process 팀원과 세션 재개 불가
작업 상태가 지연될 수 있음
세션당 한 팀만 가능
중첩 팀 불가
팀원을 리더로 승격 불가

🎯 Agent Teams란?

Agent Teams는 여러 독립적인 Claude Code 인스턴스가 함께 작동하도록 조율하는 시스템입니다.

핵심 개념

팀 리더가 조율:

팀을 생성하고 관리
작업 목록 생성
팀원 간 메시지 전달
결과 종합

팀원들이 협업:

독립적인 세션에서 작업
공유 작업 목록에서 작업 선택
서로 직접 메시지 전송
자체적으로 조율

Sub-agents vs Agent Teams

비교	Sub-agents	Agent Teams
세션	같은 세션 내	독립적인 세션들
컨텍스트	격리된 윈도우	완전히 분리
통신	부모에게만 보고	서로 직접 메시지
조율	부모가 관리	공유 작업 목록
용도	결과만 중요	협업과 논의 필요
토큰 비용	낮음 (요약만)	높음 (독립 인스턴스)

아키텍처

                 ┌─────────────────────────┐
                 │   팀 리더 (세션 1)      │
                 │                         │
                 │  • 팀 생성 및 조율      │
                 │  • 작업 목록 관리       │
                 │  • 결과 종합            │
                 └─────────────────────────┘
                           ↕ (메시지)
                 ┌──────────────────┐
                 │  공유 저장소     │
                 │  • 작업 목록     │
                 │  • 메시징 시스템 │
                 └──────────────────┘
                   ↕       ↕       ↕
       ┌───────────┴──┐    │    ┌──┴───────────┐
       ↓              ↓    ↓    ↓              ↓
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│ 팀원 1       │  │ 팀원 2       │  │ 팀원 3       │
│ (세션 2)     │  │ (세션 3)     │  │ (세션 4)     │
│              │  │              │  │              │
│ Frontend     │  │ Backend      │  │ Testing      │
│ 개발 담당    │  │ 개발 담당    │  │ 작업 담당    │
└──────────────┘  └──────────────┘  └──────────────┘
       ↕                 ↕                 ↕
       └────────────────►│◄────────────────┘
            팀원 간 직접 메시지
           (공유 저장소를 통해)

파일 시스템 저장소:
~/.claude/teams/{team-name}/config.json  ← 팀 구성
~/.claude/tasks/{team-name}/             ← 작업 목록 & 메시지

흐름 예시:

1. 사용자 → 팀 리더: "3개 팀으로 작업 분할해줘"
          ↓
2. 팀 리더: 팀원 1, 2, 3 생성 + 작업 목록 생성
          ↓
3. 팀원들: 공유 작업 목록에서 작업 선택
          ↓
4. 팀원 1 → 팀원 2: "API 스펙 이렇게 했어"
          ↓
5. 팀원 2: API 스펙 기반으로 구현
          ↓
6. 팀원들 → 팀 리더: 완료 보고
          ↓
7. 팀 리더: 결과 종합 및 사용자에게 보고

💡 언제 사용하나?

Agent Teams가 적합한 경우

병렬 탐색이 가치를 더하는 작업:

✅ 연구 및 검토: 여러 관점에서 동시 조사
✅ 새로운 모듈: 각자 별도 부분 소유
✅ 경쟁 가설 디버깅: 다양한 이론을 병렬 테스트
✅ 교차 계층 조율: 프론트엔드/백엔드/테스트 동시 작업

단일 세션이 더 나은 경우

순차적이거나 밀접하게 연관된 작업:

❌ 순차적 단계가 많은 작업
❌ 같은 파일을 편집해야 하는 경우
❌ 많은 종속성이 있는 작업
❌ 빠른 왕복이 필요한 경우

🚀 첫 번째 팀 만들기

기본 사용법

자연어로 원하는 작업과 팀 구조를 설명하세요:

CLI 도구 설계를 돕는 팀을 만들어줘:
- UX 관점 팀원
- 기술 아키텍처 팀원
- 반론 제기 팀원

각자 다른 각도에서 문제를 탐색하고 발견을 공유해줘.

Claude가 자동으로:

팀 생성
3명의 팀원 생성
작업 목록 생성
팀원들에게 역할 할당
협업 조율
결과 종합

표시 모드

In-process 모드 (기본):

모든 팀원이 메인 터미널 내에서 실행
Shift+Down으로 팀원 순환
추가 설정 불필요

분할 창 모드:

각 팀원이 자신의 창
tmux 또는 iTerm2 필요
모든 출력을 동시에 확인

설정:

{
  "teammateMode": "in-process"  // 또는 "tmux"
}

또는 CLI:

claude --teammate-mode in-process

🎨 실용적인 예제

예제 1: 병렬 코드 검토

여러 관점에서 동시에 검토합니다.

PR #142를 검토할 팀을 만들어줘:
- 보안 전문가: 보안 취약점
- 성능 전문가: 성능 영향
- 테스트 전문가: 테스트 커버리지

각자 검토하고 발견을 보고해줘.

효과:

각 검토자가 다른 필터 적용
동시에 세 가지 관점 확보
리더가 모든 발견 종합

예제 2: 경쟁 가설 디버깅

여러 이론을 동시에 테스트합니다.

앱이 첫 메시지 후 종료되는 문제를 조사해줘.
5명의 팀원을 만들어서 각자 다른 가설을 조사하고,
서로의 이론을 반박하도록 해줘.
발견한 내용을 findings.md에 업데이트해줘.

효과:

독립적인 조사로 앵커링 방지
팀원들이 서로 도전
생존한 이론이 근본 원인일 가능성 높음

예제 3: 교차 계층 개발

프론트엔드, 백엔드, 테스트를 동시에 작업합니다.

사용자 프로필 기능을 추가해줘.
3개 팀으로 나눠서:
1. 프론트엔드: React 컴포넌트
2. 백엔드: API 엔드포인트
3. 테스트: E2E 테스트

각 팀이 독립적으로 작업하되 서로 소통하게 해줘.

효과:

3배 빠른 진행
독립적인 모듈 개발
API 스펙으로 조율

🔧 팀 제어하기

팀원 수 지정

4명의 팀원으로 팀을 만들어서 이 모듈들을 병렬로 리팩토링해줘.
각 팀원은 Sonnet 모델을 사용해줘.

계획 승인 요구

복잡한 작업에 대해 계획을 먼저 승인합니다.

인증 모듈을 리팩토링할 architect 팀원을 만들어줘.
변경하기 전에 계획 승인을 요구해줘.

과정:

팀원이 읽기 전용 계획 모드에서 시작
계획 완성 후 리더에게 승인 요청
리더가 검토 후 승인/거부
승인되면 구현 시작

팀원과 직접 대화

In-process 모드:

Shift+Down: 팀원 순환
입력: 현재 팀원에게 메시지
Enter: 팀원 세션 보기
Escape: 현재 턴 중단
Ctrl+T: 작업 목록 토글

분할 창 모드:

팀원 창 클릭: 직접 상호작용

작업 할당

리더가 할당:

frontend 팀원에게 다음 작업을 할당해줘: ProfilePage 컴포넌트 만들기

자체 요청: 팀원들이 작업 목록에서 스스로 선택합니다.

팀원 종료

researcher 팀원에게 종료하도록 요청해줘

팀 정리

완료 후 항상 정리하세요:

팀을 정리해줘

반드시 리더에서 정리하세요. 팀원에서 정리하면 안 됩니다.

📚 모범 사례

1. 적절한 팀 크기

권장 크기: 3-5명

팀원 수가 많을수록:
- 토큰 비용 선형 증가
- 조율 오버헤드 증가
- 수익 감소

권장: 팀원당 5-6개 작업 유지

2. 충분한 컨텍스트 제공

팀원은 대화 기록을 상속하지 않습니다.

나쁜 예:

보안 검토자 팀원을 만들어줘

좋은 예:

다음 프롬프트로 보안 검토자 팀원을 만들어줘:
"src/auth/ 의 인증 모듈을 보안 취약점 관점에서 검토해줘.
토큰 처리, 세션 관리, 입력 검증에 집중해줘.
앱은 httpOnly 쿠키에 JWT 토큰을 저장해.
심각도와 함께 문제를 보고해줘."

3. 적절한 작업 크기

너무 작음:

조율 오버헤드가 이점 초과

너무 큼:

팀원이 너무 오래 고립
낭비 위험 증가

적절함:

함수, 테스트 파일, 검토 같은 명확한 단위
팀원당 5-6개 작업

4. 파일 충돌 피하기

나쁜 예:

두 팀원이 같은 파일 편집
→ 덮어쓰기 발생

좋은 예:

각 팀원이 다른 파일 집합 소유
→ 충돌 없음

5. 모니터링 및 조율

정기적으로:

진행 상황 확인
막힌 팀원 재지정
발견 내용 종합

팀원이 기다리지 않고 작업 시작하면:

팀원들이 작업을 완료할 때까지 기다려줘

6. 연구로 시작

처음 사용할 때:

PR 검토
라이브러리 연구
버그 조사

코드 작성은 나중에 시도하세요.

🛠️ 고급 기능

Subagent 정의 재사용

팀원 생성 시 subagent 정의를 참조할 수 있습니다.

security-reviewer agent 타입을 사용해서
auth 모듈을 감사할 팀원을 만들어줘.

팀원이 해당 subagent의:

시스템 프롬프트
도구 제한
모델

을 상속합니다.

저장 위치

팀 구성:

~/.claude/teams/{team-name}/config.json

작업 목록:

~/.claude/tasks/{team-name}/

수동으로 편집하지 마세요. Claude Code가 자동 관리합니다.

⚠️ 문제 해결

팀원이 나타나지 않음

확인 사항:

Shift+Down으로 순환해보기 (In-process 모드)
작업이 팀을 보증할 만큼 복잡한지 확인
tmux 설치 확인 (분할 창 모드):
```
which tmux
```

너무 많은 권한 프롬프트

팀원 생성 전에 권한 설정에서 사전 승인:

{
  "permissions": {
    "allow": ["Read", "Write", "Edit", "Bash"]
  }
}

팀원이 오류에서 중단

In-process:

Shift+Down으로 팀원 확인
직접 지시 제공

분할 창:

창 클릭하여 확인
추가 지시 또는 대체 팀원 생성

리더가 조기 종료

팀원들이 완료될 때까지 계속 기다려줘

고아 tmux 세션

팀 정리가 완전하지 않으면 발생:

# 세션 확인
tmux ls

# 종료
tmux kill-session -t <session-name>

📊 토큰 비용

Agent Teams는 단일 세션보다 훨씬 많은 토큰을 사용합니다.

비용 계산:

총 토큰 = 팀원 수 × 각 팀원의 컨텍스트

언제 가치가 있나:

연구 및 검토
새로운 기능 개발
복잡한 디버깅

언제 비효율적인가:

일상적인 작업
순차적 단계
간단한 수정

⚠️ 제한사항

Agent Teams는 실험적 기능입니다. 현재 알려진 제한사항:

In-process 팀원과 세션 재개 불가: /resume 및 /rewind는 in-process 팀원을 복원하지 않습니다. 세션 재개 후 리더가 더 이상 존재하지 않는 팀원에게 메시지를 보내려 할 수 있습니다. 이 경우 리더에게 새 팀원을 생성하도록 요청하세요.
작업 상태가 지연될 수 있음: 팀원이 때때로 작업을 완료로 표시하지 못해 종속 작업이 차단될 수 있습니다. 작업이 멈춘 것처럼 보이면 실제로 완료되었는지 확인하고 수동으로 상태를 업데이트하거나 리더에게 팀원을 독려하도록 요청하세요.
종료가 느릴 수 있음: 팀원은 종료하기 전에 현재 요청이나 도구 호출을 완료하므로 시간이 걸릴 수 있습니다.
세션당 한 팀만 가능: 리더는 한 번에 하나의 팀만 관리할 수 있습니다. 새 팀을 시작하기 전에 현재 팀을 정리하세요.
중첩 팀 불가: 팀원은 자신의 팀이나 팀원을 생성할 수 없습니다. 리더만 팀을 관리할 수 있습니다.
리더 고정: 팀을 생성한 세션이 팀의 수명 동안 리더입니다. 팀원을 리더로 승격하거나 리더십을 이전할 수 없습니다.
생성 시에만 권한 설정 가능: 모든 팀원은 리더의 권한 모드로 시작합니다. 생성 후 개별 팀원 모드를 변경할 수 있지만 생성 시 팀원별 모드를 설정할 수는 없습니다.
분할 창은 tmux 또는 iTerm2 필요: 기본 in-process 모드는 모든 터미널에서 작동합니다. 분할 창 모드는 VS Code 통합 터미널, Windows Terminal, Ghostty에서는 지원되지 않습니다.

CLAUDE.md는 정상 작동합니다. 팀원들이 프로젝트별 지침을 읽습니다.

✅ 완료

Agent Teams로 여러 독립 세션을 조율하는 방법을 배웠습니다!

배운 것:

✅ Agent Teams 개념 (독립 세션 조율)
✅ Sub-agents와의 차이
✅ 팀 생성 및 관리
✅ 표시 모드 (In-process vs 분할 창)
✅ 실용적인 사용 사례
✅ 모범 사례
✅ 제한사항 이해

핵심 개념:

독립적인 Claude Code 인스턴스들의 협업
공유 작업 목록으로 자체 조율
팀원 간 직접 메시징
병렬 탐색이 가치를 더하는 작업에 적합
토큰 비용이 높지만 복잡한 작업에 가치 있음

Sub-agents vs Agent Teams:

Sub-agents: 결과만 중요할 때
Agent Teams: 협업과 논의가 필요할 때

다음에는: Troubleshooting으로 문제 해결 방법을 배웁니다.

다음 단계

고급 8: Troubleshooting →

Agent Teams로 병렬 협업하기

목차

⚠️ 중요: 실험적 기능

🎯 Agent Teams란?

핵심 개념

Sub-agents vs Agent Teams

아키텍처

💡 언제 사용하나?

Agent Teams가 적합한 경우

단일 세션이 더 나은 경우

🚀 첫 번째 팀 만들기

기본 사용법

표시 모드

🎨 실용적인 예제

예제 1: 병렬 코드 검토

예제 2: 경쟁 가설 디버깅

예제 3: 교차 계층 개발

🔧 팀 제어하기

팀원 수 지정

계획 승인 요구

팀원과 직접 대화

작업 할당

팀원 종료

팀 정리

📚 모범 사례

1. 적절한 팀 크기

2. 충분한 컨텍스트 제공

3. 적절한 작업 크기

4. 파일 충돌 피하기

5. 모니터링 및 조율

6. 연구로 시작

🛠️ 고급 기능

Subagent 정의 재사용

저장 위치

⚠️ 문제 해결

팀원이 나타나지 않음

너무 많은 권한 프롬프트

팀원이 오류에서 중단

리더가 조기 종료

고아 tmux 세션

📊 토큰 비용

⚠️ 제한사항

✅ 완료

다음 단계