claudekit / guides / agent-teams
[ Guide · Advanced · 15분 ]

에이전트 팀

published · updated

여러 Claude Code 인스턴스를 하나의 팀으로 묶어 작업을 분담하고 조율하는 실험 기능 사용법. in-process 모드와 iTerm2 + tmux 분할 창 셋업, 사용 사례, 알려진 제한까지 정리합니다.

에이전트 팀이란?

에이전트 팀(Agent Teams)은 여러 Claude Code 인스턴스를 하나의 팀으로 조율하는 모드입니다. 한 세션이 팀 리더 역할을 맡아 작업을 나누고 결과를 종합하며, 팀원들은 각자 독립된 컨텍스트 윈도우에서 작업하면서 서로 직접 메시지를 주고받습니다.

Claude Code 2.1.32 이상이 필요합니다(이 버전에서 research preview로 처음 추가). claude --version으로 확인하세요. 아래 설명은 2026년 10월(v2.1.314) 공식 문서 기준이며, 팀 정리 방식, 표시 모드 기본값, 조작 키 등이 초기 버전과 다릅니다. 에이전트 팀은 실험 기능이고 기본적으로 비활성화되어 있으며, 세션 재개, 작업 조율, 종료 동작에 알려진 제한이 있습니다.

리더를 거치지 않고 개별 팀원과 직접 대화할 수도 있다는 점이 subagent와의 가장 큰 차이입니다.

공식 문서: Claude Code 세션 팀 조율하기 — code.claude.com/docs/ko/agent-teams

subagent와 어떻게 다른가

항목subagent에이전트 팀
컨텍스트자체 컨텍스트 윈도우, 결과는 호출자에게 반환자체 컨텍스트 윈도우, 완전히 독립적
통신호출자에게 결과 반환팀원들이 서로 직접 메시지 전송
조율메인 에이전트가 모든 작업 관리메시지와 공유 작업 목록으로 자체 조율
최적 용도결과만 중요한 집중된 작업토론과 협업이 필요한 복잡한 작업
토큰 비용낮음 — 결과만 메인 컨텍스트로 요약높음 — 각 팀원이 별도 Claude 인스턴스

빠르고 집중된 워커가 필요할 때는 subagent를, 팀원들이 발견을 공유하고 서로 반박하며 자체적으로 조율해야 할 때는 에이전트 팀을 사용합니다.

활성화하기

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 환경 변수를 1로 설정합니다. 셸 환경 변수에 직접 추가하거나 ~/.claude/settings.json에서 설정할 수 있습니다.

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

활성화하면 일반 위임 동작도 달라집니다. Claude가 이름(name)을 붙여 생성한 subagent는 팀원으로 실행되므로, 팀을 요청하지 않았는데도 팀이 만들어질 수 있습니다. 또한 팀원 생성은 대화형 세션에서만 동작합니다. -p 플래그를 쓰는 비대화형 모드와 Agent SDK 세션에서는 팀원이 생성되지 않고 일반 subagent로 실행됩니다.

첫 팀 만들기

활성화 후, Claude에게 자연어로 팀 구조와 작업을 설명하면 됩니다. 별도의 팀 생성 단계는 없습니다. 2.1.178부터 세션마다 암묵적인 팀이 하나씩 있으며, 팀원을 바로 생성하면 됩니다. 다음 예시는 세 역할이 서로 기다리지 않고 독립적으로 탐색할 수 있어 잘 동작합니다.

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Spawn three teammates to explore this from different angles:
one on UX, one on technical architecture, one playing devil's advocate.

Claude가 팀 대신 subagent를 쓰는 경우도 있습니다. subagent도 같은 에이전트 패널에 나타나므로 패널만으로는 팀이 만들어졌는지 알 수 없습니다. 이럴 때는 에이전트 팀을 명시해 다시 요청합니다.

리더의 터미널에는 프롬프트 입력창 아래 에이전트 패널에 팀원 목록이 표시됩니다. 위/아래 화살표로 팀원을 선택하고 Enter로 해당 팀원의 트랜스크립트를 열어 직접 메시지를 보냅니다.

팀이 쓰던 공유 디렉터리는 세션이 끝나면 자동으로 정리되므로 별도의 정리 단계가 필요 없습니다.

표시 모드 — in-process vs 분할 창

