Claude Code Agent Teams: 여러 AI가 함께 코딩하는 시대

작성일: 2026년 2월 6일
카테고리: Claude Code, AI Agent, Multi-Agent
키워드: Claude Code, Agent Teams, 멀티에이전트, Lead-Teammate, 병렬 개발, Hook

요약

Claude Code v2.1.32에서 Agent Teams 기능이 연구 미리보기로 출시되었다. 하나의 Claude Code 세션에서 여러 AI 에이전트가 병렬로 작업하고 직접 통신하는 멀티에이전트 시스템이다. 이 글에서는 Agent Teams의 아키텍처, 설정 방법, 실전 사용 패턴, 그리고 제한사항까지 상세히 다룬다.

왜 멀티에이전트인가

단일 에이전트의 병목

AI 코딩 어시스턴트를 사용할 때 가장 흔한 불만은 "느리다"가 아니라 "한 번에 하나만 한다"이다.

10개 모듈을 리팩토링해야 하는 상황을 생각해보자. 단일 에이전트는 모듈 1을 수정하고, 테스트하고, 다음 모듈로 넘어간다. 모듈 간 의존성이 없는데도 순차적으로 처리한다. 개발자가 3명이면 3배 빠를 작업을 1명이 하는 셈이다.

단일 에이전트의 구조적 한계를 정리하면:

한계	설명
순차 실행	독립적인 작업도 하나씩 처리
컨텍스트 독점	하나의 컨텍스트 윈도우에 모든 정보를 넣어야 함
단일 관점	보안, 성능, 테스트를 한 에이전트가 모두 판단
장시간 작업의 피로	작업이 길어질수록 초기 결정을 잊거나 번복

주방의 비유

1인 식당과 전문 분업 주방의 차이와 같다.

1인 식당에서는 주문 받기, 식재료 손질, 조리, 플레이팅을 한 사람이 전부 처리한다. 주문이 3개만 밀려도 병목이 생긴다.

전문 주방에서는 헤드 셰프가 전체를 조율하고, 수셰프들이 전채, 메인, 디저트를 병렬로 준비한다. 주문표(Task List)로 진행 상황을 공유하고, 필요하면 직접 대화한다.

Agent Teams는 이 전문 주방 모델을 AI 코딩에 적용한 것이다.

아키텍처

Lead-Teammate 구조

Agent Teams는 Orchestrator-Worker 패턴을 따른다. 하나의 Lead(지휘자)가 여러 Teammate(실행자)를 조율하는 구조다.

graph TB
    Lead["Team Lead"]
    TL["Shared Task List"]
    MB["Mailbox"]
    T1["Teammate 1"]
    T2["Teammate 2"]
    T3["Teammate 3"]

    Lead --> TL
    Lead --> MB
    TL --> T1
    TL --> T2
    TL --> T3
    T1 --> MB
    T2 --> MB
    T3 --> MB

    style Lead stroke:#2563eb,stroke-width:3px
    style TL stroke:#16a34a,stroke-width:3px
    style MB stroke:#ea580c,stroke-width:3px
    style T1 stroke:#4b5563,stroke-width:2px
    style T2 stroke:#4b5563,stroke-width:2px
    style T3 stroke:#4b5563,stroke-width:2px

각 구성요소의 역할:

구성요소	역할	비유
Team Lead	작업 분배, 진행 조율, 결과 통합	헤드 셰프
Teammate	독립적 작업 실행, 자체 컨텍스트 보유	수셰프
Shared Task List	전체 작업 상태 공유	주문표
Mailbox	에이전트 간 메시지 전달	주방 인터콤

핵심은 각 Teammate가 독립된 Claude Code 인스턴스라는 점이다. 자체 컨텍스트 윈도우를 가지며, Lead의 대화 이력을 상속받지 않는다. 대신 프로젝트의 CLAUDE.md, MCP 서버, Skills는 자동으로 로드된다.

통신 방식

에이전트 간 통신은 세 가지 방법으로 이루어진다:

1:1 메시지 (message)
특정 Teammate에게 직접 메시지를 보낸다. Lead가 "Teammate 2에게 보안 검토 결과를 보내"라고 하면, 해당 Teammate만 메시지를 수신한다.

전체 브로드캐스트 (broadcast)
모든 Teammate에게 동시에 메시지를 보낸다. "전원 작업 중단하고 현재 진행 상황 보고" 같은 지시에 사용된다.

유휴 알림 (Idle Notification)
Teammate가 할당된 작업을 완료하면 자동으로 Lead에게 알림이 간다. Lead가 지속적으로 폴링할 필요 없이, Teammate가 "끝났습니다"라고 보고하는 방식이다.

작업 분배 메커니즘

작업은 세 가지 상태를 거친다:

graph LR
    P["Pending"]
    I["In Progress"]
    C["Completed"]

    P --> I
    I --> C

    style P stroke:#ea580c,stroke-width:3px
    style I stroke:#2563eb,stroke-width:3px
    style C stroke:#16a34a,stroke-width:3px

