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

클로드 코드로 복잡한 작업을 하다 보면 한 가지 아쉬운 점이 있습니다. 아무리 똑똑한 에이전트라도 결국 하나의 세션에서 순차적으로 작업하니까요. 프론트엔드를 고치고 백엔드 API를 수정하고 테스트까지 작성하려면 한 명이 모든 걸 해야 하는 셈이죠. 🤔

실제 개발팀에서는 어떻게 일할까요? 한 사람이 UI를 만들고 다른 사람이 API를 짜고 또 다른 사람이 테스트를 작성합니다. 서로 진행 상황을 공유하고 막히는 부분이 있으면 의논하면서 병렬로 작업을 진행하죠. 이런 팀워크를 AI에게도 적용할 수 있다면 어떨까요?

바로 이런 아이디어에서 출발한 기능이 클로드 코드의 에이전트 팀(Agent Teams)입니다. 여러 클로드 코드 인스턴스가 하나의 팀으로 움직이며 각자 맡은 역할을 수행하면서 작업을 완성해 나갑니다. 이 글에서는 에이전트 팀이 어떻게 작동하는지, 어떤 상황에서 활용하면 좋은지 살펴보겠습니다.

에이전트 팀이란?

에이전트 팀은 여러 클로드 코드 인스턴스를 하나의 팀으로 조율하는 기능입니다. 우선 팀을 만들고 팀원을 생성하며 전체 작업을 조율하는 메인 세션이 있는데 이걸 팀 리드라고 부릅니다. 그리고 각각 독립적인 클로드 코드 인스턴스로 할당된 태스크를 수행하는 팀원(teammate)이 있죠. 이들은 모든 에이전트가 공유하는 태스크 리스트를 보면서 할 일을 나눠 가지고 메일박스 시스템으로 서로 직접 메시지를 주고받습니다.

핵심은 팀원들이 각자의 컨텍스트 윈도우를 가진다는 점입니다. 하나의 거대한 컨텍스트를 공유하는 게 아니라 각자 독립적으로 작업하면서 필요한 정보만 메시지로 교환하죠. 실제 개발팀에서 각자 자기 모니터를 보면서 Slack으로 소통하는 것과 비슷합니다.

서브에이전트와 뭐가 다른가요?

클로드 코드에는 이미 서브에이전트라는 병렬 작업 기능이 있는데요, 에이전트 팀과는 근본적으로 다릅니다.

서브에이전트는 메인 에이전트가 헬퍼를 잠깐 불러서 일을 시키고 결과만 돌려받는 구조입니다. 헬퍼끼리 서로 대화할 수 없고 메인 에이전트에게만 보고하죠. 빠르고 가볍지만, 복잡한 협업에는 한계가 있습니다.

에이전트 팀은 다릅니다. 팀원들이 서로 직접 메시지를 보낼 수 있고 공유 태스크 리스트를 보면서 자율적으로 일을 조율합니다. 마치 실제 팀처럼 서로 발견한 내용을 공유하고 상대방의 결론에 이의를 제기하기도 하죠.

간단히 말해서 서브에이전트는 “이거 조사해서 알려줘”에 적합하고 에이전트 팀은 “같이 고민하면서 해결하자”에 적합합니다.

에이전트 팀 활성화하기

에이전트 팀은 아직 실험적 기능이라 기본적으로 비활성화되어 있습니다. 사용하려면 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 환경 변수를 설정해야 합니다.

settings.json에서 설정하는 방법이 가장 편합니다.

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

쉘 환경 변수로 설정해도 됩니다.

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

첫 번째 팀 만들기

에이전트 팀을 활성화한 뒤에는 자연어로 Claude에게 팀 구성을 요청하면 됩니다. Claude가 알아서 팀을 만들고 팀원을 생성한 뒤 작업을 분배합니다.

예를 들어 CLI 도구를 설계한다고 해보겠습니다.

개발자가 코드베이스 전체의 TODO 주석을 추적하는 CLI 도구를 설계하려고 해.
에이전트 팀을 만들어서 여러 각도로 탐색해줘.
한 팀원은 UX, 한 팀원은 기술 아키텍처, 한 팀원은 비판적 시각에서 접근해줘.

