Claude Code가 팀전 모드를 시작합니다! 반드시 사용해야 할 Agent Teams!

Claude Code가 또 한 번 대박을 터뜨렸습니다: Agent Teams, Sub Agents의 슈퍼 강화판으로 이해할 수 있습니다～ 아래 그림은 Agent Teams와 Subagents의 비교입니다:

저는 "먼저 사용해 보았습니다!" (아주 좋습니다! 아주 좋습니다! 아주 좋습니다!)

Agent Teams를 시작하는 조건: 
1. Claude Code를 최신 버전으로 업데이트하세요 (claude update) 

2. settings.json에 한 줄을 추가하세요:

"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" 

3. Claude Code를 재시작하세요～  

4. 그런 다음 자연어로 Claude Code에게 Agent Teams를 생성하도록 지시하세요 (물론, Agent Teams가 무엇을 해야 하는지 명확히 설명해야 합니다)  

또한, 다른 모델은 Agent Teams의 작업에 영향을 미치지 않습니다 (저는 코딩용 KIMi를 사용했습니다)

Agent Teams에 대한 자세한 내용은 아래 글을 참조하세요 (Anthropic 공식 문서)!

Agent Teams를 사용하면 여러 Claude Code 인스턴스를 함께 작업하도록 조정할 수 있습니다. 하나의 세션이 리더 역할을 하여 작업을 조정하고, 업무를 분배하며, 결과를 종합합니다. 팀원들은 독립적으로 작업하며, 각자 자신의 컨텍스트 창에서 작업하고, 직접 서로 대화할 수도 있습니다.

하위 에이전트(Subagents)와는 다릅니다 (하위 에이전트는 단일 세션에서 실행되며, 주 에이전트에게만 보고합니다). 또한 리더를 거치지 않고도 개별 팀원과 직접 상호작용할 수 있습니다.

이 문서는 다음을 다룹니다:

• • Agent Teams를 언제 사용할지, 최적의 사용 사례 및 하위 에이전트와의 비교 포함

• • 팀 시작하기

• • 팀원들 제어하기, 디스플레이 모드, 업무 분배 및 위임 포함

• • 병렬 작업의 모범 사례

Agent Teams를 언제 사용할까요

Agent Teams는 병렬 탐색이 진정한 가치를 더할 수 있는 작업에서 가장 효과적입니다. 가장 강력한 사용 사례는 다음과 같습니다:

• • 연구 및 검토 —— 여러 팀원이 문제의 다른 측면을 동시에 조사한 다음, 서로의 발견을 공유하고 도전할 수 있습니다

• • 새로운 모듈 또는 기능 —— 팀원들은 각각 독립적인 부분을 가질 수 있어 서로 방해받지 않습니다

• • 경쟁 가설을 통한 디버깅 —— 팀원들이 다른 이론을 병렬로 테스트하여 더 빠르게 답을 찾을 수 있습니다

• • 계층 간 조정 —— 프론트엔드, 백엔드 및 테스트에 걸친 변경 사항을 각각 다른 팀원이 담당합니다

Agent Teams는 조정 오버헤드를 증가시킵니다 (Opus4.6로 Agent Teams를 사용할 용기가 있나요🤣), 단일 세션 사용보다 토큰 소비가 크게 증가합니다. 소규모 팀이 독립적으로 운영될 수 있을 때 가장 효과적입니다. 순차적 작업, 동일 파일 편집 또는 많은 의존성이 있는 작업의 경우 단일 세션 또는 하위 에이전트가 더 효과적입니다.

하위 에이전트와 비교

Agent Teams와 하위 에이전트 모두 병렬 작업을 가능하게 하지만, 작동 방식이 다릅니다. 작업자들이 서로 통신해야 하는지에 따라 선택하세요:

하위 에이전트

Agent Teams

컨텍스트

자신의 컨텍스트 창; 결과는 호출자에게 반환됨

자신의 컨텍스트 창; 완전히 독립적

통신

주 에이전트에게만 결과 보고