작업 할당에는 두 가지 방식이 있다:

• Lead 할당: Lead가 특정 Teammate에게 명시적으로 작업을 배정
• 자율 선택 (Claim): Teammate가 Task List에서 Pending 상태의 작업을 스스로 선택

여러 Teammate가 동시에 같은 작업을 선택하는 race condition을 방지하기 위해 file locking 메커니즘을 사용한다.

설정과 시작

활성화

Agent Teams는 현재 연구 미리보기 상태이므로 명시적으로 활성화해야 한다.

방법 1: 환경변수

# 세션 시작 시 활성화
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

방법 2: settings.json

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

Display Mode

Teammate의 표시 방식을 선택할 수 있다:

모드	특징	적합한 환경
in-process	단일 터미널에서 Shift+위/아래로 전환	VS Code 통합 터미널, Windows Terminal
tmux	각 Teammate가 별도 tmux pane에 표시	tmux/iTerm2가 설치된 환경

{
  "teammateMode": "in-process"
}

참고: tmux 모드에서 split pane을 사용하려면 tmux 또는 iTerm2가 필요하다. VS Code 통합 터미널, Windows Terminal, Ghostty에서는 split pane이 지원되지 않는다.

기본 사용

활성화 후 자연어로 팀 생성을 요청하면 된다:

이 프로젝트의 인증 모듈, 결제 모듈, 알림 모듈을 각각 리팩토링해줘.
3명의 teammate를 생성해서 병렬로 처리해.

Lead가 자동으로 작업을 분해하고 Teammate를 생성한다.

실전 사용 패턴

패턴 1: 병렬 코드 리뷰

하나의 PR을 여러 관점에서 동시에 검토한다.

PR #142를 리뷰할 Agent Team을 만들어줘.
3명의 리뷰어를 생성해:
- 보안 취약점 전담
- 성능 영향 분석 전담
- 테스트 커버리지 검증 전담
각자 리뷰하고 결과를 보고해.

단일 에이전트가 순차적으로 보안 → 성능 → 테스트를 검토하면 시간도 오래 걸리고, 앞서 확인한 보안 이슈의 맥락이 테스트 검토 시점에 희석된다. 병렬 리뷰는 각 전담 에이전트가 자신의 영역에 집중하므로 품질도 향상된다.

패턴 2: 경쟁 가설 디버깅

원인을 모르는 버그를 여러 가설로 동시에 조사한다.

사용자가 메시지 한 번 보내면 앱이 종료되는 버그가 보고됨.
5명의 teammate를 생성해서 서로 다른 가설을 조사해:
- WebSocket 연결 끊김
- 메모리 누수
- 이벤트 핸들러 중복 등록
- 인증 토큰 만료
- 프로세스 시그널 처리 오류
서로 대화하면서 상대방의 가설을 반증해봐. 과학적 토론처럼.

이 패턴의 핵심은 Teammate 간 직접 통신이다. Teammate 1이 "WebSocket은 정상이다"라는 증거를 찾으면, 다른 Teammate들에게 공유하여 불필요한 조사를 줄인다.

패턴 3: 모듈 병렬 구현

독립적인 모듈을 동시에 개발한다.

4명의 teammate로 다음 모듈을 병렬 리팩토링해줘.
각 teammate는 Sonnet 모델을 사용해.
- Teammate 1: src/auth/ 모듈
- Teammate 2: src/payment/ 모듈
- Teammate 3: src/notification/ 모듈
- Teammate 4: src/logging/ 모듈

주의: 이 패턴은 모듈 간 의존성이 없을 때만 사용해야 한다. 두 Teammate가 같은 파일을 수정하면 나중에 쓴 내용이 앞선 수정을 덮어쓴다.

Hook 이벤트로 워크플로우 자동화

v2.1.33에서 Agent Teams 전용 Hook 이벤트 2개가 추가되었다.

TeammateIdle

Teammate가 할당된 작업을 완료하고 유휴 상태가 되면 발생한다.

