Claude Code 에이전트 팀: 병렬 작업으로 개발 가속하기

핵심 요약

에이전트 팀은 여러 개의 Claude Code 인스턴스를 한 번에 돌려 병렬로 연구·리뷰·개발을 진행하게 해주는 기능입니다.
리드(총괄) 하나가 팀을 조직·조율하고, 각 팀원은 독립 세션으로 일하면서 서로 메시지를 주고받고 공유 작업 목록을 사용해 협업합니다.
토큰 비용과 오버헤드는 크지만, 복잡한 문제를 빠르게 탐색하거나 리뷰·디버깅을 병렬화할 때 특히 유효합니다.

에이전트 팀 개념과 언제 쓰는지

에이전트 팀은 "여러 명의 Claude 개발자/리뷰어를 동시에 고용한다"고 생각하면 이해가 쉽습니다.
한 세션이 팀 리드가 되고, 나머지는 팀원으로 떠서 각각 자기 컨텍스트 창에서 독립적으로 일합니다.

이 기능은 특히 병렬 탐색의 가치가 큰 문제에 적합합니다.
예를 들어, 한 기능을 여러 관점(UX, 아키텍처, 리스크)에서 동시에 검토할 때, 또는 서로 다른 가설로 디버깅을 병렬 수행할 때 강력합니다.

반대로, 순차적인 작업이나 같은 파일을 여러 번 수정해야 하는 일, 의존성이 촘촘한 리팩터링에는 오버헤드만 늘고 효율이 떨어집니다.
이럴 땐 보통 단일 세션이나 서브에이전트가 더 낫습니다.

에이전트 팀 vs 서브에이전트: 전략적 선택

서브에이전트는 "도우미 프로세스"에 가깝습니다.
독립적인 컨텍스트를 가지지만, 결과는 호출한 메인 에이전트에게만 돌아가고, 서브에이전트끼리 직접 대화하거나 자율적으로 협업하지 않습니다.

에이전트 팀은 "동료들로 구성된 팀"입니다.
각 팀원이 서로 메시지를 보내고, 공유 작업 목록을 보고, 스스로 일을 나눠 맡을 수 있습니다.
대신 팀원 하나하나가 독립 Claude 인스턴스이므로 토큰 비용은 서브에이전트보다 크게 듭니다.

정리하면, 결과만 필요하고 상호 토론이 불필요한 서브 태스크(예: 간단한 리서치, 특정 함수 검증)는 서브에이전트가 적합합니다.
반대로 논의·반박·합의를 거쳐야 하는 복잡한 일(예: 아키텍처 설계, 복합 디버깅, 다각도의 코드 리뷰)은 에이전트 팀이 더 적합합니다.

활성화와 기본 사용 흐름

에이전트 팀은 기본 비활성화 상태라, 먼저 설정이나 환경변수로 켜야 합니다.
settings.json의 env에 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "1"을 넣거나, 환경변수로 동일 값을 설정하면 됩니다.

그 후에는 "자연어로 팀을 만들어 달라"고 요청하는 것만으로 시작됩니다.
예를 들어, "CLI TODO 트래커를 설계하니 UX, 기술 구조, 리스크를 각각 맡을 팀을 만들어 달라"는 식으로 역할과 목표를 설명하면, 리드가 팀을 구성하고 작업 목록을 만들고 팀원을 스폰합니다.

리드 터미널에서 팀원 목록과 담당 작업을 확인할 수 있고, 단축키(Shift+위/아래)로 특정 팀원을 선택해 직접 메시지를 보낼 수 있습니다.
팀 종료 시에는 리드에게 "팀 정리해 달라"고 요청해 공유 리소스를 깨끗이 정리합니다.

표시 모드: 한 화면 vs 여러 화면

팀원 세션을 어떻게 보여줄지는 모드에 따라 달라집니다.
"인프로세스 모드"는 한 터미널 안에서 팀원들을 번갈아 보며 상호작용하는 방식입니다.
추가 설치 없이 어디서나 동작하고, 단축키로 팀원을 전환하며 대화합니다.

"분할 창 모드"는 각 팀원을 별도 터미널 패널로 띄우는 방식입니다.
tmux 혹은 iTerm2+it2 CLI가 필요하지만, 모든 팀원의 출력을 동시에 볼 수 있어 진행 상황 모니터링에 유리합니다.
기본 설정은 자동 판별로, tmux 환경이면 분할 창을, 아니면 인프로세스를 사용합니다.