에이전트 팀은 두 가지 표시 모드를 지원합니다.

  • in-process — 모든 팀원이 메인 터미널 안에서 실행됩니다. 에이전트 패널에서 위/아래 화살표로 팀원을 선택하고 Enter로 연 뒤 입력해서 메시지를 보냅니다. 어떤 터미널에서도 동작하며 추가 설정이 필요 없습니다.
  • 분할 창(split panes) — 각 팀원이 별도 창을 가집니다. 모든 팀원의 출력을 한눈에 보고, 창을 클릭해 직접 상호작용할 수 있습니다. tmux 또는 iTerm2가 필요합니다.

기본값은 "in-process"입니다. 설정 가능한 값은 다음과 같습니다.

  • "auto" — 이미 tmux 세션 안이거나, iTerm2에서 it2 CLI가 설치된 경우(또는 tmux가 설치된 경우) 분할 창을 쓰고, 아니면 in-process로 동작합니다.
  • "tmux" — 분할 창 모드를 켜고 터미널에 따라 tmux 또는 iTerm2를 자동 감지합니다.
  • "iterm2" — it2 CLI로 iTerm2 네이티브 분할 창을 명시적으로 사용합니다(2.1.186에서 추가). it2가 없으면 설치 명령과 함께 오류를 표시합니다.

~/.claude/settings.json에서 기본값을 재정의합니다.

{
  "teammateMode": "auto"
}

단일 세션에서만 모드를 바꾸려면 플래그로 전달합니다. 이 플래그는 실험 기능이라 claude --help에는 나타나지 않습니다.

claude --teammate-mode auto

분할 창 모드는 tmux 또는 it2 CLI가 설치된 iTerm2가 필요합니다. 분할 창은 VS Code 통합 터미널, Windows Terminal, Ghostty에서는 지원되지 않습니다.

iTerm2 + tmux 셋업 (가장 간단한 조합)

분할 창은 tmux 단독 또는 iTerm2 + it2 CLI 두 가지 경로 중 하나만 충족하면 됩니다. 둘을 같이 설치할 필요가 없습니다. 공식 문서는 iTerm2 안에서 tmux -CC로 tmux 컨트롤 모드를 띄우는 방식을 tmux 진입 경로로 권장하며, 이 경로에서는 it2 CLI나 iTerm2 Python API 설정이 필요하지 않습니다. tmux는 운영체제마다 동작 차이가 있고 전통적으로 macOS에서 가장 잘 동작합니다.

1. tmux 설치

brew install tmux

설치 후 PATH에서 동작하는지 확인합니다.

which tmux

2. teammateMode 설정

기본값 "in-process"에서는 tmux 안에서도 분할 창이 열리지 않습니다. ~/.claude/settings.json에 "teammateMode": "auto" 또는 "tmux"를 설정합니다.

{
  "teammateMode": "tmux"
}

3. iTerm2에서 tmux -CC로 진입

iTerm2를 새로 띄운 뒤 tmux -CC로 tmux 컨트롤 모드 세션을 시작합니다.

tmux -CC

iTerm2가 tmux 세션을 네이티브 창과 탭으로 표시합니다. 이 상태에서 Claude Code를 실행합니다.

4. 동작 확인

에이전트 팀을 만들어 보면 각 팀원이 별도의 iTerm2 창으로 분리되어 열리는 것을 확인할 수 있습니다. 분할 창이 안 열리면 teammateMode 값과, which tmux로 tmux가 PATH에 있는지 확인합니다.

iTerm2에서 tmux -CC로 진입한 뒤 에이전트 팀 팀원들이 각각 별도의 분할 창으로 열린 모습

tmux 없이 iTerm2만 쓰는 경우

tmux를 설치하고 싶지 않다면 iTerm2의 Python API를 통해 분할 창을 띄우는 별도 경로가 있습니다. 이 경우에만 it2 CLI 설치와 Python API 활성화가 필요하며, teammateMode는 "iterm2" 또는 "auto"로 설정합니다.

  1. iTerm2 메뉴에서 Settings → General → Magic → Enable Python API를 활성화

  2. it2 CLI 설치 — uv 또는 pip 중 편한 쪽 사용

    uv tool install it2

    uv가 없다면 pip install it2로 대체할 수 있습니다. it2는 macOS에서 iTerm2 3.3.0 이상과 Python 3.10 이상을 요구합니다.

대부분의 경우 위의 tmux + tmux -CC 방식이 더 단순하므로 이쪽을 먼저 시도하는 것을 권장합니다.

in-process 모드 단축키

분할 창 없이 메인 터미널 안에서만 사용할 때 알아두면 좋은 에이전트 패널 단축키입니다.