이 요청이 잘 먹히는 이유가 있습니다. 세 역할이 독립적이라 서로 기다릴 필요 없이 동시에 탐색할 수 있거든요. Claude가 팀을 만들면 공유 태스크 리스트를 생성하고 각 역할에 맞는 팀원을 생성한 뒤 작업을 시작합니다. 팀원들의 탐색이 끝나면 리드가 결과를 종합해서 보여줍니다.

팀원 수나 모델을 직접 지정할 수도 있습니다.

4명의 팀원으로 팀을 만들어서 이 모듈들을 병렬로 리팩토링해줘.
각 팀원은 Sonnet 모델을 사용해.

디스플레이 모드

에이전트 팀은 두 가지 디스플레이 모드를 지원합니다.

먼저 in-process 모드는 모든 팀원이 메인 터미널 안에서 실행되는 방식입니다. Shift+Up/Down으로 팀원을 선택하고 직접 메시지를 보낼 수 있죠. 별도의 설치 없이 어떤 터미널에서든 동작합니다.

반면 split panes 모드는 각 팀원에게 별도의 터미널 패널을 할당합니다. 모든 팀원의 출력을 한눈에 볼 수 있고 패널을 클릭해서 직접 상호작용할 수 있는데요. 이 모드를 사용하려면 tmux나 iTerm2가 필요합니다.

기본값은 "auto"로, 이미 tmux 세션 안에 있으면 split panes를, 아니면 in-process를 사용합니다. 직접 설정하려면 settings.json에서 바꿀 수 있습니다.

{
  "teammateMode": "in-process"
}

CLI 플래그로 일회성 설정도 가능합니다.

claude --teammate-mode in-process

팀원 제어하기

에이전트 팀의 장점 중 하나는 팀원 각각을 세밀하게 제어할 수 있다는 것입니다.

특히 유용한 건 계획 승인을 요구하는 기능인데요. 복잡하거나 위험한 작업에서 팀원이 바로 구현에 들어가지 않고 먼저 계획을 세우게 할 수 있습니다.

인증 모듈을 리팩토링할 아키텍트 팀원을 만들어줘.
코드를 수정하기 전에 먼저 계획 승인을 받도록 설정해.

팀원이 계획을 완성하면 리드에게 승인을 요청하게 됩니다. 리드가 검토해서 승인하면 팀원이 구현을 시작하고 거부하면 피드백과 함께 계획을 다시 세우게 되죠. 승인 기준을 프롬프트에 포함하면 리드의 판단에 영향을 줄 수도 있어요. “테스트 커버리지를 포함하는 계획만 승인해”나 “데이터베이스 스키마를 변경하는 계획은 거부해” 같은 지시가 가능하죠.

또한 delegate 모드도 알아두면 좋습니다. 리드가 가끔 팀원에게 일을 맡기지 않고 직접 구현을 시작하는 경우가 있는데, delegate 모드를 활성화하면 리드를 조율 전용으로 제한할 수 있거든요. 팀을 시작한 뒤 Shift+Tab을 눌러서 전환하면 됩니다.

팀원과 직접 대화하기

에이전트 팀에서 각 팀원은 완전히 독립적인 클로드 코드 세션입니다. 리드를 거치지 않고 팀원에게 직접 메시지를 보내서 추가 지시를 하거나 방향을 수정할 수 있습니다.

In-process 모드에서는 Shift+Up/Down으로 팀원을 선택하고 메시지를 입력합니다. Enter를 누르면 팀원의 세션을 볼 수 있고 Esc를 누르면 현재 작업을 중단시킬 수 있습니다. Ctrl+T로 태스크 리스트를 토글할 수도 있죠.

Split panes 모드에서는 팀원의 패널을 직접 클릭해서 상호작용하면 됩니다.

태스크 할당과 자체 할당

공유 태스크 리스트가 팀 전체의 작업을 조율하는 중심입니다. 태스크는 세 가지 상태를 가집니다. 대기 중(pending), 진행 중(in progress), 완료(completed)로, 태스크 간 의존성도 설정할 수 있어서 선행 태스크가 완료되기 전까지 후행 태스크를 시작할 수 없습니다.

