Claude Code Agent Teams 완벽 가이드

개요

Claude Code의 Agent Teams는 여러 에이전트가 하나의 팀을 이루어 서로 소통하며 협업하는 기능이다. 기존 Subagent와의 차이점을 회사 조직 비유를 통해 설명하고, 핵심 용어와 활성화 방법, 비용 절감 전략까지 단계별로 정리한다.

Subagent vs Agent Teams

Subagent가 적합한 경우 — 독립적인 작업

네 개 지역(서울, 부산, 대구, 광주)의 커피 프랜차이즈 시장 보고서를 만들어야 하는 상황을 가정해 보자. 각 지역 보고서는 서로 관련이 없다. 팀원 네 명에게 하나씩 맡기면 각자 알아서 조사하고 완성본만 가져오면 된다. 팀원끼리 대화할 필요가 없고, 결과만 받으면 업무가 끝난다.

이것이 Subagent가 동작하는 방식이다. 각 에이전트가 독립적으로 일하고 결과만 반환한다.

Agent Teams가 적합한 경우 — 협업이 필요한 작업

이번에는 "직장인 점심 도시락 배달 서비스 런칭 기획안"을 만들어야 하는 상황이다. 팀원 네 명에게 시장 조사, 경쟁사 분석, 예산안, 일정표를 각각 맡겼다. 그런데 이 경우는 상황이 다르다.

예산 담당 팀원이 예산을 짜다가 시장 조사 팀원에게 "직장인 도시락 시장 규모가 얼마나 나왔어?"라고 물어봐야 하고, 시장 조사 담당이 시장 규모를 알려줘야 예산 담당이 막힘없이 업무를 할 수 있다.

같은 네 명이지만, 업무 성격에 따라 일하는 방식이 완전히 달라지는 것이다. 에이전트들이 하나의 팀을 이루면서 서로 소통하며 협업하는 방식이 바로 Agent Teams이다.

Subagent의 3가지 한계

Agent Teams를 이해하려면, 먼저 Subagent의 한계를 알아야 한다.

Subagent란?

메인 컨텍스트와 분리된 별도의 컨텍스트를 갖고 있는 에이전트이다. 메인 컨텍스트에서 Subagent를 호출하면, Subagent는 자기만의 별도 컨텍스트를 만들어서 그 안에서 작업한다. 작업이 끝나면 결과만 요약해서 메인 컨텍스트에 돌려준다.

Subagent가 파일 100개를 뒤져도 메인 컨텍스트는 깨끗하게 유지된다. 결과 요약 몇 줄만 넘어오기 때문에, 메인 컨텍스트가 금방 차버리는 문제를 막아준다.

핵심: 메인과 분리된 별도 컨텍스트에서 작업하고 결과 요약만 리턴하기 때문에, 메인 컨텍스트를 아끼면서 더 길고 복잡한 작업을 이어갈 수 있게 해준다.

한계 1: Subagent 간 직접 대화 불가

Subagent를 병렬로 여러 개 실행했을 때, Subagent 간에 직접 대화를 할 수 없다. 프론트엔드 개발자 A가 API 스펙 문제를 발견했는데, 바로 옆에 앉아 있는 백엔드 개발자 B에게 직접 말을 못하는 것과 같다.

한계 2: 결과 요약만 메인에 돌아옴

Subagent가 파일 50개를 분석하면서 "이 파일에서 이상한 패턴을 발견했는데, 당장은 문제가 아니네"라고 넘어간 것들이 있을 수 있다. 그런데 메인 컨텍스트에는 최종 요약 몇 줄만 돌아오기 때문에, 중간에 발견된 미묘한 단서들은 사라진다. 나중에 "아까 그 파일에서 무엇을 봤지?"라고 물어볼 수도 없다.

한계 3: 메인 에이전트 혼자서 모든 것을 관리

팀장 혼자서 팀원 전원에게 일을 나눠주고, 결과를 받고, 종합한다. Subagent가 늘어갈수록 메인의 부담이 커지고 병목이 생긴다. 메인 컨텍스트가 이런 조율 작업으로 빠르게 차버리면, 더 복잡한 작업을 이어 나가기 어렵다.

정리

