클로드 코드 에이전트 팀, 여러 AI가 함께 일하는 법

왜 에이전트 팀이 필요한가

클로드 코드로 복잡한 작업을 하다 보면, 아무리 똑똑한 에이전트라도 한 세션에서 순서대로만 움직인다는 한계가 있습니다. 프론트·백엔드·테스트를 한 명이 모두 맡는 셈이죠. 실제 팀은 UI·API·테스트를 나눠 하고, 진행 상황을 공유하고 막히면 논의하면서 병렬로 일합니다. 이 팀워크를 AI에도 적용한 기능이 클로드 코드의 에이전트 팀(Agent Teams)입니다. 여러 클로드 코드 인스턴스가 한 팀으로 움직이며 각자 역할을 수행하고 작업을 완성해 나갑니다.

에이전트 팀이란

에이전트 팀은 여러 클로드 코드 인스턴스를 한 팀으로 조율하는 기능입니다. 팀 리드는 팀 생성·팀원 생성·전체 조율을 담당하는 메인 세션이고, 팀원(teammate)은 각자 독립된 클로드 코드 인스턴스로 할당된 태스크를 수행합니다. 팀원들은 공유 태스크 리스트를 보고 일을 나누어 가져가고, 메일박스로 서로 직접 메시지를 주고받습니다. 각 팀원은 자기 컨텍스트 윈도우만 가지며, 하나의 거대한 컨텍스트를 나누는 것이 아니라 필요한 정보만 메시지로 주고받습니다. 실제 팀이 각자 모니터를 보며 Slack으로 소통하는 것과 비슷합니다.

서브에이전트와의 차이

서브에이전트는 메인 에이전트가 헬퍼를 잠깐 불러 결과만 받는 구조라, 헬퍼끼리는 대화하지 않고 메인에게만 보고합니다. 빠르고 가볍지만 복잡한 협업에는 한계가 있습니다. 에이전트 팀은 팀원끼리 직접 메시지를 보내고, 공유 태스크 리스트로 자율적으로 조율하며, 발견한 내용을 공유하거나 서로 의견을 제기할 수 있습니다. 요약하면 서브에이전트는 "이거 조사해서 알려줘"에, 에이전트 팀은 "같이 고민하면서 해결하자"에 적합합니다. 토큰 비용은 에이전트 팀이 더 큽니다.

활성화와 첫 팀 만들기

에이전트 팀은 실험 기능이라 기본이 비활성화되어 있습니다. `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`을 settings.json의 env나 쉘 환경 변수로 설정하면 됩니다. 활성화한 뒤에는 자연어로 "에이전트 팀을 만들어서 …"처럼 요청하면 클로드가 팀과 팀원을 만들고 작업을 분배합니다. 예를 들어 CLI 도구 설계 시 "한 팀원은 UX, 한 팀원은 기술 아키텍처, 한 팀원은 비판적 시각으로 탐색해줘"처럼 역할을 나누면, 세 역할이 독립적으로 동시에 탐색하고 리드가 결과를 종합합니다. 팀원 수나 모델(Sonnet 등)을 직접 지정할 수도 있습니다.

디스플레이와 팀원 제어

In-process 모드는 모든 팀원이 메인 터미널 안에서 돌아가고, `Shift+Up/Down`으로 팀원을 골라 직접 메시지를 보낼 수 있습니다. Split panes 모드는 팀원마다 별도 터미널 패널을 주며, tmux나 iTerm2가 필요합니다. 기본값은 tmux 안이면 split panes, 아니면 in-process입니다. 팀원별로 계획 승인을 요구할 수 있어, 복잡하거나 위험한 작업 전에 리드가 계획을 검토·승인한 뒤에만 구현에 들어가게 할 수 있습니다. Delegate 모드를 켜면 리드는 조율만 하고 직접 구현하지 않게 할 수 있습니다.

태스크와 팀 활용 팁

태스크는 대기·진행 중·완료 상태를 가지며 의존 관계를 둘 수 있습니다. 리드가 특정 팀원에게 할당하거나, 팀원이 끝난 뒤 비어 있는 태스크를 스스로 가져가는 방식으로 배분됩니다. 리드는 팀원당 5~6개 정도 태스크를 만들어 두면 좋고, Hooks와 연동해 팀원이 유휴 상태가 되거나 태스크가 완료될 때 자동으로 품질 검사(테스트·린트 등)를 걸 수 있습니다. 병렬 코드 리뷰(보안·성능·테스트 커버리지 등 역할을 나눠 동시에 리뷰)나 경쟁 가설 조사(버그 원인을 여러 팀원이 서로 다른 가설로 검증하고 반증하게 하는 방식)처럼 병렬 탐색이 확실히 이득인 작업에 쓰는 것이 좋습니다. 작업이 끝나면 리드에게 "팀을 정리해줘"라고 하며, 팀원은 먼저 종료한 뒤 정리해야 합니다. 팀원에게는 생성 시 충분한 컨텍스트를 주고, 태스크 크기는 함수·테스트 파일 하나처럼 명확한 단위로 잡으며, 같은 파일을 두 팀원이 동시에 수정하지 않도록 나누는 것이 좋습니다.

제한과 맺음말

에이전트 팀은 아직 실험 기능이라 in-process 팀원은 `/resume`·`/rewind`로 복원되지 않고, 한 세션에 팀 하나만 가능하며 팀 중첩·리드 교체·split panes 미지원 환경(VS Code 터미널, Windows Terminal, Ghostty) 같은 제한이 있습니다. 토큰 사용이 크게 늘어나므로 병렬 탐색이 확실히 가치 있는 작업—코드 리뷰, 설계, 디버깅—부터 쓰고, 처음에는 파일을 건드리지 않는 PR 리뷰·라이브러리 조사·버그 원인 탐색부터 시도해 보는 것을 추천합니다.