태스크 배분은 두 가지 방식으로 이루어집니다. 리드가 “이 태스크를 이 팀원에게 할당해”라고 명시적으로 지정하거나 팀원이 자기 작업을 끝낸 뒤 아직 할당되지 않은 태스크를 스스로 가져갈 수 있습니다. 여러 팀원이 동시에 같은 태스크를 가져가려는 상황을 방지하기 위해 파일 잠금 방식을 사용합니다.

리드가 충분한 수의 태스크를 만들지 않으면 팀원들이 놀게 될 수 있는데요. 팀원 한 명당 5~6개 정도의 태스크를 만들어두면 모두가 바쁘게 움직이고 누군가 막히더라도 리드가 작업을 재분배할 수 있습니다.

Hooks와 연동하기

클로드 코드 Hooks를 에이전트 팀과 함께 활용하면 팀원이 작업을 마치거나 태스크를 완료할 때 자동으로 품질 검사를 수행할 수 있습니다.

TeammateIdle 이벤트는 팀원이 할 일을 마치고 유휴 상태가 되려 할 때 실행됩니다. 종료 코드 2로 나가면 피드백을 보내면서 팀원을 계속 일하게 만들 수 있죠. 예를 들어 “아직 테스트가 통과하지 않으니 계속 작업해”라는 피드백을 자동으로 보내는 식입니다.

TaskCompleted 이벤트는 태스크가 완료로 표시될 때 실행됩니다. 역시 종료 코드 2로 나가면 완료 처리를 막고 피드백을 전달합니다. 린트 검사나 테스트 실행을 걸어두면 기준을 충족하지 못한 태스크가 섣불리 완료 처리되는 걸 방지할 수 있죠.

실전 활용 사례

에이전트 팀이 빛나는 순간은 병렬로 탐색하는 것이 확실히 가치 있는 작업을 할 때입니다. 두 가지 대표적인 시나리오를 살펴보겠습니다.

먼저 병렬 코드 리뷰를 생각해볼까요? 리뷰어 한 명이 보통 한 번에 한 가지 유형의 문제에 집중하게 되는데요. 리뷰 기준을 독립적인 영역으로 분리해서 여러 리뷰어에게 할당하면 보안, 성능, 테스트 커버리지를 동시에 꼼꼼히 검토할 수 있습니다.

에이전트 팀을 만들어서 PR #142를 리뷰해줘. 세 명의 리뷰어를 만들어:
- 하나는 보안 관점
- 하나는 성능 영향
- 하나는 테스트 커버리지 검증
각자 리뷰하고 결과를 보고하도록 해.

각 리뷰어가 같은 PR을 보면서 서로 다른 렌즈를 적용합니다. 리드는 세 리뷰어의 결과를 종합해서 최종 리뷰를 만들어주죠.

다음으로 경쟁 가설 조사는 버그의 원인이 불분명할 때 특히 유용합니다. 하나의 에이전트가 순차적으로 원인을 조사하면 첫 번째로 찾은 그럴듯한 설명에 매몰되기 쉬운데요. 여러 팀원이 각자 다른 가설을 검증하면서 서로의 결론에 반박하게 하면 진짜 원인을 찾을 가능성이 높아집니다.

사용자들이 앱에서 메시지를 하나 보내면 연결이 끊긴다고 합니다.
5명의 팀원을 만들어서 서로 다른 가설을 조사하게 해줘.
과학 토론처럼 서로의 이론을 반증하도록 해.
합의된 결론을 문서에 업데이트해줘.

이 토론 구조가 핵심입니다. 독립적인 조사자들이 서로의 이론을 적극적으로 반증하려 하기 때문에 살아남은 가설이 실제 원인일 가능성이 훨씬 높아지거든요.

팀 정리하기

작업이 끝나면 리드에게 팀 정리를 요청합니다.

팀을 정리해줘

리드가 정리를 실행하면 공유 리소스가 제거됩니다. 이때 활성 팀원이 남아 있으면 정리가 실패하니까 먼저 팀원들을 종료시켜야 합니다.

리서처 팀원을 종료시켜줘

팀원은 종료 요청을 수락하거나 이유를 설명하며 거부할 수 있습니다. 정리는 반드시 리드를 통해서 해야 합니다. 팀원이 직접 정리를 실행하면 팀 컨텍스트가 제대로 해석되지 않아서 리소스가 꼬일 수 있거든요.

알아두면 좋은 모범 사례