설정 파일의 teammateMode 값이나 CLI 플래그(--teammate-mode)로 모드를 강제로 지정할 수 있습니다.
스타트업처럼 빠르게 실험해보려면 일단 인프로세스로 시작하고, 팀이 복잡해질 때 tmux 기반 분할 창을 검토하는 것이 현실적입니다.

팀 구조: 리드, 팀원, 작업 목록, 메시지 시스템

에이전트 팀의 핵심 구성요소는 네 가지입니다.
리드는 팀 관리의 중심입니다. 팀 생성, 팀원 스폰, 작업 분배, 결과 종합, 정리까지 모두 리드가 담당합니다.

팀원은 각각 별도의 Claude Code 세션으로 동작합니다.
각 팀원은 프로젝트 컨텍스트(CLAUDE.md, MCP 서버, 스킬)를 로딩하고, 리드로부터 받은 "스폰 프롬프트"를 기반으로 역할과 목표를 이해합니다.

작업 목록은 팀 전체가 공유하는 할 일 보드입니다.
작업은 "대기, 진행 중, 완료"로 상태를 가지고, 다른 작업에 의존할 수도 있습니다.
의존 작업이 끝나야만 다음 작업을 잡을 수 있으며, 동시에 여러 팀원이 동일 작업을 잡지 않도록 파일 락을 사용해 경합을 막습니다.

메시지 시스템(메일박스)은 리드와 팀원, 팀원끼리의 통신 채널입니다.
특정 팀원에게 직접 보내는 메시지와 팀 전체에게 뿌리는 브로드캐스트가 있으며, 브로드캐스트는 팀원 수만큼 토큰이 든다는 점을 염두에 둬야 합니다.

리드 제어: 위임 모드, 계획 승인, 직접 대화

리드는 기본적으로 "조정 + 직접 작업"을 둘 다 할 수 있습니다.
그러다 보면 리드가 팀원을 기다리지 않고 스스로 구현을 시작해 병렬성이 떨어질 수 있습니다.

이럴 때 "위임 모드"를 켜면 리드는 오직 팀 운영(스폰, 메시지, 종료, 작업 관리)만 수행하고 코드 작업은 하지 못하게 제한됩니다.
팀이 커질수록 리드를 "PM+Tech Lead" 역할로 고정하는 셈이라, 전체 전략 설계와 결과 통합에 집중시킬 수 있습니다.

위험하거나 영향도가 큰 작업에는 "계획 승인"을 필수로 요구할 수 있습니다.
해당 팀원은 처음엔 읽기 전용으로 설계·계획만 세우고, 리드에게 승인 요청을 보냅니다.
리드는 기준(테스트 포함 여부, DB 스키마 변경 금지 등)에 맞춰 자동 판단하며 승인 또는 피드백과 함께 거절합니다.

각 팀원은 독립 세션이므로 언제든 그 팀원에게 직접 말을 걸어 방향을 바꾸거나 추가 정보를 줄 수 있습니다.
리드를 거치지 않고 바로 팀원과 대화할 수 있다는 점이 서브에이전트와 가장 큰 차이입니다.

사용 시나리오: 병렬 코드 리뷰와 경쟁 가설 디버깅

PR 리뷰에 에이전트 팀을 쓰면 "전담 리뷰어 3명"을 동시에 두는 효과를 얻을 수 있습니다.
한 명은 보안, 한 명은 성능, 한 명은 테스트 관점만 보도록 역할을 나누면, 한 사람이 모든 관점을 번갈아 보는 것보다 누락이 줄고 속도가 빨라집니다.
리드는 이들의 결과를 취합해 요약 리포트를 제공하므로, 사람이 확인할 때 이미 잘 정리된 상태를 받게 됩니다.

디버깅에서는 "서로 다른 가설을 가진 조사관들"을 동시에 투입하는 패턴이 유용합니다.
앱이 한 번 메시지 주고 바로 종료되는 문제라면, 각각 네트워크, 세션 관리, 에러 핸들링, 클라이언트 로직, 서버 설정 등 다양한 가설을 맡긴 뒤 서로의 가설을 반박하게 하는 식입니다.
이렇게 경쟁적으로 가설을 깨보게 하면, 첫 그럴듯한 가설에 멈추는 '앵커링 편향'을 줄이고 실제 원인을 더 빠르게 찾을 수 있습니다.