단축키동작
위/아래 화살표팀원 선택
Enter선택한 팀원의 트랜스크립트를 열고 직접 메시지 전송
Escape선택 해제. 팀원 트랜스크립트를 보는 중이면 그 팀원의 현재 턴 중단
x선택한 팀원 중지
Ctrl+T작업 목록 토글

유휴 상태인 팀원은 패널의 모든 에이전트가 유휴가 된 지 30초 후 목록에서 숨겨지지만, 계속 실행 중이며 이름으로 메시지를 보낼 수 있습니다. 유휴 팀원이 셋을 넘으면 나머지는 N idle agents 한 줄로 접히고 Enter로 펼칩니다.

팀 제어하기

리더에게 자연어로 지시하면 팀 조율, 작업 할당, 위임을 알아서 처리합니다.

팀원 수와 모델 지정

Claude가 작업에 따라 팀원 수를 자동으로 결정하지만, 직접 지정할 수도 있습니다.

Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.

팀원의 모델은 다음 중 먼저 해당하는 것으로 정해집니다.

  1. 생성 프롬프트에서 그 팀원에게 지정한 모델
  2. subagent 정의로 생성한 팀원이면 정의의 model (inherit이면 리더 모델)
  3. inherit 이외 값으로 설정된 CLAUDE_CODE_SUBAGENT_MODEL
  4. 리더의 현재 모델

예전의 teammateDefaultModel 설정은 2.1.234에서 제거되어 남아 있어도 무시됩니다. 모델은 프롬프트에서 지정합니다. 팀원의 모델과 fast mode는 생성 시점에 고정됩니다.

계획 먼저 세우게 하기

복잡하거나 위험한 작업은 팀원이 구현 전에 계획을 세우게 할 수 있습니다. 리더가 plan mode에 있는 동안 생성된 팀원은 계획이 준비될 때까지 읽기 전용 plan mode에서 동작합니다. 먼저 리더를 plan mode로 전환한 뒤 팀원을 요청합니다.

Spawn an architect teammate to refactor the authentication module.

계획을 마친 팀원은 리더에게 계획 승인 요청을 보냅니다. 생성 이후 그 팀원의 권한 모드를 바꾸지 않았다면, Claude Code가 요청이 도착하는 즉시 계획을 자동 승인합니다. 리더가 검토하지 않으므로, 계획 승인에 판단 기준을 걸어두는 용도로는 쓸 수 없습니다. 승인 후에도 팀원의 편집과 명령은 평소와 같이 권한 프롬프트를 거칩니다.

실행 중인 in-process 팀원의 세션을 보면서 Shift+Tab으로 그 팀원을 plan mode로 바꾸면, 그 실행의 계획은 자동 승인 대신 리더가 검토해 승인하거나 수정을 요청합니다.

팀원과 직접 대화

각 팀원은 완전히 독립된 Claude Code 세션입니다. 추가 지시를 주거나 후속 질문을 하거나 접근을 재지정할 때 직접 메시지를 보냅니다.

  • in-process — 에이전트 패널에서 위/아래 화살표로 선택하고 Enter로 세션을 연 뒤 입력. x로 팀원 중지, Ctrl+T로 작업 목록 토글
  • 분할 창 — 팀원의 창을 클릭해 직접 상호작용. 각 팀원은 자기 터미널의 전체 보기를 가짐

in-process 팀원의 화면을 보는 동안 일반 텍스트와 skill은 그 팀원에게 전달되고, 빌트인 명령은 리더 세션으로 갑니다. /compact, /clear, /rewind는 리더 대화에 적용되므로 실행 전에 확인을 묻고, /model과 /fast는 이 화면에서 실행되지 않습니다.

작업 할당과 자체 요청

공유 작업 목록이 팀 전체 작업을 조율합니다. 작업은 대기 중 / 진행 중 / 완료 세 상태를 가지고 다른 작업에 의존할 수 있습니다. 의존 작업이 끝나지 않은 작업은 목록에 차단됨으로 표시되며, 팀원이 스스로 가져가지는 않지만 사용자나 리더가 할당할 수는 있습니다. 의존 작업이 완료되면 차단은 자동으로 풀립니다.

  • 리더 할당 — 리더에게 어느 작업을 어느 팀원에게 줄지 명시
  • 자체 요청 — 작업을 마친 팀원이 다음 미할당, 미차단 작업을 스스로 선택

