Claude Code 에이전트 팀(Agent Teams) 완전 정리

핵심 요약

Claude Code 에이전트 팀은 여러 개의 Claude Code 인스턴스를 한꺼번에 띄워 병렬로 작업시키고, 그 위에 "팀 리드" 세션이 조율하는 구조입니다.

연구·리뷰·멀티 모듈 개발·가설 경쟁 탐색처럼 병렬 탐색의 이득이 큰 문제에 적합하지만, 토큰 비용과 조율 비용이 크기 때문에 사용 목적을 분명히 해야 합니다.

팀 생성, 작업 배분, 디스플레이 모드, 권한·한계까지 이해하면 "여러 명의 Claude를 한 프로젝트에 투입하는" 느낌으로 전략적으로 활용할 수 있습니다.

에이전트 팀이란 무엇인가

에이전트 팀은 하나의 리드 세션을 중심으로 여러 Claude Code 인스턴스를 팀원으로 띄워 함께 일하게 하는 기능입니다.

리드는 작업을 쪼개고, 팀원을 생성하고, 작업을 배정하며, 결과를 종합합니다. 팀원은 각각 독립된 콘텍스트 창(별도 Claude 세션)을 가지며, 서로 직접 메시지를 주고받을 수 있습니다.

중요한 점은, 기존의 "한 세션에 모든 일을 시키던 방식"에서 벗어나, 역할을 나눠 병렬로 탐색하고, 논쟁하고, 서로 결과를 검증하는 협업 구조를 제공한다는 점입니다.

이 기능은 아직 실험적이며 기본값은 비활성화이고, 세션 복원·종료 처리 등 몇 가지 제한사항도 함께 존재합니다.

에이전트 팀을 언제 쓰고, 언제 쓰지 말까

에이전트 팀은 병렬 탐색의 이득이 확실할 때 가장 빛을 발합니다. 예를 들어, 하나의 문제를 여러 관점에서 동시에 조사하는 리서치, PR 리뷰 시 보안·성능·테스트를 각기 다른 팀원이 동시에 보는 경우, 프런트/백엔드/테스트가 섞인 기능 개발처럼 레이어가 나뉜 작업이 대표적입니다.

반대로, 한 파일을 여러 번 고쳐야 하거나, 의존성이 많은 단계적 작업처럼 순차적 진행이 중요한 경우에는 오히려 비용과 혼선만 늘 수 있습니다. 이런 작업은 단일 세션이나 서브에이전트가 더 적합합니다.

또한 팀을 띄우면 팀원 수만큼 Claude 인스턴스가 늘어나 토큰 사용량이 폭증하므로, "이 작업이 진짜 병렬 탐색의 가치가 있는지?"를 먼저 자문하는 습관이 필요합니다.

에이전트 팀 vs 서브에이전트 비교 이해하기

서브에이전트와 에이전트 팀은 모두 "병렬 작업"을 돕지만, 구조와 커뮤니케이션 방식이 다릅니다.

서브에이전트는 하나의 메인 에이전트 안에서 돌아가는 보조 작업자입니다. 독립 콘텍스트를 갖지만, 결과를 메인에게만 보고하고, 서브끼리 직접 대화하거나 공동 태스크를 관리하지는 않습니다. 이 때문에 짧고 명확한 하위 작업(요약, 검증, 단일 조사 등)에 적합합니다.

반면 에이전트 팀의 팀원들은 서로 메시지를 보내고, 공동 작업 목록을 공유하며, 자율적으로 태스크를 나누어 처리합니다. 토론·비판·가설 검증처럼 "서로 소통해야 가치가 생기는 작업"에서는 에이전트 팀이 훨씬 강력합니다.

따라서 "결과만 메인으로 돌아오면 되는 단독 심부름"은 서브에이전트, "서로 말이 통하는 팀 활동"은 에이전트 팀으로 생각하면 선택 기준이 명확해집니다.

사용 준비: 활성화와 기본 설정

에이전트 팀은 기본적으로 꺼져 있으므로, 먼저 환경 변수나 설정 파일에서 기능을 켜야 합니다.

settings.json에 다음처럼 환경 변수를 추가하면 됩니다.

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

또는 쉘 환경에서 같은 환경 변수를 설정해도 됩니다.