에이전트 팀을 효과적으로 쓰려면 몇 가지 원칙을 따르는 게 좋습니다.

팀원에게 충분한 컨텍스트를 전달하세요. 팀원은 CLAUDE.md와 Skills를 자동으로 로드하지만 리드의 대화 내역은 가져가지 않습니다. 생성 시 프롬프트에 작업에 필요한 구체적인 정보를 포함해야 합니다.

보안 리뷰 팀원을 생성해줘. 프롬프트:
"src/auth/ 디렉토리의 인증 모듈에서 보안 취약점을 찾아줘.
토큰 처리, 세션 관리, 입력 검증에 집중해.
앱에서 httpOnly 쿠키에 JWT 토큰을 저장하고 있어.
심각도 등급과 함께 이슈를 보고해줘."

태스크 크기를 적절하게 잡으세요. 너무 작으면 조율 비용이 이득보다 커지고 너무 크면 팀원이 오래 혼자 작업하다가 방향이 틀어질 수 있습니다. 함수 하나나 테스트 파일 하나처럼 명확한 결과물이 나오는 단위가 적당해요.

파일 충돌을 피하세요. 두 팀원이 같은 파일을 동시에 수정하면 덮어쓰기가 발생합니다. 작업을 분배할 때 각 팀원이 서로 다른 파일을 담당하도록 나눠야 합니다.

팀원이 끝날 때까지 기다리세요. 리드가 가끔 팀원의 작업이 끝나기 전에 직접 구현을 시작할 때가 있는데요. 이럴 때는 “팀원들이 작업을 완료할 때까지 기다려줘”라고 말하면 됩니다.

제한 사항

에이전트 팀은 아직 실험적 기능이라 몇 가지 제한이 있습니다.

In-process 팀원은 세션을 재개할 수 없습니다. /resume이나 /rewind를 사용해도 팀원이 복원되지 않아서 세션을 재개한 뒤 리드에게 새 팀원을 생성하라고 해야 해요. 태스크 상태가 지연될 수도 있는데 팀원이 작업을 실제로 끝냈는데도 태스크를 완료로 표시하지 못하는 경우가 있습니다. 이런 경우 직접 상태를 확인하고 업데이트하거나 리드에게 팀원을 재촉하라고 하면 됩니다.

한 세션에 하나의 팀만 운영할 수 있고 팀원이 자기 팀을 만드는 중첩 구조는 지원되지 않습니다. 팀을 만든 세션이 계속 리드를 맡으며 리드를 교체하거나 팀원을 리드로 승격시키는 것도 불가능하죠. 또한 split panes 모드는 VS Code 통합 터미널이나 Windows Terminal, Ghostty에서는 지원되지 않고 tmux나 iTerm2가 필요합니다.

마치며

에이전트 팀은 AI 코딩 에이전트의 협업을 한 단계 끌어올리는 기능입니다. 하나의 에이전트가 순차적으로 처리하던 작업을 여러 에이전트가 병렬로 수행하면서 단순히 작업을 나누는 것을 넘어 서로 소통하고 조율하는 진정한 팀워크를 구현하죠.

다만 모든 작업에 에이전트 팀이 적합한 건 아닙니다. 토큰 사용량이 크게 늘어나기 때문에 병렬 탐색이 확실히 가치 있는 작업에 사용하는 게 현명해요. 코드 리뷰나 새 기능 설계, 디버깅처럼 여러 시각이 필요한 작업부터 시작해보세요.

처음 써본다면 코드를 건드리지 않는 작업부터 시작하는 걸 추천합니다. PR 리뷰나 라이브러리 조사, 버그 원인 탐색 같은 작업은 팀원 간 파일 충돌 걱정 없이 병렬 탐색의 가치를 체험할 수 있으니까요.

클로드 코드에 대해 더 알고 싶다면 클로드 코드 소개를 참고하시고 커스터마이징에 관심이 있다면 클로드 코드 설정 가이드와 Hooks 가이드도 살펴보세요. 에이전트 팀의 태스크 관리를 더 깊이 이해하고 싶다면 Tasks 가이드를 참고하세요. CI/CD 파이프라인에서 활용하고 싶다면 클로드 코드 GitHub Actions 사용법이 도움이 될 겁니다.