Subagent가 소통이 필요 없는 두세 개일 때는 괜찮다. 하지만 작업이 복잡해지면서 Subagent를 여러 개 돌리다 보면, 메인 컨텍스트가 조율하느라 빠르게 차버리거나, Subagent 간 정보를 공유해야 하는 상황이 생긴다. 공식 문서에서도 이 시점을 콕 집어서 말한다: 이때가 Agent Teams로 넘어갈 타이밍이다.

아이디어는 단순하다. 팀장이 전부 중계하지 말고, 팀원끼리 직접 소통하고 스스로 작업을 나눠 가지게 하자.

Agent Teams의 4가지 핵심 특징

1. 컨텍스트 (Context)

• Subagent: 작업이 끝나면 결과 요약만 메인에게 돌아온다. 중간에 스쳐 지나간 단서는 사라진다.
• Agent Teams: 팀원은 완전히 독립된 자기만의 컨텍스트를 유지한다. 수상한 파일 정보도 팀원의 컨텍스트에 그대로 남아있기 때문에, 나중에 "아까 그 파일 다시 확인해봐"라고 요청할 수 있다.

2. 소통 (Communication)

• Subagent: 메인에게만 보고한다. 보안 담당 Subagent가 "이 부분 성능에도 영향을 줄 수 있겠는데"라고 느껴도, 성능 담당 Subagent에게 직접 말을 못 한다. 전달하려면 메인에게 보고하고, 메인이 다시 전달해야 한다.
• Agent Teams: 보안 담당 팀원이 성능 담당 팀원에게 바로 "이거 한번 봐봐"라고 메시지를 보낼 수 있다.

3. 조율 (Coordination)

• Subagent: 메인이 전부 관리한다. "A야 이거 해, B야 저거 해, 끝나면 다음 이거 해." 매번 메인이 지시해야 한다.
• Agent Teams: 공유된 Task List가 있어서, 리드가 할당하기도 하고, 팀원이 자기 작업이 끝나면 다음 Task를 스스로 가져가기도 한다.

4. 비용 (Cost)

Agent Teams의 비용이 당연히 더 높다. 각 팀원이 독립된 Claude 세션을 사용하기 때문에, 팀원이 세 명이면 대략 세 배 이상의 토큰이 사용된다.

한 줄 요약: Subagent는 시키면 혼자 다 하고 결과만 보고하는 프리랜서라면, Agent Teams는 서로 대화하면서 같이 일하는 하나의 팀이다.

핵심 용어 5가지

1. Team Lead (팀 리드)

• 팀장 역할
• 터미널에서 claude 명령어로 실행한 Claude Code 세션이 팀 리드가 됨
• 해야 할 작업을 나누고, 팀원을 생성하고, 결과를 종합해서 사용자에게 응답
• 한 번 리드가 정해지면 변경할 수 없음

2. Teammate (팀메이트)

• 팀원 역할
• 리드가 만든 Claude Code의 추가 세션
• 각 팀메이트는 자기만의 독립된 컨텍스트를 가지고 그 안에서 작업
• Subagent와 달리 팀원들은 메시지를 서로 주고받을 수 있음
• 업무가 끝나고 리드에게 보고를 마친 상태에서도 대화 이력이 그대로 남아있음

3. Spawn (스폰)

• 새로운 팀원 세션을 생성한다는 뜻
• 게임에서 캐릭터가 생성되는 것처럼, 리드에게 "팀원 세 명을 만들어줘"라고 하면 리드가 팀원을 Spawn함

4. Task List (태스크 리스트)

모든 팀원이 같이 보는 공유 작업 목록이다. 리드가 Task List를 만들면 팀원들이 작업을 하나씩 처리하는 구조이다.

각 작업에는 세 가지 상태가 있다:

• 대기 중 (Pending): 아직 아무도 시작하지 않은 상태
• 진행 중 (In Progress): 누군가가 작업을 가져간 상태
• 완료됨 (Completed): 작업이 끝난 상태

Task 할당 방식:

• 리드가 직접 지정: "시장 조사는 A, 경쟁사 분석은 B, 예산안은 C." 한 팀원에게 여러 작업을 미리 배정할 수도 있다.
• 팀원이 스스로 가져감: 자기 작업이 끝났는데 아무에게도 배정 안 된 작업이 남아 있으면, 팀원이 알아서 가져간다. 팀장의 부담을 줄이면서 효율적으로 업무를 처리할 수 있다.

