Claude Code Agent Teams: 멀티 세션 가이드 (2026)

- 이것은 리서치 프리뷰 기능이며, 활성화 방식은 이미 한 번 바뀌었습니다(v2.1.178 전후로, 수동으로 팀을 생성하는 도구는 더 이상 존재하지 않습니다). 여기의 내용은 작성 시점(2026년 8월)의 공식 문서와 대조 확인했습니다 - 이에 의존하기 전에 반드시 최신 문서를 확인하세요.

agent teams란 실제로 무엇인가

agent teams는 Claude Code의 리서치 프리뷰 기능으로, 하나의 "팀" 안에서 여러 세션을 병렬로 실행할 수 있게 해줍니다. 리드 에이전트가 조율하고, 하나 이상의 teammate가 작업을 수행합니다. 각 teammate는 자체 컨텍스트 창을 가지며 - 리드나 다른 teammate와 컨텍스트를 공유하지 않습니다 - 팀 전체가 하나의 작업 목록과 직접 메시징 채널(메일박스)을 공유합니다. 공식 문서 code.claude.com/docs/en/agent-teams(2026년 8월 확인)에 따르면, 이는 독립적인 Claude Code 세션 위에 얹히는 조율 계층이며 - 새로운 모델도, 별도의 API도 아닙니다.

혼동을 피하기 위해 한마디: agent teams는 AgentKit의 "advisor"나 "kongming" 페르소나가 아닙니다 - 이들은 완전히 다르게 동작합니다(끝부분의 솔직한 평가 참조).

agent teams와 subagents 비교

이미 Claude Code subagents에 익숙하다면, 문서에서 가져온 직접 비교(요약)는 다음과 같습니다:

간단히 말하면, subagent는 "작업을 위임하고 결과를 돌려받는" 것이고, agent teams는 "그룹이 함께 일하며 서로 직접 메시지를 주고받는" 것입니다. subagent 오케스트레이션을 더 크게 확장하려면 subagent를 대규모로 오케스트레이션하는 방법을 참고하세요.

누가 계획을 쥐고 있는가: subagents / skills / agent teams / workflows

이것이 이 글의 핵심 정보 가치입니다 - Claude Code 문서(code.claude.com/docs/en/workflows, 2026년 8월 확인)에서 직접 가져온 4자 비교로, 우리가 확인한 경쟁 글들은 EN이든 VI든 이를 온전한 형태로 재현하지 못합니다:

우리가 확인한 경쟁 글 중 어느 것도 이 정확한 4자 틀을 재현하지 못합니다 - 대부분은 agent teams를 subagents와만 비교하고 skills와 workflows는 완전히 건너뜁니다. workflows/ultracode에 대한 자세한 심층 분석은 Claude Code Dynamic Workflows를 참고하세요.

agent teams 활성화하기 - CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

agent teams는 기본적으로 비활성화되어 있습니다. settings.json에서 환경 변수를 지정해 켭니다:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "true"
  }
}

기억해 둘 만한 몇 가지(문서 기준, 2026년 8월 확인 - 이에 의존하기 전에 실제로 실행 중인 Claude Code 버전에서 확인하세요):

• 인터랙티브 세션에서만 동작합니다 - -p나 Agent SDK를 통해서는 실행되지 않습니다.
• 현재 설정(v2.1.178 이후)에서는, 일부 오래된 글에서 설명하는 것처럼 TeamCreate/TeamDelete 도구를 수동으로 호출할 필요가 없습니다 - 그 도구들은 현재 흐름에 더 이상 존재하지 않습니다. 수동 팀 생성 단계를 설명하는 가이드를 본다면, 그것은 이 변경 이전에 작성되었을 가능성이 큽니다 - Anthropic 스스로가 하는 "바뀔 수 있다"는 경고의 구체적인 예입니다.

첫 팀 시작하기, 그리고 공유 작업 목록

활성화한 뒤에는, 여러 관점으로 나눠 다룰 만큼 큰 작업으로 시작하세요. 예를 들어:

Spawn a team of 3 teammates to review this PR:
one for security, one for performance, one for test coverage.
Report findings back to me.

Claude Code는 팀 전체를 위한 공유 작업 목록을 만듭니다. 익숙한 상태를 가집니다: pending, in progress, completed. 알아둘 만한 몇 가지 메커니즘:

• 의존성 차단 - 작업은 다른 작업이 끝날 때까지 기다렸다가 시작할 수 있습니다.
• 자체 가져오기 또는 리드 배정 - teammate는 pending 작업을 스스로 가져가거나, 리드가 직접 배정할 수 있습니다.
• 가져올 때 파일 잠금 - teammate가 특정 파일을 건드리는 작업을 가져가면, 잠금이 두 teammate가 같은 위치를 동시에 편집하지 못하게 막습니다.

cross-session messaging - 팀이 아닌 별개의 기능

여기서 대부분의 경쟁자(EN·VI)가 경계를 흐리며 이를 "팀 메시징"으로 취급합니다. 문서는 실제로 이를 별개의 기능으로 다룹니다: cross-session messaging은 두 개의 독립적인 Claude Code 세션 - 다른 머신에서든, 아니면 Remote Control을 통해서든 - 이 둘 다 같은 Claude 감독 팀에 속하지 않고도 ListAgents/SendMessage(또는 /list-agents 명령)를 통해 메시지를 주고받을 수 있게 해줍니다.

어느 것을 쓸지: Claude가 직접 하나의 공유 작업 목록을 통해 그룹을 조율하게 하려면 agent teams를 쓰세요. 직접 조종하는 독립 세션이 몇 개 있고 필요할 때 메시지만 주고받게 하고 싶다면, cross-session messaging이 알맞은 더 가벼운 도구입니다 - 그것 때문에 완전한 팀 메커니즘을 켤 필요는 없습니다.

플랫폼 참고: cross-session messaging은 현재 macOS/Linux에서만 동작합니다 - 아직 네이티브 Windows 지원은 없습니다. WSL2는 Linux로 취급되므로 거기서는 동작합니다. 팀의 분할 창 표시 모드에도 tmux나 iTerm2가 필요하며, Windows Terminal에서는 명시적으로 동작하지 않습니다. 경쟁자(EN·VI) 중 이를 언급한 곳은 하나도 보지 못했습니다 - 이 사이트 독자 중 Windows에서 작업하는 개발 머신이 많다는 점을 고려하면 짚어둘 가치가 있습니다.

agent view - 병렬 백그라운드 세션을 위한 대시보드

관련되어 있고 혼동하기 쉬운 기능: agent view는 claude agents로 엽니다. 병렬로 실행되는 백그라운드 세션을 나열하는 대시보드로 - agent teams와 달리 세션 간 메시징이 없습니다. 순전히 모니터링 화면입니다. 이것도 리서치 프리뷰입니다.

흔한 혼동을 바로잡을 가치가 있습니다: 세션마다 전용 git worktree를 통한 격리는 agent view의 메커니즘(백그라운드 세션용)이며, agent teams의 기본 동작이 아닙니다. 일부 글은 agent teams가 teammate마다 별도의 worktree를 자동 생성해 일종의 "평행 우주"처럼 만든다고 설명합니다 - 그러나 agent teams 아키텍처 문서에는 그런 메커니즘이 기술되어 있지 않고, 리드/teammate/작업 목록/메일박스만 설명하며 자동 worktree에 대한 언급은 없습니다.

현실적인 사용 사례: 병렬 PR 리뷰

공식 문서에서 가장 강력한 사용 사례(그리고 제가 실제로 손이 가는 것)는 병렬 PR 리뷰입니다: teammate 3명을 띄우고, 각자 같은 PR을 서로 다른 관점 - 보안, 성능, 테스트 커버리지 - 으로 읽은 뒤 여러분에게 보고합니다. 각 teammate는 자체 컨텍스트를 가지므로, 같은 diff를 읽어도 서로 방해하지 않습니다.