{
  "hooks": {
    "TeammateIdle": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Teammate idle: checking for remaining tasks'",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

활용 예시:

• 유휴 Teammate에게 대기 중인 작업 자동 할당
• Slack/Discord로 진행 상황 알림 전송
• 모든 Teammate가 유휴 상태면 최종 통합 테스트 실행

TaskCompleted

작업이 완료 상태로 전환되면 발생한다.

{
  "hooks": {
    "TaskCompleted": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Task completed - running validation'",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

활용 예시:

• 완료된 모듈의 단위 테스트 자동 실행
• 의존성 있는 후속 작업 자동 해제
• 완료율 대시보드 업데이트

Hook 타입은 세 가지가 있다:

타입	설명	용도
command	셸 스크립트 실행	테스트 실행, 알림 전송
prompt	LLM 단일 호출 (도구 접근 없음)	yes/no 판단, 분류
agent	서브에이전트 실행 (도구 접근 가능)	복잡한 후속 처리

제한사항과 주의점

Agent Teams는 연구 미리보기 상태다. 실무에 적용하기 전에 다음 제한사항을 반드시 확인해야 한다.

제한사항	설명
토큰 비용	각 Teammate가 별도 컨텍스트 윈도우를 사용한다. 3명의 Teammate = 약 4배의 토큰 소비
같은 파일 동시 수정 불가	두 Teammate가 같은 파일을 수정하면 덮어쓰기 발생
중첩 팀 불가	Teammate가 자신의 하위 팀을 생성할 수 없음
리더 변경 불가	팀 생성 후 Lead 교체 불가
세션 복원 제한	/resume, /rewind로 기존 Teammate를 복원할 수 없음
1 팀/세션	Lead는 동시에 하나의 팀만 관리 가능
Split Pane 환경 제한	tmux 모드는 tmux/iTerm2 필요. VS Code 통합 터미널, Windows Terminal 미지원

토큰 비용에 대한 현실적 고려

Agent Teams의 가장 큰 진입 장벽은 비용이다. Opus 4.6 기준으로 각 Teammate가 독립된 Claude 인스턴스이므로, Teammate 수에 비례하여 비용이 증가한다.

사용 방식	적합한 요금제
가벼운 탐색 (1-2 Teammate)	Pro 요금제
본격적 병렬 작업 (3+ Teammate)	Max 요금제 또는 API
대규모 프로젝트	API (비용 상한 설정 권장)

노력 수준(effort level)을 조절하여 비용을 관리할 수 있다. 탐색 위주 Teammate에는 낮은 노력 수준을, 핵심 구현 Teammate에는 높은 수준을 설정하는 전략이 효과적이다.

베스트 프랙티스

실제 사용 경험과 공식 문서를 바탕으로 정리한 권장사항이다.

1. 독립적인 작업으로 분해하라

Agent Teams의 효과는 작업의 독립성에 비례한다. 같은 파일을 건드리는 작업을 병렬로 돌리면 충돌이 발생한다. 모듈, 디렉토리, 또는 관심사 기준으로 분리해야 한다.

# 나쁜 분배: 같은 파일을 여러 Teammate가 수정
Teammate 1: utils.ts에 함수 추가
Teammate 2: utils.ts에서 함수 리팩토링

# 좋은 분배: 서로 다른 영역
Teammate 1: src/auth/ 전체 리팩토링
Teammate 2: src/payment/ 전체 리팩토링

2. Spawn 프롬프트에 충분한 컨텍스트를 포함하라

Teammate는 Lead의 대화 이력을 상속받지 않는다. 작업 지시 시 필요한 배경 정보를 명시적으로 전달해야 한다.

# 부족한 컨텍스트
"이 버그 고쳐"

# 충분한 컨텍스트
"src/auth/login.ts의 validateToken 함수에서 만료된 토큰을
갱신하지 않는 버그가 있다. refreshToken 로직이 catch 블록에서
호출되지 않는 것이 원인으로 추정된다. 관련 테스트는
tests/auth/login.test.ts에 있다."

3. 적절한 작업 크기를 유지하라

공식 문서에서 권장하는 작업 크기는 Teammate당 5-6개 태스크다. 너무 작으면 에이전트 생성/통신 오버헤드가 크고, 너무 크면 중간 점검이 어렵다.

4. 처음에는 읽기 전용 작업부터 시작하라

Agent Teams에 익숙하지 않다면, 코드를 수정하지 않는 작업부터 시작하는 것이 안전하다:

• 코드 리뷰
• 버그 원인 조사
• 코드베이스 문서화
• 테스트 커버리지 분석

수정 작업은 팀의 동작 방식을 충분히 이해한 후에 시도하는 것이 좋다.

5. Lead는 직접 작업하지 마라

Lead가 직접 코드를 작성하면서 동시에 Teammate를 관리하면, Teammate의 보고를 놓치거나 작업이 꼬일 수 있다. Lead는 조율에 집중하고, 실제 작업은 Teammate에게 위임(delegate mode)하는 것이 권장된다.

Agent Teams가 적합한/부적합한 작업

적합한 작업	부적합한 작업
독립 모듈 병렬 구현	순차적 의존성이 높은 작업
멀티 관점 코드 리뷰	같은 파일을 동시 수정
경쟁 가설 디버깅	단순한 한 줄 수정
코드베이스 탐색/분석	짧은 질의응답
대규모 리팩토링 (파일 단위 분리 가능 시)	높은 대화형 상호작용이 필요한 작업

기존의 Task 도구(서브에이전트)와의 차이도 명확하다. Task는 메인 에이전트가 잠깐 하위 작업을 위임하고 결과를 받는 방식이다. Agent Teams는 여러 에이전트가 동등한 레벨에서 장시간 병렬로 작업하며, 서로 직접 통신한다.

참고 자료

공식 문서

• Claude Code Agent Teams
• Claude Code Hooks
• Claude Code CHANGELOG

관련 블로그

• Claude Opus 4.6 출시: 100만 토큰 컨텍스트와 에이전트 팀의 시대