스타트업 환경에서는 크리티컬 장애나 중요한 PR에 이런 구조를 도입하면, 사람의 시간을 절약하면서도 품질과 속도를 동시에 확보하기 좋습니다.

운영 팁: 컨텍스트, 작업 크기, 충돌 방지, 모니터링

팀원은 리드의 대화 이력까지는 공유받지 못합니다.
따라서 스폰 프롬프트에 최대한 구체적인 컨텍스트(경로, 기술 스택, 제약조건, 우선순위)를 담아줘야 팀원이 바로 생산적으로 움직입니다.

작업을 너무 잘게 쪼개면 조율 비용이 커지고, 너무 크게 잡으면 팀원이 오랫동안 "혼자 딴짓"하다가 잘못된 방향으로 가기 쉽습니다.
보통 팀원 1명당 5~6개의 독립된, 결과물이 명확한 태스크(예: 특정 파일 테스트 작성, 하나의 모듈 리팩터링, 한 영역 리뷰)가 적당합니다.

여러 팀원이 같은 파일을 수정하면 충돌과 덮어쓰기가 발생합니다.
가능한 한 파일 혹은 모듈 단위로 소유권을 나눠주고, 공유 파일 변경은 한 팀원에게 집중시키는 편이 안전합니다.

마지막으로, 팀을 "돌려만 놓고 잊어버리면" 토큰과 시간이 낭비될 확률이 큽니다.
진행 상황을 주기적으로 확인하고, 잘못된 방향으로 가는 팀원은 즉시 리다이렉트하고, 필요하면 팀원을 종료하거나 새로 스폰해 유지보수하는 감각이 중요합니다.

한계와 주의사항

에이전트 팀은 아직 실험적 기능이라 몇 가지 제약이 있습니다.
세션 재개(/resume, /rewind) 시 인프로세스 팀원이 복원되지 않고, 리드가 존재하지 않는 팀원에게 메시지를 보내려 할 수 있으므로, 이 경우 새 팀원을 다시 스폰해야 합니다.

작업 상태가 실제 진행과 어긋나는 경우도 있습니다.
팀원이 실제로는 일을 끝냈는데 작업을 완료로 표시하지 않아 의존 작업이 막혀 보일 수 있으므로, 이상하면 직접 결과를 확인하고 상태를 수동으로 조정하거나 리드에게 "태스크 상태를 정리하라"고 지시해야 합니다.

한 세션당 한 팀만 운영 가능하고, 팀원은 또 다른 팀을 만들 수 없습니다.
리드도 교체할 수 없으니, 세션 설계 시 리드로 사용할 터미널과 권한 설정을 처음부터 신중히 정하는 것이 좋습니다.

분할 창 모드는 tmux나 iTerm2가 필요해, VS Code 통합 터미널이나 Windows Terminal 등에서는 기본 인프로세스만 사용할 수 있습니다.
실제 팀 운영 환경과 터미널 도구 체인에 따라 UX가 꽤 달라질 수 있음을 염두에 둬야 합니다.

인사이트

스타트업 입장에서 에이전트 팀은 "AI 기반 멀티스레드 개발/리뷰 엔진"으로 활용할 수 있습니다.
모든 작업에 쓸 도구는 아니고, 고비용인 만큼 임팩트가 큰 문제(핵심 기능 설계, 주요 PR 리뷰, 난해한 버그) 위주로 제한적으로 쓰는 것이 좋습니다.

도입 전략으로는, 먼저 코드 작성이 아닌 "연구·리뷰·디버깅" 같은 부작업에 제한적으로 적용해 패턴을 익히는 것을 추천합니다.
이 과정에서 어떤 작업을 어떻게 쪼개면 팀이 효율적으로 돌아가는지 감이 잡히면, 조금씩 구현 단계로 확장해 나가는 방식이 리스크와 비용을 줄입니다.

결국 핵심은 "어떤 일을 몇 명의 가상 동료에게 어떻게 나눠줄 것인가"입니다.
역할 정의, 태스크 분할, 컨텍스트 제공만 잘 설계하면, 에이전트 팀은 작은 팀이 큰 팀처럼 움직이게 만들어 주는 강력한 레버리지 도구가 될 수 있습니다.

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