작업 요청에는 파일 잠금이 적용되어 여러 팀원이 동시에 같은 작업을 가져가는 경합을 막습니다.

팀원 종료와 팀 정리

팀원 세션을 우아하게 종료하려면 이름으로 지정합니다.

Ask the researcher teammate to shut down

리더가 종료 요청을 보내면 팀원은 승인하고 종료하거나 사유와 함께 거부할 수 있습니다.

팀 정리를 따로 요청할 필요는 없습니다. 2.1.178에서 TeamCreate, TeamDelete 도구가 제거되었고, 팀의 공유 디렉터리는 세션이 끝날 때 자동으로 정리됩니다. 어떤 디렉터리가 지워지고 남는지는 아래 “작동 원리”를 참고합니다.

작동 원리

에이전트 팀은 다음 네 가지 구성 요소로 이루어집니다.

구성 요소역할
팀 리더팀원을 생성하고 작업을 조율하는 메인 Claude Code 세션
팀원할당된 작업을 처리하는 별도의 Claude Code 인스턴스
작업 목록팀원이 요청하고 완료하는 공유 작업 항목 목록
메일박스에이전트 간 메시징 시스템

팀과 작업은 세션에서 파생된 이름(session- + 세션 ID 앞 8자)으로 로컬에 저장됩니다.

  • 팀 구성: ~/.claude/teams/{team-name}/config.json — 세션이 끝나면 삭제됩니다.
  • 작업 목록: ~/.claude/tasks/{team-name}/ — 세션이 끝나도 남으며, 보관 기간은 cleanupPeriodDays로 조정합니다.

팀 구성은 세션 ID와 tmux 창 ID 같은 런타임 상태를 보유하므로 수동으로 편집하거나 사전 작성하지 않습니다 — 다음 상태 업데이트에서 덮어써집니다. 재사용할 팀원 역할은 아래의 subagent 정의로 만듭니다.

각 팀원은 자기 컨텍스트 윈도우에서 동작합니다. 생성 시 일반 세션과 동일하게 CLAUDE.md, MCP server, skill을 로드하지만 리더의 대화 기록은 전달되지 않습니다. 작업별 세부 정보는 생성 프롬프트에 명시적으로 포함해야 합니다.

subagent 정의를 팀원으로 재사용

팀원을 생성할 때 프로젝트, 사용자, managed, 플러그인 범위의 subagent 유형을 이름으로 참조할 수 있습니다. 한 번 정의한 역할(security-reviewer, test-runner 등)을 위임된 subagent와 팀원 양쪽에서 재사용하기 위함입니다.

Spawn a teammate using the security-reviewer agent type to audit the auth module.

정의의 각 부분은 팀원의 표시 모드에 따라 다르게 적용됩니다.

  • tools, model — 두 모드 모두 적용됩니다. in-process 팀원에게는 SendMessage와 작업 관리 도구가 자동으로 추가됩니다.
  • 본문 — in-process 팀원은 기본 시스템 프롬프트에 추가 지시로 덧붙이고, 분할 창 팀원은 기본 시스템 프롬프트를 본문으로 대체합니다.
  • skills — 두 모드 모두 적용되지 않습니다. 팀원은 프로젝트와 사용자 설정에서 skill을 로드합니다.
  • mcpServers — 분할 창 팀원에게는 적용되고, in-process 팀원은 무시하고 프로젝트와 사용자 설정의 MCP server를 로드합니다.

subagent 정의에만 묶어둔 skill은 팀원에서 동작하지 않고, MCP server는 in-process 팀원에서 동작하지 않으니 주의합니다.

추천 사용 사례

병렬 코드 리뷰

단일 리뷰어는 한 번에 한 가지 유형의 문제로 기우는 경향이 있습니다. 리뷰 기준을 독립 도메인으로 분할해 보안, 성능, 테스트 커버리지가 동시에 충분히 검토되도록 합니다.

Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

경쟁 가설 디버깅

원인이 불명확할 때 단일 에이전트는 그럴듯한 설명 하나에 머물기 쉽습니다. 팀원을 명시적으로 적대적으로 만들면 서로의 이론을 반박하면서 진짜 원인에 수렴합니다.

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.

순차 조사는 한 이론이 먼저 탐색되면 후속 조사가 그쪽으로 편향되는 앵커링에 취약합니다. 여러 독립 조사자가 적극적으로 서로를 반박할 때 살아남는 이론이 실제 근본 원인일 가능성이 훨씬 높습니다.

hooks로 품질 게이트