5. Mailbox (메일박스)

팀원끼리 메시지를 보내는 시스템이다:

• 리드 ↔ 팀원 사이의 메시지
• 팀원 ↔ 팀원 사이의 메시지

Agent Teams 동작 흐름

Agent Teams를 사용한 작업의 전체 흐름은 다음과 같다:

1. 팀 생성: 사용자가 자연어로 팀 구성을 요청
2. Task 생성: 팀원들에게 업무를 맡기기 전에 Task를 먼저 생성
3. 팀원 Spawn: 필요한 수만큼 팀원을 동시에 생성
4. 병렬 작업: 각 팀원이 자신의 업무를 병렬로 수행
5. 진행 상황 확인: 팀 리드에게 진행 상황을 확인하면, 각 팀원의 현재 작업 상태를 피드백 받을 수 있음
6. 결과 종합: 모든 팀원의 작업이 완료되면, 팀 리드가 결과를 종합

Agent Teams 활성화 설정

Agent Teams는 실험적 단계이기 때문에 기본적으로 비활성화되어 있다. 활성화하려면 settings.json에 다음 환경 변수를 설정한다:

{
  "env": {
    "CLAUDE_CODE_ENABLE_AGENT_TEAMS": "1"
  }
}

활성화 후에는 Claude에게 자연어로 팀 구성을 요청하면 된다.

팁: 에이전트 팀으로 진행해 달라고 했는데 Claude Code가 서브에이전트로 진행할 수 있다. 이럴 때는 내부적으로 에이전트 팀을 생성하는 TeamCreate를 명시적으로 선언하면 에이전트 팀을 정확히 실행할 수 있다.

디스플레이 모드

Agent Teams를 실행할 때, 팀원들을 어떻게 보여줄지 두 가지 표시 모드가 있다.

In-Progress 모드 (기본)

• 하나의 터미널에서 Shift + 방향키 Down으로 팀원들을 순환하면서 보는 방식
• 모든 터미널에서 동작하며 추가 설치가 필요 없음

Split Panes 모드 (분할 창)

• 화면을 분할해서 각 팀원을 동시에 볼 수 있는 표시 모드
• 사용하려면 다음 중 하나가 필요:
  • tmux: 하나의 터미널 화면을 여러 개로 나눠주는 도구. macOS와 Linux에서 사용 가능.
  • iTerm2: macOS 전용 터미널 앱.

설정 방법

settings.json에서 teammate_display_mode를 설정한다:

팀원 세션 조작

• Shift + 방향키 아래: 팀 리드와 각 팀원 세션을 순환
• Enter: 선택한 팀원의 세션으로 진입
• Hide: 해당 세션을 숨기고 다시 순환 가능

비용 절감 전략

Agent Teams는 강력하지만 토큰 비용이 크다. 비용을 줄이면서 품질은 유지하는 핵심 전략을 정리한다.

전략 1: 서브에이전트와 팀원의 차이를 이해하고 선택하라

팀원(Teammate)과 서브에이전트(Subagent)는 생성 방식에 핵심적인 차이가 있다.

팀원: 사용자가 Claude Code를 새로 켤 때와 똑같이 실행된다. 메모리 파일, MCP 도구, 스킬 등이 전부 자동으로 로딩된다. 단, 사용자가 리드와 나눈 대화 기록은 제외되고, 생성할 때 리드가 넣어준 프롬프트만 받는다.

서브에이전트: 별도 컨텍스트에서 돌아간다. 메모리 파일이나 MCP는 자동으로 상속받지만, 스킬은 자동으로 넘어가지 않는다. 서브에이전트를 생성할 때 스킬 필드에 명시적으로 지정해야 해당 스킬을 사용할 수 있다.

프로젝트의 스킬이 많고 팀원마다 다른 스킬을 써야 한다면 → 서브에이전트가 적합 모든 팀원이 같은 스킬 세트를 공유해도 괜찮다면 → 팀원이 편리

전략 2: Plan Approval로 토큰 낭비를 방지하라

에이전트 팀을 생성하면 팀원이 기본적으로 바로 코딩을 시작한다. 방향이 틀어진 채로 한참 작업하면 그동안 쓴 토큰이 전부 낭비된다.

