Claude Code 멀티에이전트 완벽 정리: Sub-agents, Agent Teams, Custom Agents
Claude Code 멀티에이전트 완벽 정리: Sub-agents, Agent Teams, Custom Agents
Claude Code는 단일 AI 에이전트가 아닙니다. 여러 AI가 팀을 이뤄 협업하는 멀티에이전트 시스템을 지원합니다. 마치 회사에서 대표가 직접 모든 일을 하지 않고, 팀원에게 업무를 나눠주는 것처럼요. 이 글에서는 Claude Code의 3가지 멀티에이전트 메커니즘인 Sub-agents, Agent Teams, Custom Agents를 비교 분석하고, 실전에서 어떤 상황에 어떤 방식을 선택해야 하는지 알아봅니다.
Sub-agents (Task 도구): 외주를 맡기는 방식
Sub-agents는 메인 에이전트가 하위 작업을 독립된 에이전트에게 위임하고, 결과만 돌려받는 구조입니다.
비유하자면, 대표가 전문 용역사에게 업무를 외주 주는 것과 같습니다. 용역사는 자기 사무실에서 독립적으로 일하고, 완성된 결과물만 납품합니다. 다른 용역사와는 소통하지 않죠.
Sub-agent의 3가지 타입
| 타입 | 도구 접근 권한 | 용도 |
|---|---|---|
general-purpose | 전체 (Read, Write, Edit, Bash) | 코드 구현, 수정, 테스트 실행 |
Explore | 읽기 전용 | 코드베이스 탐색, 구조 파악 |
Plan | 읽기 전용 | 설계 수립, 아키텍처 계획 |
Sub-agents는 Task 도구를 통해 생성됩니다. 각 Sub-agent는 독립된 컨텍스트 윈도우에서 실행되며, 작업이 끝나면 결과만 호출자에게 반환하고 종료됩니다. 다른 Sub-agent와는 통신할 수 없으며, Sub-agent가 또 다른 Sub-agent를 생성하는 것도 불가능합니다 (2계층 제한).
Sub-agents를 선택해야 할 때
- 결과만 필요하고 중간 과정이 중요하지 않을 때
- 독립적인 작업을 병렬로 처리하고 싶을 때
- 토큰 비용을 절약하고 싶을 때
- 예: 코드 리서치, 파일 분석, 단순 코드 생성
Agent Teams: 팀으로 협업하는 방식
Agent Teams는 여러 Claude Code 인스턴스가 팀을 이뤄 실시간으로 소통하며 작업하는 시스템입니다.
비유하자면, 건설 현장에서 현장소장이 전체를 지휘하고, 전기 기술자/배관 기술자/인테리어 담당이 각자의 역할을 수행하면서도 서로 직접 소통하는 것과 같습니다. 현장소장(리더)은 직접 망치를 들지 않고, 조율만 합니다.
Agent Teams의 핵심 구조
Agent Teams는 현재 실험적 기능으로, 환경 변수를 통해 활성화해야 합니다:
# settings.json 또는 환경 변수로 활성화
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
**리더(Lead)**는 작업을 분배하고 조율하며, 직접 코딩은 하지 않습니다. **팀원(Teammates)**은 각자 독립된 컨텍스트에서 작업하면서도, SendMessage를 통해 팀원 간 직접 메시지를 주고받을 수 있습니다.
Agent Teams 라이프사이클
TeamCreate → 팀원 생성 (Task) → TaskCreate (작업 배정)
→ TaskUpdate (담당자 배정) → SendMessage (통신)
→ 작업 수행 → shutdown_request → TeamDelete
표시 모드
| 모드 | 설명 | 요구 사항 |
|---|---|---|
| In-process | 메인 터미널 내 실행, Shift+Up/Down으로 팀원 전환 | 없음 |
| Split panes | tmux/iTerm2에서 팀원별 별도 창 표시 | tmux 또는 iTerm2 |
Agent Teams를 선택해야 할 때
- 팀원 간 논의와 피드백이 필요할 때
- 파일 소유권을 분리하여 병렬 작업할 때
- 코드 작성자와 리뷰어가 직접 소통해야 할 때
- 예: 프론트엔드+백엔드 동시 개발, 코드 작성+리뷰 루프
Sub-agents vs Agent Teams: 핵심 비교
두 방식의 차이를 한눈에 정리하면 다음과 같습니다:
| 비교 항목 | Sub-agents | Agent Teams |
|---|---|---|
| 통신 | 메인 에이전트에게만 보고 | 팀원 간 직접 메시징 가능 |
| 사용자 접근 | 불가능 | 개별 팀원과 직접 대화 가능 |
| 토큰 비용 | 낮음 (결과 요약만 반환) | 3-7배 높음 (각 팀원 별도 컨텍스트) |
| 중첩 | 불가능 (2계층) | 팀원이 Sub-agent 생성 가능 (3계층) |
| 활성화 | 기본 활성화 | 실험적, 수동 활성화 필요 |
| 최적 용도 | 결과만 필요한 집중 작업 | 논의/협업이 필요한 복잡 작업 |
| 최대 인원 | 제한 없음 | 리더 포함 4명 |
선택 의사결정 플로우
작업을 받았을 때 어떤 방식을 선택할지는 3가지 질문으로 판단할 수 있습니다:
- 작업이 병렬화 가능한가? -- NO라면 단일 세션으로 충분
- 팀원 간 논의가 필요한가? -- NO라면 Sub-agents
- 파일 소유권을 분리할 수 있는가? -- YES라면 Agent Teams, NO라면 단일 세션
Google/MIT 연구에 따르면, 병렬 작업에서 Agent Teams는 +81% 성능 향상을 보이지만, 순차적 작업에서는 오히려 -70% 성능 악화가 발생합니다.
Custom Agents: 전문가를 미리 정의하는 방식
Custom Agents는 마크다운 파일로 에이전트의 역할, 도구, 행동 규칙을 미리 정의해두는 방식입니다.
비유하자면, 채용 공고(JD)를 작성해두고, 필요할 때 해당 역할의 전문가를 즉시 투입하는 것과 같습니다. 한 번 정의하면 언제든 재사용할 수 있죠.
Custom Agent 정의 예시
---
name: code-reviewer
description: Expert code reviewer
model: sonnet
tools: [Read, Grep, Glob, Bash]
---
당신은 전문 코드 리뷰어입니다.
보안, 성능, 가독성 관점에서 코드를 분석하세요.
저장 위치와 우선순위
| 위치 | 범위 | 우선순위 |
|---|---|---|
.claude/agents/ | 프로젝트별 | 높음 |
~/.claude/agents/ | 사용자 전역 | 낮음 |
Custom Agent 실행 방법
# CLI에서 직접 실행
claude --agent code-reviewer
# Headless 모드로 실행 (CI/CD 연동)
claude --agent security-auditor -p "이 코드의 보안 취약점을 분석해주세요"
Frontmatter 주요 필드
| 필드 | 설명 |
|---|---|
name | 에이전트 식별자 |
description | 역할 설명 (자동 위임 매칭에 사용) |
model | 사용할 모델 (opus, sonnet, haiku) |
tools | 사용 가능한 도구 목록 |
maxTurns | 최대 실행 턴 수 |
permissionMode | 권한 모드 설정 |
Headless Mode: 자동화의 완성
Claude Code는 -p 플래그를 통해 비대화형으로 실행할 수 있습니다. 이를 통해 CI/CD 파이프라인이나 크론 작업에 Claude Code를 연결할 수 있죠.
# 단순 실행
claude -p "이 코드베이스를 설명해주세요"
# Custom Agent + Headless
claude --agent security-auditor -p "인증 모듈 보안 감사"
# JSON 출력 (파싱용)
claude --output-format json -p "함수 목록 추출"
TypeScript와 Python SDK를 통해 프로그래밍적으로 호출하는 것도 가능합니다. 이를 통해 Sub-agents, Agent Teams, Custom Agents를 코드 레벨에서 조합할 수 있습니다.
실전 활용 시나리오
시나리오 1: 코드 리팩토링
- Custom Agent로
refactor-planner정의 - Planner가 Sub-agents로 각 모듈 분석 (병렬)
- 분석 결과를 바탕으로 Agent Teams 구성 (구현2명 + 테스트1명)
- 팀원 간 직접 소통으로 인터페이스 조율
시나리오 2: 콘텐츠 생성 파이프라인
- Sub-agent로 리서치 수행 (결과만 반환)
- Agent Teams로 콘텐츠 팀 구성 (writer + reviewer)
- Reviewer가 Writer에게 직접 피드백 (품질 루프)
- Headless Mode로 후처리 자동화
시나리오 3: CI/CD 통합
- Custom Agent
security-auditor정의 - GitHub Actions에서 Headless Mode로 PR마다 자동 실행
- 결과를 JSON으로 받아 리포트 생성
자주 묻는 질문 (FAQ)
Q: Agent Teams는 안정적으로 사용할 수 있나요?
Agent Teams는 현재 실험적 기능입니다. CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1로 활성화해야 하며, 프로덕션 환경보다는 개발/실험 환경에서 사용하는 것을 권장합니다. 알려진 제한사항으로는 세션 재개 불가, 세션당 1팀 제한 등이 있습니다.
Q: Sub-agent가 다른 Sub-agent를 만들 수 있나요?
아니요. Sub-agent는 2계층까지만 가능합니다 (메인 -> Sub-agent). 하지만 Agent Teams의 팀원은 자신의 Sub-agent를 생성할 수 있어 3계층 구조 (리더 -> 팀원 -> Sub-agent)가 가능합니다.
Q: 토큰 비용은 얼마나 차이 나나요?
Sub-agents는 결과 요약만 반환하므로 비용이 낮습니다. Agent Teams는 각 팀원이 독립된 컨텍스트 윈도우를 가지므로, 활성 팀원 수에 비례하여 3-7배 더 많은 토큰을 사용합니다. 일상적 작업은 단일 세션이 가장 비용 효율적입니다.
Q: Custom Agents와 Sub-agents의 관계는 무엇인가요?
Custom Agents는 에이전트의 역할 정의(JD)이고, Sub-agents/Agent Teams는 실행 방식입니다. Custom Agent로 정의한 에이전트를 Sub-agent로 실행할 수도 있고, Agent Teams의 팀원으로 투입할 수도 있습니다. 정의와 실행은 독립적입니다.
마무리: 3가지를 조합하는 것이 핵심
Claude Code의 멀티에이전트 시스템은 Sub-agents(외주), Agent Teams(팀 협업), Custom Agents(역할 정의) 3가지로 구성됩니다. 각각의 강점이 다르기 때문에, 상황에 맞게 조합하는 것이 핵심입니다.
- 결과만 필요하면 Sub-agents
- 논의와 협업이 필요하면 Agent Teams
- 반복 사용할 전문가는 Custom Agents로 정의
AI가 혼자 일하는 시대에서, AI 팀이 협업하는 시대로 전환되고 있습니다. Claude Code의 멀티에이전트 기능을 활용하면, 복잡한 개발 작업도 체계적으로 분해하고 병렬 처리할 수 있습니다.
