Claude Code Agent Teams(Swarms) - 멀티 에이전트 협업 아키텍처 가이드
목차
개요
2026년 2월 5일 Claude Code에 에이전트 팀(Agent Teams), 즉 스웜(Swarms) 기능이 도입되었다. 이는 리드 에이전트가 전문화된 팀원들에게 작업을 위임하고, 팀원들이 병렬로 협업하는 멀티 에이전트 시스템이다. 단일 에이전트의 순차 처리에서 분산 협업으로의 근본적인 전환을 의미한다.
단일 에이전트의 한계
LLM은 컨텍스트가 확장될수록 성능이 저하된다. 집중된 작업에 관련 없는 정보를 추가하면 오히려 성능이 떨어진다. 인간 팀이 전문화를 통해 이 문제를 해결하는 것처럼, 에이전트 팀은 각 에이전트에 좁은 범위와 전용 컨텍스트를 부여하여 이 원칙을 구현한다. 백엔드 엔지니어가 프론트엔드 리뷰에 참석하지 않는 것과 같은 원리다.
아키텍처 구성 요소
핵심 컴포넌트
| 컴포넌트 | 역할 |
|---|---|
| Team Lead | 작업 조율, 팀원 생성, 의존성 관리 |
| Teammates | 독립 Claude Code 인스턴스, 전용 컨텍스트 윈도우 보유 |
| Task List | 의존성 추적 및 자동 언블로킹이 가능한 공유 작업 목록 |
| Mailbox System | 에이전트 간 직접 메시징 시스템 |
Team Lead가 전체 작업을 조율하고 팀원을 생성한다. 각 팀원은 독립적인 Claude Code 인스턴스로 동작하며, 자체 컨텍스트 윈도우를 가진다. Task List를 통해 작업 항목의 의존성을 추적하고 자동으로 차단을 해제한다. Mailbox System은 부모 에이전트를 경유하지 않고 팀원 간 직접 메시지를 주고받을 수 있게 한다.
서브에이전트 vs 에이전트 팀
서브에이전트(Subagents)
서브에이전트는 결과를 단일 부모에게 보고한다. 통신 흐름이 위로만 향하는 단방향 구조다.
에이전트 팀(Agent Teams)
에이전트 팀은 팀원 간 직접 메시지 전송이 가능하다. 공유 작업 목록에서 독립적으로 협업한다. 토큰 비용은 더 높지만 진정한 협업을 가능하게 한다.
비교 요약
| 항목 | 서브에이전트 | 에이전트 팀 |
|---|---|---|
| 통신 방향 | 부모에게만 보고 | 팀원 간 직접 통신 |
| 작업 관리 | 부모가 전담 | 공유 작업 목록 |
| 협업 수준 | 제한적 | 독립적 협업 |
| 토큰 비용 | 낮음 | 높음 (선형 증가) |
최적 활용 사례
경쟁 가설 디버깅
5개의 에이전트가 서로 다른 장애 원인을 동시에 조사한다. 각 에이전트가 서로의 가정을 검증하고 반박하며 근본 원인을 빠르게 찾아낸다.
병렬 코드 리뷰
보안, 성능, 테스트 커버리지를 각각 전문 에이전트가 동시에 검토한다. 순차적으로 진행하면 걸리는 시간을 대폭 단축할 수 있다.
크로스 레이어 기능 개발
프론트엔드, 백엔드, 테스트 팀원이 명확한 경계를 두고 병렬로 작업한다. 파일 소유권을 분리하여 충돌을 방지한다.
리서치 탐색
여러 조사 에이전트가 동시에 탐색하여 순차적 탐색보다 빠르게 솔루션에 수렴한다.
설정 및 제어 메커니즘
활성화 방법
settings.json에서 다음과 같이 설정한다.
1
2
3
4
5
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
팀 구조는 자연어로 지정할 수 있다. 예를 들어 “인증 시스템을 보안, 성능, 아키텍처 관점에서 리뷰할 3명의 팀원을 생성해줘”와 같이 요청한다.
제어 옵션
| 옵션 | 설명 |
|---|---|
| Display modes | 인프로세스(기본) 또는 분할 패널(tmux/iTerm2) |
| Plan approval | 팀원이 구현 전 계획 승인 요구 |
| Delegate mode | 리드를 조율 전용으로 제한 |
| Direct messaging | 리드를 거치지 않고 팀원에게 직접 메시지 |
| Task management | 명시적 할당 또는 자기 주장 방식의 의존성 해결 |
Plan approval을 활성화하면 팀원이 코드를 작성하기 전에 계획을 세우고 승인을 받아야 한다. Delegate mode는 리드가 직접 코드를 작성하지 않고 조율에만 집중하도록 제한한다.
팀 운영 원칙
효과적인 에이전트 팀 운영은 인간 팀 관리와 유사한 원칙을 따른다.
작업 크기 조정
너무 작은 작업은 조율 오버헤드를 발생시키고, 너무 큰 작업은 중간 점검을 어렵게 한다. 팀원당 5-6개의 작업이 적정 수준이다.
파일 소유권 분리
각 팀원이 서로 다른 파일을 담당해야 머지 충돌을 방지할 수 있다. 동일 파일을 여러 팀원이 수정하면 충돌이 발생할 위험이 높다.
컨텍스트 로딩
대화 이력에 의존하지 말고 팀원 생성 시 작업별 브리프를 포함해야 한다. 명확한 컨텍스트를 제공할수록 팀원의 작업 품질이 높아진다.
활동량과 가치의 구분
활동량이 항상 가치로 이어지지는 않는다. 멀티 에이전트 시스템은 대량의 코드를 생산할 수 있지만, 정확성이나 유지보수성이 보장되지는 않는다. 문제 요구사항이 아키텍처 선택을 가이드해야 하며, 순차적 작업에는 단일 세션이 오히려 나을 수 있다.
제한 사항
- 세션당 하나의 팀만 운영 가능하며 중첩 팀은 지원하지 않는다
- 인프로세스 팀원은 /resume 후 복원되지 않는다
- 분할 패널은 tmux 또는 iTerm2에서만 가능하며 VS Code나 Windows Terminal에서는 사용할 수 없다
- 토큰 비용이 팀원 수에 비례하여 선형으로 증가한다
- 작업 완료 상태 표시가 지연되어 의존 작업이 차단될 수 있다
- 모든 팀원이 리드의 보안 설정을 상속한다
시작 가이드
에이전트 팀을 처음 도입할 때는 단계적으로 접근하는 것이 좋다.
- 경계가 명확한 리서치 작업부터 시작한다 (코드 변경 없이)
- 서로 다른 관점의 병렬 코드 리뷰로 확장한다
- 명확한 소유권이 있는 크로스 레이어 기능 개발을 시도한다
- 사전 명세가 충분한 전체 리팩토링으로 확대한다
Compound Engineering Plugin을 활용하면 계획과 리뷰 80%, 실행 20%의 구조화된 워크플로우를 적용할 수 있다. 전문 리뷰 에이전트와 학습 문서를 통해 이후 에이전트 성능을 지속적으로 개선할 수 있다.
결론
에이전트 팀은 이론이 아닌 프로덕션 수준의 멀티 에이전트 협업 아키텍처다. 성공적인 활용을 위해서는 적절한 작업 분해, 명확한 명세, 그리고 병렬 전문가가 순차 처리보다 우수한 시점을 판단하는 능력이 필요하다. 모든 작업에 멀티 에이전트가 적합한 것은 아니므로, 문제의 특성에 맞는 아키텍처를 선택하는 것이 핵심이다.