해결책: 팀을 생성할 때 한 줄만 추가한다.

"각 팀원이 변경하기 전에 계획 승인을 받도록 해 줘"

이렇게 하면 팀원이 읽기 전용 모드(Plan Mode) 로 시작되어 코드를 수정할 수 없고, 분석만 진행한다.

Plan Approval 워크플로우:

1. 팀원이 Plan Mode로 시작 → 코드를 읽고 분석만 수행
2. 분석이 완료되면 계획을 세워서 리드에게 제출
3. 리드가 계획을 보고 승인 → Plan Mode 해제, 구현 시작
4. 리드가 거절 → 피드백을 반영하여 계획 수정 후 재제출

리드가 자동으로 판단하게 만드는 팁:

프롬프트에 판단 기준을 미리 정의해 둘 수 있다:

• 테스트 커버리지를 포함하는 계획만 승인
• 데이터베이스 스키마를 수정하는 계획은 자동으로 차단

전략 3: 모델 믹싱 — 리드는 Opus, 팀원은 Sonnet

에이전트 팀의 토큰 사용량은 활성 팀원의 수에 비례하여 증가한다. 모든 팀원을 Opus로 돌리면 토큰이 빨리 소진된다. Opus 모델은 Sonnet 대비 4~5배 많은 토큰을 소비하기 때문이다.

효과적인 전략은 리드와 팀원의 모델을 분리하는 것이다:

프롬프트에 "팀원 모두 Sonnet을 사용해" 한 줄만 추가하면 된다.

추가 비용 절감 팁:

• 팀이 진짜 필요한지 판단하기: 팀원끼리 소통할 필요가 없는 작업이면 서브에이전트를 사용하는 것이 좋다.
• 최소 인원으로 시작하기: 대부분의 작업에서 팀원 3~5명이면 충분하다. 공식 문서에서도 이 범위를 권장한다.
• 작업이 끝난 팀원은 즉시 종료하기: 팀원 세션이 살아있으면 계속 토큰을 소모할 수 있다. "○○ 팀원을 종료해 줘" 또는 "팀을 정리해 줘"로 즉시 정리한다.

전략 4: CLAUDE.md에 비용 규칙 추가

팀원들도 CLAUDE.md 메모리 파일을 읽기 때문에, 여기에 비용 관련 규칙을 추가하면 팀원들이 해당 규칙을 따른다.

예를 들어 브로드캐스트(모든 팀원에게 동시에 보내는 전체 공지)는 팀원 수만큼 토큰을 소모하기 때문에, CLAUDE.md에 규칙을 배치하여 불필요한 브로드캐스트를 줄이는 것이 효과적이다.

Hooks로 자동 품질 게이트 만들기

Hooks란?

Claude Code의 이벤트 기반 자동화 시스템이다. "어떤 일이 일어나면 이 스크립트를 자동으로 실행해라"라는 규칙을 미리 설정해 두는 것이다.

Idle 상태

팀원 에이전트는 맡은 작업을 다 끝내거나 다음 지시를 기다릴 때 Idle(유휴) 상태가 된다. Claude Code의 훅으로 이 상태 변화를 감지하여, 검토나 테스트를 자동으로 실행할 수 있다.

에이전트 팀에서 사용 가능한 훅

TeammateIdle Hook

• 발동 단위: 팀원 단위
• 발동 시점: 팀원이 모든 일을 마치고 Idle 상태로 들어가려고 할 때
• 활용 예시: 작업이 끝나면 요약 보고서를 작성하는 등 전체 작업 관련 후속 처리

TaskCompleted Hook

• 발동 단위: Task 단위
• 발동 시점: 팀원이 개별 Task를 완료하고 상태를 전환하는 시점
• 활용 예시: 작업 완료를 차단하고 검증 후 다시 업무를 시키는 것

두 훅의 차이

하나의 팀원이 3개의 Task를 수행한다면:

• TaskCompleted Hook: 3번 발동 (각 Task 완료 시마다)
• TeammateIdle Hook: 1번 발동 (모든 Task 완료 후)

따라서:

• TaskCompleted Hook → 개별 Task에 대한 검증
• TeammateIdle Hook → 팀원의 전체 작업 검증

비교 요약