이후 Claude Code 세션에서 자연어로 "팀을 만들어 달라"고 요청할 수 있는데, 이때부터 리드 세션이 팀 생성·팀원 스폰·작업 조율을 수행합니다.

처음 사용할 때는 간단한 리서치·리뷰 같은 안전한 문제에서 테스트해 보는 것이 좋습니다. 실제 코드 수정을 대규모로 맡기기 전에, 작동 패턴과 토큰 사용량을 체감해 보는 단계가 필요합니다.

팀 시작과 조율 흐름 이해하기

팀을 시작할 때는 "무엇을 할지"와 "어떤 역할의 팀원이 필요한지"를 자연어로 서술합니다.

예를 들어, CLI 도구의 UX·아키텍처·문제 제기 관점을 각각 맡는 팀원을 요청하면, 리드는 그에 맞는 팀원을 생성하고, 공용 태스크 목록을 만들어 일을 나눕니다.

팀이 동작하면 리드의 터미널에는 팀원 목록과 각자의 작업 상태가 표시됩니다. 필요하면 특정 팀원에게 직접 말 걸기, 태스크 재배정, 팀원 종료 요청 등도 모두 자연어로 지시할 수 있습니다.

제작이 끝나면 "팀 정리"를 요청하여 공용 리소스를 정리해야 하며, 이때 리드는 아직 살아 있는 팀원이 있는지 확인하고, 있는 경우 정리 실패로 알려줍니다. 팀 정리는 반드시 리드에게 시켜야 하며, 팀원이 임의로 정리하면 상태가 꼬일 수 있습니다.

화면 구성: 인프로세스 vs 분할 창 모드

에이전트 팀을 운용할 때는 팀원의 출력을 어떻게 볼지 선택해야 합니다.

기본 인프로세스 모드는 한 터미널 안에 리드와 팀원들이 모두 들어와 있고, Shift+위/아래로 팀원을 선택해 메시지를 보내거나 세션을 확인합니다. 별도 도구 없이 어디서나 동작하는 것이 장점입니다.

분할 창 모드는 tmux 또는 iTerm2를 활용해 각 팀원을 독립된 패널로 보여줍니다. 이 방식에서는 여러 팀원의 로그를 동시에 볼 수 있고, 각 패널에 포커스를 옮겨 직접 상호작용할 수 있어 "여러 개발자가 옆에서 함께 코딩하는 화면"에 가깝습니다.

설정은 settings.json의 teammateMode로 조절할 수 있고, 명령줄에서 claude --teammate-mode in-process처럼 세션 단위로 강제할 수도 있습니다. 분할 창 모드는 tmux나 iTerm2+it2 CLI가 필요하다는 점만 주의하면 됩니다.

팀 구성 세부 옵션: 인원, 모델, 계획 승인, 델리게이트 모드

리드에게 구체적으로 팀 구성을 지시하면, 팀원 수와 모델 종류까지 통제할 수 있습니다. 예를 들어 "4명의 팀원에게 Sonnet 모델을 사용해 모듈 리팩터링을 병렬로 진행하라"고 주문할 수 있습니다.

위험하거나 복잡한 작업에서는 "계획 승인 모드"를 요청할 수 있습니다. 이 경우 특정 팀원은 먼저 변경 계획을 세우고, 리드가 이를 검토해 승인할 때까지는 읽기 전용 상태로 머무릅니다. 승인 기준(테스트 포함 여부, DB 스키마 변경 금지 등)은 프롬프트에서 명시할 수 있습니다.

또 하나의 중요한 옵션이 "델리게이트 모드"입니다. 기본 상태에서는 리드가 필요하다고 판단하면 직접 작업을 시작해 버릴 수도 있는데, 델리게이트 모드를 켜면 리드는 코드 수정 등 실 작업을 하지 않고, 팀 구성·메시지 전달·태스크 관리 같은 조율 업무에만 집중합니다. 이 모드는 팀을 시작한 뒤 Shift+Tab으로 전환할 수 있습니다.

이 옵션들을 적절히 조합하면, 리드를 "PM + 아키텍트", 팀원들을 "개발자"처럼 역할 분리하여 운영하는 구조를 만들 수 있습니다.

팀원과 직접 대화하고, 태스크로 협업하기