팀원 작업 종료, 작업 생성과 완료 시점에 규칙을 강제할 때 hooks를 사용합니다. 종료 코드 2로 종료하면 피드백을 보내고 동작을 차단합니다.

Hook시점종료 코드 2의 효과
TeammateIdle팀원이 유휴 상태로 들어가려 할 때피드백을 보내고 팀원을 계속 작업하게 함
TaskCreated작업이 생성될 때생성을 차단하고 피드백 전달
TaskCompleted작업이 완료로 표시될 때완료를 차단하고 피드백 전달

모범 사례

  • 충분한 컨텍스트 제공 — 팀원은 CLAUDE.md, MCP, skill을 자동으로 로드하지만 리더의 대화 기록은 상속하지 않습니다. 생성 프롬프트에 작업별 세부 정보(파일 경로, 사용 라이브러리, 보고 형식)를 명시합니다.
  • 3-5명 팀 크기에서 시작 — 토큰 비용이 선형으로 증가하고 조율 오버헤드가 커집니다. 팀원당 5-6개 작업을 유지합니다.
  • 작업을 적정 크기로 — 너무 작으면 조율 비용이 이득을 넘고, 너무 크면 체크인 없이 너무 오래 작업해 낭비 위험이 커집니다. 함수, 테스트 파일, 검토처럼 자체 완결된 단위가 적당합니다.
  • 파일 충돌 회피 — 두 팀원이 같은 파일을 편집하면 덮어쓰기가 발생합니다. 각 팀원이 다른 파일 집합을 소유하도록 작업을 나눕니다.
  • 모니터링과 조율 — 팀을 무인으로 너무 오래 돌리지 않습니다. 작동하지 않는 접근은 재지정하고, 결과가 들어올 때마다 종합합니다.
  • 연구와 검토 작업으로 시작 — 처음이라면 PR 리뷰, 라이브러리 조사, 버그 조사처럼 코드 작성이 필요 없는 작업으로 시작해 병렬 탐색의 가치를 먼저 체감합니다.

알려진 제한

에이전트 팀은 실험 기능입니다. 다음 제한을 알아두세요.

  • in-process 팀원의 세션 재개 미지원 — /resume과 /rewind는 in-process 팀원을 복원하지 않습니다. 재개 후 리더가 더 이상 존재하지 않는 팀원에게 메시지를 보내려고 할 수 있습니다. 이 경우 새 팀원 생성을 지시합니다.
  • 작업 상태 지연 가능성 — 팀원이 작업을 완료로 표시하지 못해 의존 작업이 막힐 수 있습니다. 막힌 듯하면 실제 작업 완료 여부를 확인하고 수동으로 상태를 업데이트하거나 리더에게 팀원을 재촉하라고 지시합니다.
  • 종료가 느릴 수 있음 — 팀원은 현재 요청이나 도구 호출을 마친 뒤 종료됩니다.
  • 세션당 한 팀 — 세션에는 그 세션 범위의 팀이 정확히 하나 있습니다. 이름 붙인 팀을 추가로 만들거나 여러 세션이 팀을 공유할 수 없습니다.
  • 중첩 팀 불가 — 팀원은 자기 팀이나 팀원을 생성할 수 없습니다. 리더만 팀을 관리합니다.
  • in-process 팀원의 백그라운드 subagent 불가 — in-process 팀원이 띄운 subagent는 포그라운드로 실행됩니다. 정의에 background: true가 있는 subagent를 생성하면 오류가 납니다.
  • 리더 고정 — 메인 세션이 수명 동안 리더입니다. 팀원을 리더로 승격하거나 리더십을 이전할 수 없습니다.
  • 권한은 생성 시 고정 — 팀원은 리더의 권한 모드로 시작합니다. 단 dontAsk 모드는 상속되지 않습니다. 생성 후 개별 팀원 모드를 바꿀 수는 있지만 생성 시점에 팀원별로 다르게 설정할 수는 없습니다.
  • 분할 창은 tmux 또는 iTerm2 한정 — 기본 in-process는 어디서나 동작합니다. 분할 창은 VS Code 통합 터미널, Windows Terminal, Ghostty에서 지원되지 않습니다.

문제 해결