솔직히 말하면: 이 안내는 Anthropic이 직접 문서화한 사용 사례를 본뜬 것으로, 구체적인 수치(문제 개수, PR 개수)를 동반한 실제 실행이 아닙니다. "Y분 만에 X개 문제 발견" 같은 정확한 수치를 인용하는 다른 리뷰를 본다면, 실제로 실행한 것인지 아니면 문서를 바꿔 말하는 것뿐인지 물어볼 가치가 있습니다. 시도해 볼 만한 또 다른 패턴: 어려운 버그를 여러 teammate에게 주어 서로 경쟁하는 가설로 작업하게 하고, 리드가 어느 가설이 증거에 가장 잘 맞는지 종합하게 하는 것입니다.

두 패턴 모두 하위 작업이 진정으로 별도의 컨텍스트에서 이득을 볼 때만 효과가 있습니다 - 같은 diff를 서로 다른 관점으로 읽거나, 한 teammate의 가정이 다른 teammate를 오염시키지 않게 서로 다른 근본 원인 이론을 추적하는 경우입니다. 대부분 순차적인 작업(구현한 다음 테스트, 그다음 문서화)에는 팀을 통째로 세우는 것보다 평범한 subagent 체인이 대개 더 저렴하고 추론하기도 쉽습니다.

제한 사항 - 아직 되지 않는 것

이것은 리서치 프리뷰이므로, 문서는 현재의 제한을 솔직하게 나열합니다 - 중요한 워크플로를 이 기능에 걸기 전에 읽어둘 가치가 있습니다:

• 실행 중인 teammate 재개 불가 - 터미널을 닫은 뒤에는 재개할 수 없으며, 세션을 닫으면 그 teammate는 사라집니다.
• 작업 상태 지연 - 작업 목록이 teammate가 지금 하는 일을 항상 실시간으로 반영하지는 않습니다.
• 세션당 팀 하나 - 하나의 리드 세션 아래에서 여러 팀을 병렬로 실행할 수 없습니다.
• 중첩 팀 불가 - teammate는 자신의 하위 팀을 띄울 수 없습니다.
• 분할 창에는 tmux/iTerm2가 필요하며, Windows Terminal에서는 동작하지 않습니다(cross-session messaging과 같은 주의사항).

이것이 이 글이 "리서치 프리뷰"를 계속 강조하는 이유이기도 합니다: 활성화 방식은 이미 한 번 바뀌었고(수동 팀 생성 도구 단계가 삭제됨), 이 제한 목록도 바뀔 여지가 충분합니다. 여기 설명된 정확한 세부 사항이나 동작에, 다시 확인하지 않은 채로 프로덕션에 필수적인 워크플로를 고정하지 마세요.

솔직한 AgentKit 관점: 그 페르소나가 teammate가 될 수 있을까

직접적인 질문: AgentKit의 advisor와 kongming이 agent team 안에서 teammate로 동작할 수 있을까요? 아니요, 지속적인 teammate로는 안 됩니다.

• kongming은 원샷입니다: 프롬프트 하나를 넣으면 답 하나가 나오고, 양방향 주고받기가 없습니다.
• advisor는 인터뷰 릴레이형입니다: 질문을 한 번에 하나씩 하고 그 사이에 메인 세션으로 돌아옵니다 - 병렬로 실행되며 메일박스를 통해 메시지하는 독립 세션이 아닙니다.

둘 다 teammate에게 필요한 지속적이고 다중 턴의 메시징을 위해 만들어지지 않았습니다(docs.agentkit.best/en/beta/concepts/advisory-supervision, 2026년 8월 확인).