각 팀원은 하나의 완전한 Claude Code 세션이므로, 리드를 통하지 않고도 직접 지시와 피드백을 줄 수 있습니다.

인프로세스 모드에서는 Shift+위/아래로 팀원을 선택하고, Enter로 그 팀원의 세션을 열어 내용을 보고, Esc로 현재 턴을 중단할 수 있습니다. 분할 창 모드에서는 단순히 해당 패널을 클릭한 뒤 바로 입력하면 됩니다.

팀의 공동 작업은 "공용 태스크 목록"으로 관리됩니다. 태스크는 대기·진행 중·완료 상태를 가지며, 다른 태스크에 대한 의존 관계도 가질 수 있습니다. 아직 완료되지 않은 의존 태스크가 있는 경우, 해당 태스크는 자동으로 잠겨 있어 아무도 시작할 수 없습니다.

리드는 특정 태스크를 특정 팀원에게 배정할 수 있고, 팀원은 자신이 맡은 일을 마친 후 스스로 다음 대기 태스크를 "자기 할당"할 수 있습니다. 동시에 여러 팀원이 같은 태스크를 잡는 충돌은 파일 락킹 방식으로 방지됩니다.

내부 동작: 아키텍처, 권한, 콘텍스트, 토큰 사용

에이전트 팀은 크게 리드, 팀원들, 공용 태스크 목록, 메시지 시스템이라는 네 요소로 이루어진 구조입니다.

팀 설정과 태스크 목록은 로컬 파일 시스템에 저장되며, 팀 설정 파일에는 팀원 이름·에이전트 ID·타입 정보가 포함되어 있어 팀원들이 서로를 탐색할 수 있습니다.

권한 측면에서는 리드의 권한 설정이 팀 생성 시 그대로 팀원에게 복사됩니다. 예를 들어 리드가 --dangerously-skip-permissions로 실행되었다면 모든 팀원이 같은 위험 모드로 시작합니다. 이후 개별 팀원의 권한 모드를 바꾸는 것은 가능하지만, 스폰 시점에 팀원별로 다르게 설정하는 것은 지원되지 않습니다.

각 팀원은 독립된 콘텍스트를 가지며, 프로젝트 내 CLAUDE.md, MCP 서버, 스킬 등을 리드와 마찬가지로 로딩하지만, 리드의 대화 히스토리는 공유하지 않습니다. 정보 공유는 메시지, 브로드캐스트, 공용 태스크 상태를 통해 이루어집니다.

토큰 사용량은 "활성 팀원 수 × 각자의 콘텍스트"로 선형 증가하므로, 팀 규모와 작업 길이를 신중히 잡지 않으면 비용이 크게 튈 수 있습니다.

대표적인 활용 시나리오

코드 리뷰에서 에이전트 팀을 쓰면, 하나의 PR을 세 명이 서로 다른 렌즈로 동시에 보는 방식으로 깊이와 속도를 모두 챙길 수 있습니다. 예를 들어 보안, 성능, 테스트 커버리지 전담 리뷰어를 만들어 각자 문제를 찾고, 리드가 결과를 모아 종합 리뷰를 작성하도록 할 수 있습니다.

버그 원인 조사처럼 "답이 불분명한 문제"에는 경쟁 가설 구조가 잘 어울립니다. 여러 팀원이 서로 다른 원인을 가정하고 각자 탐색하며, 동시에 서로의 가설을 반박하도록 지시하면, 일종의 과학적 토론처럼 검증이 진행됩니다. 이 방식은 "첫 그럴듯한 가설에 고정되는 인지 편향(anchoring bias)"을 줄이는 데 효과적입니다.

이 밖에도, 신규 기능을 구현할 때 프런트·백엔드·테스트 담당을 구분하거나, 큰 리팩터링에서 모듈별 책임자를 나누는 등 사람이 실제로 팀을 구성하는 방식과 비슷하게 설계할 수 있습니다.

효과적으로 쓰기 위한 베스트 프랙티스

먼저, 팀원을 스폰할 때 필요한 배경과 목표를 프롬프트에 충분히 담아야 합니다. 팀원은 리드의 기존 대화 내용은 모르기 때문에, 마치 새로운 동료에게 일을 맡기듯 "어떤 디렉터리를 보라, 어떤 기술 스택이며, 무엇을 중점적으로 보라"까지 구체적으로 적어주는 편이 좋습니다.