팀원들이 직접 서로 메시지를 보냄

조정

주 에이전트가 모든 작업 관리

공유 작업 목록, 자기 조정

가장 적합한 경우

결과만 신경 쓰는 집중 작업

토론과 협업이 필요한 복잡한 작업

토큰 비용

낮음: 결과가 주 컨텍스트로 집계됨

높음: 각 팀원은 독립적인 Claude 인스턴스

빠르고 집중된 작업자가 결과를 보고해야 할 때는 하위 에이전트를 사용하세요. 팀이 발견을 공유하고, 서로 도전하며, 자기 조정이 필요할 때는 Agent Teams를 사용하세요.

Agent Teams 활성화

Agent Teams는 기본적으로 비활성화되어 있습니다. CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 환경 변수를 1 로 설정하여 활성화하세요. 셸 환경에서 또는 settings.json을 통해 설정할 수 있습니다:

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

첫 번째 Agent Team 시작하기

Agent Teams를 활성화한 후, Claude에게 Agent Team을 생성하라고 지시하고, 자연어로 작업과 원하는 팀 구조를 설명하세요. Claude는 당신의 프롬프트에 따라 팀을 생성하고, 팀원을 생성하며, 작업을 조정합니다.

이 예시는 세 역할이 독립적이며 서로를 기다리지 않고 문제를 탐색할 수 있기 때문에 효과적입니다:

Create an agent team to explore this from different angles: one teammate on UX, one on technical architecture, one playing devil's advocate.
(다른 각도에서 이를 탐색하는 Agent Team을 생성하세요: 한 팀원은 UX 담당, 한 팀원은 기술 아키텍처 담당, 한 팀원은 악역을 맡습니다.)

거기에서 Claude는 공유 작업 목록이 있는 팀을 생성하고, 각 관점에 대한 팀원을 생성하며, 그들이 문제를 탐색하고, 발견을 종합하며, 완료 후 팀을 정리하려고 시도합니다.

리더의 터미널에는 모든 팀원과 그들의 작업 내용이 나열됩니다. Shift+Up/Down을 사용하여 팀원을 선택하고 직접 메시지를 보내세요.

Agent Team 제어하기

자연어로 리더에게 원하는 것을 알려주세요. 리더는 당신의 지시에 따라 팀 조정, 업무 분배 및 위임을 처리합니다.

디스플레이 모드 선택

Agent Teams는 두 가지 디스플레이 모드를 지원합니다:

• • 프로세스 내 모드 —— 모든 팀원이 당신의 주 터미널 내에서 실행됩니다. Shift+Up/Down을 사용하여 팀원을 선택하고 직접 입력하여 메시지를 보내세요. 추가 설정 없이 모든 터미널에서 사용 가능합니다.

• • 분할 화면 모드 —— 각 팀원이 자신의 창을 가집니다. 모든 사람의 출력을 동시에 볼 수 있으며, 창을 클릭하여 직접 상호작용할 수 있습니다. tmux 또는 iTerm2가 필요합니다.

기본값은 "auto"이며, 이미 tmux 세션에서 실행 중이면 분할 화면을 사용하고, 그렇지 않으면 프로세스 내 모드를 사용합니다.

단일 세션에 대해 프로세스 내 모드를 강제로 사용하려면 플래그를 전달하세��:

claude --teammate-mode in-process

팀원 및 모델 지정

Claude는 당신의 작업에 따라 생성할 팀원 수를 결정하지만, 원하는 것을 정확히 지정할 수도 있습니다:

Create a team with 4 teammates to refactor these modules in parallel. Use Sonnet for each teammate.
(이 모듈들을 병렬로 리팩터링하는 4명의 팀원으로 구성된 팀을 생성하세요. 각 팀원에 Sonnet을 사용하세요.)

팀원에게 계획 승인 요구하기

복잡하거나 위험이 있는 작업의 경우, 팀원에게 구현 전 계획을 요구할 수 있습니다. 팀원은 리더가 그들의 방법을 승인할 때까지 읽기 전용 계획 모드에서 작업합니다:

