핵심 요약
에이전트 팀은 병렬 작업과 도메인별 전문화에 최적화되어 있으며, 적절한 가이드와 제어를 통해 복잡한 아키텍처 설계부터 디버깅까지 개발 전 과정을 가속화할 수 있다.
배경
Claude Code는 단일 에이전트 실행을 넘어 여러 에이전트가 협업하는 '에이전트 팀' 기능을 통해 복잡한 프로젝트를 처리할 수 있는 환경을 제공한다.
대상 독자
AI 코딩 도구를 실무 워크플로우에 깊이 있게 통합하려는 소프트웨어 엔지니어 및 테크 리드
의미 / 영향
Claude Code의 에이전트 팀 기능은 개발자가 단순 코딩을 넘어 AI 팀을 지휘하는 오케스트레이터로 진화하게 만든다. 병렬 처리를 통해 복잡한 프로젝트의 리드 타임을 획기적으로 줄일 수 있으며, 전문화된 에이전트들의 협업으로 코드 품질과 보안성을 동시에 확보할 수 있는 실무 환경이 구축될 것이다.
챕터별 상세
00:43
에이전트 팀의 개념과 하위 에이전트와의 차이
에이전트 팀은 하나의 리드 에이전트와 여러 명의 팀원으로 구성된 오케스트레이션 구조이다. 일반적인 하위 에이전트(Subagents)가 메인 에이전트에게만 보고하는 것과 달리, 팀원들은 서로 직접 메시지를 주고받으며 작업 목록을 공유하고 자율적으로 협업한다. 각 팀원은 독립적인 컨텍스트를 가지며 리드 에이전트가 할당한 태스크를 병렬로 처리한다. 결과적으로 단순한 작업 대행을 넘어 복잡한 문제 해결을 위한 협업 체계를 구축한다.
- •리드 에이전트가 태스크를 할당하고 팀원들이 병렬로 실행하는 구조이다
- •팀원 간 직접 통신이 가능하며 공유된 태스크 리스트를 기반으로 움직인다
- •하위 에이전트는 결과 중심, 에이전트 팀은 협업과 병렬 탐색에 최적화되어 있다
06:48
에이전트 팀 활성화 및 기본 설정
에이전트 팀 기능은 현재 실험적 단계이므로 settings.json 파일에서 직접 활성화해야 한다. CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 환경 변수를 1로 설정한 후 Claude Code를 재시작하면 기능을 사용할 수 있다. 사용자는 자연어를 통해 원하는 팀 구성을 설명하기만 하면 Claude가 자동으로 필요한 역할의 에이전트들을 생성한다. 설정 과정에서 공식 문서를 참고하여 필요한 환경 변수를 정확히 입력하는 것이 중요하다.
- •settings.json에서 실험적 기능 플래그를 활성화해야 사용 가능하다
- •자연어 프롬프트만으로 UX, 아키텍처 등 특정 역할을 가진 팀을 즉시 생성한다
- •설정 변경 후에는 반드시 Claude Code 인스턴스를 재시작해야 적용된다
json
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}settings.json 파일에서 에이전트 팀 실험적 기능을 활성화하는 설정
08:42
에이전트별 모델 지정 및 비용 최적화
에이전트 팀의 각 팀원에게 서로 다른 Claude 모델을 할당하여 성능과 비용의 균형을 맞출 수 있다. 예를 들어 복잡한 로직이 필요한 디버거에는 Opus 모델을, 단순한 UI 작업에는 Haiku 모델을 지정하는 방식이다. 에이전트 팀은 여러 인스턴스를 동시에 실행하므로 단일 에이전트보다 토큰 소모가 훨씬 빠르다. 따라서 모든 팀원에게 고성능 모델을 할당하기보다 태스크의 난이도에 맞춰 모델을 분배하는 전략이 필수적이다.
- •Opus, Sonnet, Haiku 등 태스크 성격에 맞는 모델을 팀원별로 지정 가능하다
- •병렬 작업 특성상 토큰 비용이 급격히 상승할 수 있음을 인지해야 한다
- •비용 민감도가 높다면 단순 작업 에이전트에는 경량 모델을 우선 배정한다
text
Create an agent team with one teammate on UX, one on architecture, one playing devil's advocate.자연어를 사용하여 특정 역할을 가진 에이전트 팀을 생성하는 프롬프트 예시
text
For the agent team, make sure the debugger runs on opus-4.6, the ui-perf runs on sonnet, and the ux-quality runs on haiku.각 에이전트 팀원별로 서로 다른 Claude 모델을 지정하는 프롬프트 예시
09:24
디스플레이 모드와 tmux 활용
에이전트 팀의 작업 과정을 확인하는 방식은 두 가지이다. 기본 모드인 'In-process'는 하나의 터미널에서 탭을 전환하며 각 에이전트의 상태를 확인하는 방식이다. 반면 'Split panes' 모드는 tmux를 활용하여 화면을 분할하고 모든 에이전트의 로그를 실시간으로 동시에 모니터링한다. 대화면 모니터를 사용하는 환경에서는 tmux 설정을 통해 팀 전체의 진행 상황을 한눈에 파악하는 것이 효율적이다. 설정 파일에서 teammode를 tmux로 지정하여 이 기능을 활성화한다.
- •In-process 모드는 단일 터미널에서 에이전트 간 탭 전환으로 상태를 확인한다
- •tmux 연동 시 화면 분할을 통해 모든 팀원의 작업을 실시간 동시 모니터링한다
- •대규모 프로젝트에서는 분할 화면 모드가 전체 워크플로우 파악에 유리하다
11:52
태스크 관리 및 에이전트 제어 라이프사이클
에이전트 팀은 공유된 태스크 리스트를 중심으로 작동하며 사용자는 Ctrl+T를 눌러 전체 진행 상황을 확인할 수 있다. 리드 에이전트가 계획을 수립하면 팀원들이 태스크를 스스로 가져가거나(self-claim) 할당받아 실행한다. 작업이 완료되거나 일정 시간 유휴 상태가 되면 에이전트는 자동으로 종료된다. 사용자는 리드 에이전트를 통해 팀 전체의 승인 기준을 설정하거나 작업을 중단시키는 등 중앙 집중식 제어를 수행한다. 특히 구현 시작 전 반드시 계획(Plan)을 검토하도록 설정하는 것이 품질 관리에 중요하다.
- •공유 태스크 리스트를 통해 작업의 의존성과 진행 상태를 관리한다
- •유휴 상태의 에이전트는 시스템 자원 절약을 위해 자동으로 종료된다
- •리드 에이전트를 통해 팀 전체의 품질 게이트와 승인 절차를 제어한다
19:05
실무 적용 베스트 프랙티스
효율적인 팀 운영을 위해 팀원 수는 3-5명, 에이전트당 태스크는 5-6개로 제한하는 것이 좋다. 팀원 수가 너무 많으면 관리 오버헤드와 토큰 비용이 기하급수적으로 증가하기 때문이다. 또한 에이전트들이 동일한 파일을 동시에 수정하여 충돌이 발생하는 것을 방지하기 위해 작업 범위를 명확히 분리해야 한다. 리드 에이전트에게 충분한 컨텍스트를 제공하고, 에이전트가 직접 코드를 수정하기 전에 계획을 먼저 보고하도록 유도하여 실수를 줄인다.
- •팀 규모를 3-5명으로 유지하여 관리 효율성과 비용을 최적화한다
- •파일 수정 충돌을 피하기 위해 에이전트별 작업 도메인을 엄격히 분리한다
- •읽기 전용 태스크부터 시작하여 에이전트 팀의 특성을 파악하는 것을 권장한다
22:37
주요 활용 사례: 코드 리뷰 및 디버깅
에이전트 팀은 병렬 코드 리뷰와 복합적인 디버깅에서 강력한 성능을 발휘한다. 보안, 성능, 테스트 커버리지 등 각기 다른 관점을 가진 리뷰어 에이전트들을 배치하여 다각도의 검토 결과를 한 번에 얻을 수 있다. 디버깅 시에는 여러 가설을 각각의 에이전트에게 할당하여 병렬로 검증하게 함으로써 문제의 근본 원인을 빠르게 찾아낸다. 이는 단일 에이전트가 가질 수 있는 컨텍스트 편향을 방지하고 객관적인 분석 결과를 도출하는 데 도움을 준다.
- •보안, 성능 등 전문 분야별 에이전트를 배치하여 병렬 코드 리뷰를 수행한다
- •상충하는 가설을 여러 에이전트에게 할당하여 디버깅 속도와 객관성을 높인다
- •에이전트 간 컨텍스트 분리를 통해 특정 해결책에 대한 편향을 방지한다
실무 Takeaway
- 복잡한 풀스택 개발 시 프론트엔드, 백엔드, 아키텍처 에이전트로 팀을 구성하여 개발 주기를 단축한다.
- 에이전트 팀 규모를 3-5명으로 유지하고 에이전트당 태스크를 6개 이하로 관리하여 토큰 비용과 오버헤드를 최적화한다.
- 디버깅 시 여러 에이전트에게 서로 다른 가설을 검증하게 하여 단일 모델의 확증 편향을 극복하고 정확한 원인을 파악한다.
- tmux를 연동한 분할 화면 모드를 활용하여 여러 에이전트의 병렬 작업 과정을 실시간으로 모니터링하고 제어한다.
AI 분석 전체 내용 보기
AI 요약 · 북마크 · 개인 피드 설정 — 무료