태스크 크기는 "너무 잘게 쪼개면 조율 비용이 더 크고, 너무 크면 한참 동안 엇나간 채 작업할 위험이 커지는" 중간 지점을 찾는 것이 중요합니다. 일반적으로 팀원 한 명당 5~6개의 자립적인 단위(함수·테스트 파일·리뷰 포인트 등)를 준비해 둔 상태가 운영하기 좋습니다.

리드가 팀원을 무시하고 스스로 일을 시작하는 경향이 보이면 "팀원이 끝날 때까지 기다리라"고 명시적으로 지시하거나, 아예 델리게이트 모드를 켜 두는 것이 좋습니다.

코드 수정을 병렬로 시킬 때는 같은 파일을 두 명이 동시에 고치지 않도록, 파일·모듈 단위로 소유권을 나눠야 합니다. 그렇지 않으면 덮어쓰기와 충돌이 빈번해집니다.

마지막으로, 팀을 완전히 자동으로 내버려두기보다는 중간중간 진행 상황을 확인하며 방향을 조정하고, 필요하면 태스크 분할·재배정·팀원 추가/종료를 수시로 해 주는 것이 효율과 품질 모두에 좋습니다.

문제 상황과 한계 이해하기

실무에서 자주 부딪히는 문제들을 미리 알고 있으면 당황을 줄일 수 있습니다.

팀원이 안 보일 때는, 인프로세스 모드에서는 이미 실행 중인데 선택만 안 되어 있을 수 있으니 Shift+아래로 순환해 보고, 분할 창 모드를 강제했다면 tmux나 iTerm2 설정·PATH를 점검해야 합니다. 권한 팝업이 너무 자주 뜬다면, 팀을 만들기 전에 자주 쓰는 권한을 미리 허용해 두는 것이 좋습니다.

팀원이 에러에서 스스로 회복하지 못하고 멈추면, 해당 팀원의 화면을 직접 확인한 뒤 추가 지시를 주거나, 새 팀원을 스폰해 이어받게 할 수 있습니다. 리드가 "끝났다"고 판단했는데 실제로는 태스크가 남은 경우도 있으니, 그럴 땐 리드에게 계속 진행하라고 명시적으로 요청해야 합니다.

현재 한 세션은 하나의 팀만 관리할 수 있고, 팀 안에서 또 다른 팀을 만드는 중첩 구조는 지원되지 않습니다. 또한 인프로세스 팀원은 /resume으로 복원되지 않기 때문에, 세션 재개 후에는 필요한 팀원을 다시 띄워야 합니다.

분할 창 모드는 tmux나 iTerm2가 필요한 만큼, VS Code 내장 터미널이나 Windows Terminal, Ghostty 등에서는 인프로세스 모드를 사용하는 것이 안전합니다.

인사이트

에이전트 팀은 "Claude를 여러 명 고용해서 한 프로젝트에 투입하는 것"과 비슷합니다.

팀을 만들기 전에 병렬 탐색이 진짜 도움이 되는 문제인지, 그리고 결과를 통합할 주도적인 리드를 어떻게 설계할지부터 생각하는 습관을 들이면, 토큰과 시간을 크게 아낄 수 있습니다.

처음에는 PR 리뷰·리서치·가설 경쟁 조사처럼 코드 변경이 없는 작업으로 연습하며, 화면 모드와 태스크 전략, 델리게이트 모드 운용에 익숙해지는 것이 좋습니다.

그다음 단계로, 기능 개발이나 리팩터링에서 모듈·계층 단위로 작업을 나누고, "계획 승인 + 테스트 필수" 같은 안전 장치를 두면, 실제 팀 개발에 가까운 형태로 Claude를 활용할 수 있습니다.

결국 핵심은 "역할 분리 + 충분한 콘텍스트 + 적절한 태스크 크기 + 지속적인 모니터링" 네 가지를 지키는 것입니다. 이 네 가지를 의식하면서 설계하면, 에이전트 팀은 단일 세션으로는 얻기 어려운 깊이·속도·견제 효과를 동시에 제공하는 강력한 도구가 됩니다.

출처 및 참고 : Orchestrate teams of Claude Code sessions - Claude Code Docs