Spawn an architect teammate to refactor the authentication module. Require plan approval before they make any changes.
(인증 모듈을 리팩터링할 건축가 팀원을 생성하세요. 변경 사항을 만들기 전에 계획 승인을 요구하세요.)

팀원이 계획을 완료하면, 리더에게 계획 승인 요청을 보냅니다. 리더는 계획을 검토하고 승인하거나 거부하며 피드백을 제공합니다.

위임 모드 사용

위임 모드가 없으면, 리더가 가끔 팀원이 작업을 완료하기를 기다리지 않고 직접 작업을 시작할 수 있습니다. 위임 모드는 리더를 조정 도구로만 제한하여 이를 방지합니다. Shift+Tab 을 눌러 위임 모드로 전환하세요.

팀원과 직접 대화하기

각 팀원은 완전하고 독립적인 Claude Code 세션입니다. 어떤 팀원에게도 직접 메시지를 보낼 수 있습니다:

• • 프로세스 내 모드: Shift+Up/Down을 사용하여 팀원을 선택한 다음, 입력하여 메시지를 보내세요. Enter를 눌러 팀원의 세션을 보고, Escape를 눌러 그들의 현재 차례를 중단하세요. Ctrl+T를 눌러 작업 목록을 전환하세요.

• • 분할 화면 모드: 팀원의 창을 클릭하여 직접 그 세션과 상호작용하세요.

업무 할당 및 인수

공유 작업 목록은 팀의 작업을 조정합니다. 리더가 작업을 생성하고, 팀원이 완료합니다. 작업에는 세 가지 상태가 있습니다: 대기 중, 진행 중, 완료됨. 작업은 다른 작업에 의존할 수도 있습니다.

리더는 명시적으로 작업을 할당하거나, 팀원이 작업을 완료한 후 자체적으로 작업을 인수할 수 있습니다.

팀원 종료하기

팀원의 세션을 우아하게 종료하려면:

Ask the researcher teammate to shut down
(연구원 팀원에게 종료하라고 요청하세요)

리더가 종료 요청을 보냅니다. 팀원은 승인하고 우아하게 종료하거나, 거부하고 이유를 설명할 수 있습니다.

팀 정리하기

완료 후, 리더에게 정리하라고 지시하세요:

Clean up the team
(팀을 정리하세요)

이렇게 하면 공유된 팀 리소스가 제거됩니다. 리더가 정리를 실행할 때, 활성 팀원을 확인하고 아직 실행 중인 팀원이 있으면 실패하므로, 먼저 그들을 종료해야 합니다.

Agent Teams 작동 방식

아키텍처

Agent Team은 다음을 포함합니다:

• • 리더: 팀을 생성하고, 팀원을 생성하며, 작업을 조정하는 주 Claude Code 세션

• • 팀원: 할당된 작업을 처리하는 독립적인 Claude Code 인스턴스

• • 작업 목록: 팀원이 인수하고 완료하는 작업 항목의 공유 목록

• • 메일박스: 에이전트 간 통신을 위한 메시지 시스템

시스템은 작업 의존성을 자동으로 관리합니다. 팀과 작업은 로컬에 저장됩니다:

• • 팀 구성: ~/.claude/teams/{team-name}/config.json

• • 작업 목록: ~/.claude/tasks/{team-name}/

컨텍스트 및 통신

각 팀원은 자신의 컨텍스트 창을 가집니다. 생성 시, 팀원은 일반 세션과 동일한 프로젝트 컨텍스트를 로드합니다: CLAUDE.md, MCP 서버 및 스킬. 리더의 대화 기록은 전달되지 않습니다.

팀원이 정보를 공유하는 방법:

• • 자동 메시징: 팀원이 메시지를 보낼 때, 자동으로 수신자에게 전달됨

• • 유휴 알림: 팀원이 완료하고 중지할 때, 자동으로 리더에게 알림