팀원이 보이지 않을 때

  • in-process 모드에서 팀원은 프롬프트 입력창 아래 에이전트 패널에 나타납니다. 위/아래 화살표로 선택하고 Enter로 엽니다.

  • 유휴 상태로 있다가 사라진 팀원은 중지된 것이 아니라 숨겨진 것입니다. 이름으로 메시지를 보내면 다시 나타납니다.

  • Claude가 작업이 팀을 보증할 만큼 복잡하지 않다고 판단했을 수 있습니다. 작업 설명을 구체화합니다.

  • 분할 창을 명시 요청했다면 teammateMode가 "in-process"가 아닌지, tmux가 PATH에 있는지 확인합니다.

    which tmux
  • tmux 없이 iTerm2 단독 모드로 쓰고 있다면 it2 CLI 설치와 Python API 활성화 여부를 확인합니다.

subagent 대신 팀원이 생성될 때

팀 기능이 켜져 있으면 Claude가 이름을 붙인 subagent는 팀원으로 실행됩니다. subagent로 되돌리려면 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS를 0으로 설정합니다. settings 파일의 env 값은 저장하면 실행 중인 세션에 다시 적용되므로 새 세션을 시작할 필요가 없습니다. 다만 프로젝트, 로컬, managed 설정에서 1로 켜두었다면 그쪽이 우선합니다.

권한 프롬프트가 너무 많을 때

팀원의 권한 요청은 모두 리더로 올라옵니다. 팀을 생성하기 전에 권한 설정에서 자주 쓰는 동작을 사전 승인해 중단을 줄입니다.

팀원이 오류로 멈췄을 때

팀원은 오류를 만나면 복구하지 않고 멈출 수 있습니다. 출력을 확인한 뒤 직접 추가 지시를 주거나 대체 팀원을 생성합니다.

고아 tmux 세션

Claude Code 세션이 끝났는데 tmux 세션이 남아 있다면 정리가 완전히 되지 않은 것입니다. 세션을 나열하고 팀이 만든 세션을 종료합니다.

tmux ls
tmux kill-session -t <session-name>

다음 단계

§ 14

자주 묻는 질문

자주 묻는 질문
§ 14.1
에이전트 팀과 subagent의 차이는 무엇인가요?
subagent는 메인 세션 안에서 작업을 수행하고 결과를 호출한 에이전트에게 돌려줍니다. 에이전트 팀은 각 팀원이 독립된 Claude Code 인스턴스로 동작하며 메일박스로 서로 직접 메시지를 주고받고, 공유 작업 목록으로 일을 나눕니다. 토론과 협업이 필요한 복잡한 작업이면 팀, 결과만 받으면 되는 집중된 작업이면 subagent가 적합합니다.
§ 14.2
에이전트 팀은 어떻게 활성화하나요?
Claude Code 2.1.32 이상이 필요하며, 환경 변수 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`로 활성화합니다. 셸 환경 변수로 설정하거나 `~/.claude/settings.json`의 `env` 객체에 키를 추가합니다. 활성화하면 Claude가 이름을 붙인 subagent도 팀원으로 실행되므로, 요청하지 않아도 팀이 생길 수 있습니다.
§ 14.3
iTerm2 + tmux 분할 창 모드는 어떻게 설정하나요?
`brew install tmux`로 tmux를 설치하고 iTerm2에서 `tmux -CC`로 진입한 뒤, `~/.claude/settings.json`에 `"teammateMode": "auto"`(또는 `"tmux"`)를 설정합니다. 기본값이 `"in-process"`이므로 이 설정이 없으면 tmux 안에서도 분할 창이 열리지 않습니다. it2 CLI와 Python API 활성화는 tmux 없이 iTerm2 단독으로 쓸 때만 필요합니다.
§ 14.4
팀원은 몇 명이 적당한가요?
대부분의 워크플로에서 3-5명으로 시작하는 것이 좋습니다. 팀원당 5-6개의 작업을 유지하면 모두 생산적으로 일할 수 있고, 누군가 막혔을 때 리더가 작업을 재배정할 여유도 생깁니다. 팀원이 늘수록 토큰 비용이 선형으로 증가하고 조율 오버헤드도 커지므로, 작업이 실제로 동시 진행에서 이득을 볼 때만 확장합니다.
§ 14.5
어떤 작업에 가장 효과적인가요?
병렬 탐색이 가치를 더하는 작업에 강합니다. 여러 각도에서 동시에 살펴봐야 하는 연구와 검토, 서로 다른 모듈을 동시에 만드는 신규 기능 개발, 경쟁하는 가설을 함께 검증하는 디버깅, 프론트엔드와 백엔드와 테스트가 얽힌 교차 계층 변경이 대표적입니다.