핵심 요약
Claude Code 에이전트 팀은 여러 개의 Claude Code 인스턴스를 하나의 팀처럼 묶어 병렬로 작업하게 하는 기능이다.
한 세션이 리더가 되어 작업을 쪼개고 배분하며, 각 팀원은 독립된 컨텍스트에서 소통·협업·자율 조정을 수행한다.
복잡한 연구·리뷰·대규모 기능 개발 등 "병렬 탐색의 가치가 큰 작업"에서 특히 유용하다.
에이전트 팀의 기본 개념
에이전트 팀은 "리더 1 + 팀원 N" 구조로 움직이는 가상의 개발 팀이라고 생각하면 이해하기 쉽다.
리더는 전체 목표를 이해하고 작업을 나누며, 어떤 팀원이 무엇을 할지 조율하고 결과를 모아 종합한다.
각 팀원은 별도의 Claude Code 세션으로, 자신의 컨텍스트와 터미널을 가지고 독립적으로 작업하며, 서로 메시지를 주고받을 수 있다.
중요한 점은, 이 구조가 한 세션에 모든 것을 몰아 넣는 대신, 여러 세션에서 병렬로 탐색하고 토론하게 만들기 때문에 복잡한 문제를 더 빠르고 입체적으로 다룰 수 있다는 점이다.
언제 에이전트 팀을 쓰면 좋은가
에이전트 팀이 진가를 발휘하는 상황은 "여러 관점에서 동시에 파고들 가치가 있는 문제"다.
예를 들어 새로운 기능을 설계할 때, 한 명은 UX, 한 명은 아키텍처, 한 명은 리스크 분석을 맡아 동시에 고민하게 하면 서로의 관점이 충돌·보완되면서 설계 품질이 올라간다.
복잡한 버그 분석에서도 서로 다른 가설을 병렬로 검증하게 만들면, 한 가설에 집착하는 "앵커링"을 줄이고 실제 원인에 더 빠르게 도달할 수 있다.
반대로, 순차적인 단계가 많거나, 같은 파일을 자주 수정해야 하거나, 의존성이 촘촘한 작업이라면 에이전트 팀보다 단일 세션이나 서브에이전트가 더 낫다.
에이전트 팀 vs 서브에이전트
두 기능 모두 병렬 작업을 가능하게 하지만 성격이 다르다.
서브에이전트는 "메인 에이전트가 쓰는 일회성 심부름꾼"에 가깝다. 각 서브에이전트는 자기 컨텍스트 안에서 일을 하고, 결과만 메인 세션에 요약해서 전달한다. 서브끼리는 서로를 모른다.
반면 에이전트 팀의 팀원은 서로 메시지를 주고받으며, 공용 작업 목록을 보고, 서로의 진행 상황을 고려해 자율적으로 조정한다. 즉 "진짜 팀"처럼 상호 협업이 가능하다.
그만큼 토큰 사용량은 더 크고, 조정 비용도 생긴다.
요약하면, 결과만 가져오면 되는 "작은 심부름"은 서브에이전트, 토론·비판·조정이 필요한 "협업 작업"은 에이전트 팀이 적합하다.
에이전트 팀 활성화와 첫 사용
에이전트 팀은 실험 기능이라 기본은 꺼져 있다.
환경 변수 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 을 설정하거나 settings.json에 다음과 같이 추가해야 한다.
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}이후에는 자연어로 "어떤 팀을 만들고 무엇을 시킬지" 설명하면 된다.
예를 들어 "CLI TODO 추적 도구를 설계하는데 UX/아키텍처/악마의 변호인 역할을 가진 팀을 만들어 달라"고 요청하면, 리더가 해당 구조의 팀을 만들고, 팀원들을 스폰하고, 각자 탐색하게 만든 뒤 결과를 종합한다.
사용자는 리더에게만 말을 걸어도 되고, 필요하면 특정 팀원에게 직접 접근해서 세부 지시를 줄 수도 있다.
표시 모드: 인프로세스와 분할 화면
에이전트 팀을 어떻게 화면에 보여줄지에 따라 두 가지 모드가 있다.
기본값인 인프로세스 모드에서는 모든 팀원이 현재 터미널 안에서 순차적으로 표시된다. 단축키(예: Shift+위/아래)를 이용해 활성 팀원을 바꾸며, 선택된 팀원에게 직접 메시지를 입력할 수 있다. 이 방식은 별도 설정이 필요 없고, 어떤 터미널에서도 동작한다.
분할 화면 모드는 tmux 또는 iTerm2를 활용해 각 팀원을 별도의 창이나 패널로 나눠 보여준다. 여러 팀원의 로그와 작업을 동시에 모니터링하기 좋아서 "실시간 상황판" 같은 느낌을 얻을 수 있다. 단, tmux 또는 iTerm2의 설정이 추가로 필요하고, 일부 터미널(VS Code 내 터미널, Windows Terminal 등)에서는 직접 지원되지 않는다.
설정 파일의 teammateMode 값을 이용해 모드를 고정할 수 있고, 커맨드라인 플래그로 세션별로 강제할 수도 있다.
팀원 구성, 모델 지정, 계획 승인
리더가 자동으로 팀원 수를 판단해 생성할 수도 있지만, 직접 "몇 명을 어떤 모델로 쓸지"를 지정할 수도 있다. 예를 들어 "4명의 팀원을 만들고 모두 Sonnet을 쓰게 해달라"고 지시하는 식이다.
복잡하거나 위험한 작업에서는 팀원이 바로 코드를 고치지 못하게 하고, 먼저 계획을 세워 검토받게 할 수 있다. 이 모드에서는 팀원이 "읽기 전용"으로 분석과 계획만 수행하고, 리더에게 승인 요청을 보낸다.
리더는 계획을 보고 승인하거나, 피드백과 함께 거절해 재수정을 요구한다. "테스트 커버리지를 반드시 포함해야 한다"처럼 승인 기준을 프롬프트에 명시하면 리더의 판단 기준을 통제할 수 있다.
이 구조는 사람 조직에서 아키텍트가 설계안을 리뷰하고 나서야 구현에 들어가게 하는 절차와 비슷하다.
리더의 위임 모드(Delegate Mode)
기본 설정에서는 리더가 작업을 팀원에게 나누어 주면서도, 종종 스스로 코드를 작성하거나 구현 작업에 뛰어들기도 한다.
하지만 어떤 경우에는 리더가 "오로지 조율과 관리만" 하도록 만들고 싶을 수 있다. 이때 사용하는 것이 위임 모드다.
위임 모드에서는 리더에게 팀원 생성, 메시지 전달, 작업 목록 관리, 팀 종료 같은 "관리 도구"만 허용되고, 직접 코드 수정 같은 일을 하지 못한다.
팀을 생성한 뒤 단축키를 이용해 위임 모드로 전환하면, 리더를 진짜 매니저처럼 "작업을 쪼개고, 사람을 붙이고, 결과를 통합하는 역할"에만 집중시킬 수 있다.
팀원과 직접 대화하고 작업을 배분하는 방법
각 팀원은 하나의 완전한 Claude Code 세션이므로, 사용자도 이들과 직접 대화할 수 있다.
리더에게만 명령을 전달하는 것이 기본이지만, 특정 팀원이 잘못된 방향으로 가는 것 같거나, 추가 맥락이 필요한 경우에는 해당 팀원 세션으로 들어가 직접 메시지를 보낼 수 있다.
공용 작업 목록은 팀 전체의 "할 일 보드" 역할을 한다. 리더는 여기에 작업을 만들고, 특정 작업을 특정 팀원에게 배정할 수도 있고, 팀원들이 스스로 비어 있는 작업을 가져가 처리하게 만들 수도 있다.
작업은 대기, 진행 중, 완료 상태를 가지며, 다른 작업에 의존성을 가질 수 있다. 의존성이 해결되지 않은 작업은 자동으로 "잠김" 상태가 되어, 선행 작업이 끝나야 잡을 수 있다.
여러 팀원이 동시에 같은 작업을 잡으려 할 때의 충돌은 파일 락킹으로 방지한다.
팀 종료와 정리(cleanup)의 절차
팀 작업을 마치고 나면, 개별 팀원의 세션을 종료하고, 팀 전체 자원을 정리해야 한다.
팀원을 종료할 때는 리더에게 "어떤 팀원을 종료하라"고 요청하면 된다. 리더는 해당 팀원에게 종료 요청을 보내고, 팀원은 이를 수락하며 부드럽게 종료하거나, 필요시 거절 사유를 설명할 수 있다.
모든 팀원을 종료한 뒤, 리더에게 "팀 정리"를 요청하면 공용 설정과 작업 목록 등이 삭제된다.
정리 작업은 반드시 리더를 통해 수행해야 한다. 팀원에게 정리를 맡기면 팀 컨텍스트가 맞지 않아 일부 리소스가 남는 등 불안정한 상태가 발생할 수 있기 때문이다.
내부 구조와 컨텍스트 공유 방식
에이전트 팀은 크게 네 요소로 구성된다고 보면 된다. 리더, 여러 팀원, 공용 작업 목록, 그리고 서로 메시지를 주고받는 메일박스다.
각 팀원은 자체 컨텍스트 윈도우를 갖고 있으며, 스폰되는 시점에 리더가 준 프롬프트와 프로젝트 컨텍스트(CLAUDE.md, MCP 서버, 스킬 등)를 로드한다. 단, 리더의 대화 히스토리는 그대로 넘어가지 않는다.
정보 공유는 몇 가지 채널을 통해 이뤄진다. 특정 팀원에게 보내는 단일 메시지, 팀 전체에게 뿌리는 브로드캐스트, 그리고 작업 목록을 통한 간접적인 상태 공유가 그것이다.
팀 및 작업 정보는 로컬 디렉터리에 저장되며, 팀원들은 이 파일을 읽어 서로의 존재와 역할을 파악할 수 있다. 이 구조 덕분에 각 세션이 완전히 분리되어 있으면서도, 최소한의 메타데이터를 통해 느슨히 연결된다.
토큰 사용 특성과 대표적인 활용 시나리오
에이전트 팀을 쓰면 토큰 사용량이 크게 증가한다.
각 팀원이 독립된 Claude 인스턴스이기 때문에 컨텍스트가 각자 따로 유지되고, 팀원이 많을수록 토큰 사용량이 선형적으로 늘어난다고 생각하면 된다.
따라서 일상적인 작은 작업에는 과한 도구지만, 다음과 같은 상황에서는 토큰을 더 써서라도 얻는 이득이 크다.
여러 관점의 병렬 코드 리뷰(보안, 성능, 테스트 커버리지 등), 뚜렷한 원인이 불명확한 버그에 대한 경쟁적 가설 검증, 프론트/백엔드/테스트 등 계층별로 나누어 진행하는 대규모 기능 구현 등이 대표적이다.
이런 경우, 한 사람이 순차적으로 보는 것보다 여러 명이 동시에 다른 관점으로 보는 편이 더 빠르고 깊은 결과를 가져온다.
효과적으로 쓰기 위한 실전 팁
에이전트 팀을 잘 활용하려면 "작업 쪼개기"와 "맥락 전달"이 중요하다.
팀원은 리더의 대화 히스토리를 모르기 때문에, 스폰할 때 프롬프트에 필요한 파일 경로, 기술 스택, 주의점 등을 명시적으로 담아주는 것이 좋다. 예를 들어 보안 리뷰 팀원에게는 대상 디렉터리, 사용 중인 인증 방식, 중점 검토 항목을 구체적으로 알려주는 식이다.
작업 단위는 너무 작으면 조정 비용이 커지고, 너무 크면 팀원이 한참 헤매다 방향이 틀어져도 알아차리기 늦어진다. 대략 팀원당 5~6개의 "독립적인 산출물을 만드는" 작업으로 나누는 것이 균형 잡힌 편이다.
처음부터 코드 수정 같은 위험한 병렬 작업에 투입하기보다는, PR 리뷰, 라이브러리 리서치, 버그 원인 파악 등 "읽고 분석하는 작업"에 먼저 적용해 감을 잡는 것이 안전하다.
또한 같은 파일을 둘 이상의 팀원이 동시에 수정하지 않도록, 파일 단위나 모듈 단위로 소유권을 나누는 것이 좋다. 중간중간 팀원 진행 상황을 확인하고, 방향이 어긋난 팀원은 지시를 다시 내려 궤도 수정하는 것도 중요하다.
문제 발생 시 자주 겪는 이슈와 대응
팀을 쓰다 보면 몇 가지 패턴화된 문제들이 등장한다.
팀원이 뜨지 않는 것처럼 보일 때는, 실제로는 이미 인프로세스 모드에서 돌고 있지만 현재 화면에 보이지 않는 경우가 많다. 이때는 팀원 전환 단축키로 순환하며 확인해 본다. 혹은 작업이 너무 단순해서 Claude가 굳이 팀을 만들 필요가 없다고 판단했을 수도 있다.
권한 승인 팝업이 너무 자주 뜬다면, 미리 설정에서 공통적인 파일 접근·명령 실행을 허용해 두어 마찰을 줄일 수 있다.
팀원이 에러를 만나 멈춘 상태에서 스스로 회복하지 못하는 경우, 해당 팀원 화면을 직접 확인하고 추가 지시를 주거나, 필요시 새 팀원을 스폰해 작업을 이어받게 하면 된다.
가끔 리더가 "다 끝났다"고 판단하고 팀을 종료하려 하는데 실제로는 작업이 남아 있을 수 있다. 이 경우 리더에게 계속 진행하라고 명시하거나, "팀원이 모두 끝낼 때까지 기다려라"라고 지시해서 조정하면 된다.
tmux 세션이 고아 상태로 남는 경우에는 tmux 명령으로 세션을 나열하고, 팀이 만든 세션을 직접 종료하면 깔끔하게 정리된다.
현재 한계와 제약 사항 이해하기
에이전트 팀은 아직 실험 단계이므로, 몇 가지 구조적 한계를 안고 있다.
인프로세스 팀원은 세션 복원(/resume, /rewind)의 대상이 아니다. 세션을 복원해도 기존 팀원은 사라져 있을 수 있고, 리더가 존재하지 않는 팀원에게 메시지를 보내려다 실패할 수 있다. 이때는 리더에게 새 팀원을 다시 스폰하라고 지시해야 한다.
작업 상태가 실제 진행과 어긋나는 경우도 있다. 팀원이 작업을 완료했는데 목록상 완료 표시를 하지 않아, 의존 작업이 계속 대기 상태로 남는 식이다. 이런 상황에서는 수동으로 상태를 조정하거나, 리더에게 해당 팀원을 재촉하라고 요청할 수 있다.
한 세션에 한 팀만 가질 수 있고, 팀 안에서 다시 하위 팀을 만드는 "중첩 팀"은 지원되지 않는다. 리더도 교체할 수 없고, 팀 생성 시점의 리더 권한 설정이 모든 팀원에게 복사되며, 스폰 시점에는 팀원별 권한을 개별 설정할 수 없다.
분할 화면 모드는 tmux 또는 iTerm2에 의존하므로, VS Code 내 터미널 등에서는 사용할 수 없다.
인사이트
에이전트 팀은 "혼자 일하는 똑똑한 개발자"를 여러 명 동시에 고용해 팀처럼 굴리는 도구라고 볼 수 있다.
하지만 실제 팀이 그렇듯, 사람을 많이 붙인다고 항상 좋은 결과가 나오는 것은 아니다. 작업을 잘 쪼개고, 적절한 맥락을 제공하며, 방향을 잡고, 충돌을 피하도록 관리하는 것이 핵심이다.
실전에서는 먼저 작은 리뷰·리서치 작업에 적용해 팀 운영 감각을 익히고, 그 다음에 중요한 기능 개발이나 난해한 버그 분석에 점진적으로 확대하는 전략이 안전하다.
마지막으로, 토큰은 "팀 인건비"라고 생각하면 좋다. 인건비를 더 쓸 만한 가치가 있는 문제에만 팀을 투입하면, 투자 대비 얻는 통찰과 생산성이 크게 높아질 것이다.
출처 및 참고 : Orchestrate teams of Claude Code sessions - Claude Code Docs
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.