• • 공유 작업 목록: 모든 에이전트가 작업 상태를 보고 사용 가능한 작업을 인수할 수 있음

토큰 사용

Agent Teams는 단일 세션 사용보다 토큰 소비가 크게 증가합니다. 각 팀원은 자신의 컨텍스트 창을 가지며, 활성 팀원 수에 따라 토큰 사용량이 증가합니다. 연구, 검토 및 새로운 기능 작업의 경우, 추가 토큰은 일반적으로 가치가 있습니다. 일반 작업의 경우 단일 세션이 비용 효율적입니다.

사용 사례 예시

병렬 코드 검토 실행

단일 검토자는 한 번에 한 유형의 문제에 집중하는 경향이 있습니다. 검토 기준을 독립적인 영역으로 분할하면 보안, 성능 및 테스트 커버리지가 동시에 철저히 검토됩니다.

Create an agent team to review PR #142. Spawn three reviewers: one focused on security implications, one checking performance impact, one validating test coverage. Have them each review and report findings.
(PR #142를 검토하는 Agent Team을 생성하세요. 세 명의 검토자를 생성하세요: 한 명은 보안 영향에 집중, 한 명은 성능 영향 확인, 한 명은 테스트 커버리지 검증. 각자가 검토하고 발견 사항을 보고하도록 하세요.)

경쟁 가설로 조사하기

근본 원인이 불분명할 때, 단일 에이전트는 그럴듯한 설명을 찾으면 더 이상 찾지 않는 경향이 있습니다.

Users report the app exits after one message instead of staying connected. Spawn 5 agent teammates to investigate different hypotheses. Have them talk to each other to try to disprove each other's theories, like a scientific debate. Update the findings doc with whatever consensus emerges.

모범 사례

팀원에게 충분한 컨텍스트 제공

팀원은 자동으로 프로젝트 컨텍스트를 로드하지만, 리더의 대화 기록을 상속받지 않습니다. 생성 프롬프트에 작업별 세부 사항을 포함하세요.

작업 크기를 적절히 조정하기

• • 너무 작음: 조정 오버헤드가 이익을 초과함

• • 너무 큼: 팀원이 너무 오래 작업하여 확인 없이 진행되어 낭비된 노력의 위험 증가

• • 적절함: 자체 포함된 단위로, 명확한 결과물을 생성함

팀원이 완료할 때까지 기다리기

가끔 리더가 팀원이 작업을 완료하기를 ��다리지 않고 직접 작업을 시작할 수 있습니다. 이런 경우를 발견하면:

Wait for your teammates to complete their tasks before proceeding
(진행하기 전에 팀원들이 작업을 완료할 때까지 기다리세요)

파일 충돌 피하기

두 팀원이 동일한 파일을 편집하면 덮어쓰기가 발생할 수 있습니다. 작업을 분할하여 각 팀원이 다른 파일 집합을 담당하도록 하세요.

모니터링 및 안내

팀원의 진행 상황을 확인하고, 효과가 없는 방법을 재지향하며, 진행에 따라 발견을 종합하세요.

제한 사항

Agent Teams는 실험적입니다. 현재 제한 사항:

• • 프로세스 내 팀원은 세션 복구를 지원하지 않음: /resume 및 /rewind은 프로세스 내 팀원을 복구하지 않음

• • 작업 상태가 지연될 수 있음: 팀원이 가끔 작업 완료를 표시하지 못할 수 있음

• • 종료가 느릴 수 있음: 팀원은 종료 전 현재 요청을 완료함

• • 세션당 하나의 팀: 한 리더는 한 번에 하나의 팀만 관리할 수 있음

• • 중첩 팀 지원 안 함: 팀원은 자신의 팀을 생성할 수 없음

• • 리더 고정: 팀을 생성한 세션은 그 수명 동안 리더임

• • 분할 화면에는 tmux 또는 iTerm2 필요: VS Code 통합 터미널, Windows Terminal 또는 Ghostty 지원 안 함