다만, 얼버무리지 않고 분명히 말할 가치가 있는 진짜 뉘앙스가 있습니다: Claude Code에서는 프로젝트/사용자/플러그인 수준에서 정의된 임의의 에이전트 타입을 사용해 teammate를 띄울 수 있습니다 - 그리고 AgentKit의 런타임 어댑터는 키트의 에이전트를 네이티브 Claude Code subagent 정의로 설치합니다. 그러므로 기술적으로는 AgentKit 키트의 작업 실행 에이전트(advisor/kongming이 아님)를 teammate로 지정할 수 있습니다. 그것이 "AgentKit이 기성 팀을 제공한다"는 것과 같지는 않습니다 - 경계를 분명히 말해두겠습니다: AgentKit은 작업을 위임할 페르소나/skill을 주는 유료 키트이고, agent teams는 여러분이 직접 그것들을 끼워 넣는 Claude Code의 무료 조율 메커니즘입니다 - AgentKit이 패키징한 "팀" 제품이 아닙니다. 자세한 내용은 AgentKit 전체 리뷰를 참고하세요.

자주 묻는 질문(FAQ)

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS는 무엇을 하나요?

이것은 (settings.json에서 설정하는) 환경 변수로, Claude Code의 agent teams 기능을 활성화합니다. 아직 리서치 프리뷰이므로 기본적으로 비활성화되어 있습니다. 인터랙티브 세션에서만 동작하며, -p나 Agent SDK를 통해서는 동작하지 않습니다.

agent teams는 subagents와 어떻게 다른가요?

subagent는 호출한 세션의 컨텍스트 안에서 동작하고, 작업을 받아 결과를 반환하며, 양방향 메시징이 없습니다. agent teams는 여러 독립 세션(각 teammate가 자체 컨텍스트를 가짐)이 관여해 작업 목록을 공유하고, 실행 중에 메일박스를 통해 직접 메시지를 주고받습니다 - 토큰 비용이 눈에 띄게 높습니다.

cross-session messaging은 Windows에서 동작하나요?

아직 네이티브로는 동작하지 않습니다 - 현재는 macOS/Linux에서만 동작합니다. WSL2는 Linux로 취급되므로 거기서는 동작합니다. 팀의 분할 창 표시 모드에도 tmux나 iTerm2가 필요하며, Windows Terminal에서는 동작하지 않습니다.

팀의 토큰 비용은 단일 세션과 비교해 어떤가요?

눈에 띄게 높습니다. 각 teammate가 메인 세션과 컨텍스트를 공유하지 않고 병렬로 실행되는 완전한 세션이기 때문입니다. 문서는 고정된 수치를 제시하지 않습니다 - 하나의 에이전트가 순차적으로 작업하면 될 때가 아니라, 진짜로 병렬 관점이 필요할 때만 이것을 쓰세요.

터미널을 닫은 뒤 팀을 재개할 수 있나요?

아직 안 됩니다. 현재 제한에 따르면, 실행 중인 teammate는 세션을 닫은 뒤 재개할 수 없으며 - 터미널을 닫으면 그 teammate는 사라집니다. 이는 문서가 스스로 솔직하게 나열하는 제한 중 하나입니다.

이 기능은 일상 업무에 쓸 만큼 안정적인가요?

그다지 아닙니다 - 아직 리서치 프리뷰이고, 활성화 방식은 이미 한 번 바뀌었습니다(수동 팀 생성 도구 단계 삭제). 중요하지 않은 병렬 탐색에서 시도하는 것은 괜찮습니다. 다만 아직 필요한 안정성이 많이 남아 있는 점을 감안하면, 필수적인 일상 워크플로를 구축할 대상으로는 아직 적합하지 않습니다.

결론

agent teams는 아직 리서치 프리뷰입니다 - 병렬 탐색(하나의 문제에 대한 여러 관점 동시 검토)에는 강력하지만, subagent나 skill이 이미 처리하는 더 단순한 순차 작업의 대체재는 아닙니다. "누가 계획을 쥐고 있는가" 4자 비교표를 판단의 지름길로 곁에 두세요: 순차적인 지시를 따르는 단일 에이전트 - subagent/skill, 서로 메시지를 주고받는 길고 협업적인 세션 - agent teams, 하나의 컨텍스트 창보다 큰 작업이나 수백 개의 subagent가 필요한 작업 - workflow. 먼저 중요하지 않은 것에서 시도하고, 제한 사항을 꼼꼼히 읽고, 언제든 바뀔 수 있는 세부 사항에 프로덕션 프로세스를 고정하지 마세요.