Claude Code의 에이전트는 세 가지 레벨로 구분됩니다.
- 메인 에이전트: 사용자와 직접 대화하는 기본 Claude Code 인스턴스
- 서브에이전트: 메인 에이전트가 특정 작업을 위임하는 하위 에이전트. 독립 컨텍스트에서 실행
- Agent Teams: 여러 에이전트가 역할을 나누어 협업하는 팀 단위 시스템 (2026.02~)
Claude Code 가이드 #5 — 에이전트 & 서브에이전트
Multi-Agent 코드 리뷰 시스템, 에이전트 파일 구성, 병렬 실행과 결과 취합 방법을 다룬다. 서브에이전트 생성, Task 분배, worktree 격리 실행까지 실전 패턴을 정리한다.
Claude Code의 에이전트 시스템은 2026년 들어 대폭 강화되었습니다. 기존 서브에이전트에 더해 Agent Teams(2026.02 출시)가 추가되어, 여러 에이전트가 협업하는 멀티에이전트 워크플로우가 가능해졌습니다. 이 편에서는 서브에이전트부터 Agent Teams까지 전체 에이전트 시스템을 정리합니다.
에이전트 시스템 개요
💡 핵심 차이: 서브에이전트는 메인 에이전트의 "도구"로 동작하고, Agent Teams는 독립적인 에이전트들이 서로 통신하며 협업합니다. 서브에이전트는 서브에이전트를 생성할 수 없지만, Agent Teams의 멤버는 각자 서브에이전트를 가질 수 있습니다.
서브에이전트 — 작업 위임
서브에이전트는 마크다운 프론트매터로 정의됩니다. .claude/agents/ 디렉토리에 파일을 생성하고, /agents 명령어로 목록을 확인합니다.
에이전트 파일 예시 (.claude/agents/security-reviewer.md)--- name: Security Reviewer model: claude-sonnet-4-6 tools: - Read - Grep - Glob --- # 역할 코드의 보안 취약점을 검토합니다. # 체크리스트 - SQL 인젝션 - XSS - 인증/인가 이슈 - 하드코딩된 시크릿 - OWASP Top 10
서브에이전트의 핵심 특성:
- 메인 에이전트와 별도 컨텍스트에서 실행 (메인 컨텍스트 오염 방지)
- 지정된 도구만 사용 가능 (보안 격리)
- 서브에이전트는 서브에이전트를 생성할 수 없음 (무한 재귀 방지)
- 결과를 메인 에이전트에 반환하여 취합
병렬 리뷰 실행claude --agent security-reviewer.md review src/ claude --agent performance-reviewer.md review src/ claude --agent style-reviewer.md review src/
⚠️ 막히는 케이스: 서브에이전트가 무한 루프처럼 보이면, 에이전트 파일의 역할 정의가 모호하기 때문입니다. "XX를 찾아서 YY 형식으로 보고하라"처럼 종료 조건을 명확히 하세요.
Agent Teams — 멀티에이전트 협업
Agent Teams는 2026년 2월에 출시된 실험적 기능입니다. 여러 에이전트가 각자 역할을 맡아 동시에 작업하고, 서로 메시지를 주고받으며 협업합니다.
Agent Teams 활성화# 환경 변수로 실험 기능 활성화 export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
Agent Teams의 핵심 구성요소:
- 팀 리더: 작업을 분배하고 결과를 취합하는 코디네이터 역할
- 팀 멤버: 각자 전문 영역(프론트엔드, 백엔드, 테스트 등)을 담당
- 메시지 버스: 에이전트 간 통신 채널. 진행 상황 공유, 질문, 결과 전달
- 태스크 보드: 전체 작업의 진행 상태를 추적
⚠️ 막히는 케이스: Agent Teams가 활성화되지 않는다면 환경 변수 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1을 확인하세요. 아직 실험 단계이므로 기본 비활성화 상태입니다.
Agent SDK — 커스텀 에이전트 빌드
더 복잡한 에이전트 시스템이 필요하면 Claude Agent SDK(TypeScript/Python)를 사용합니다. 커스텀 도구, 외부 API 연동, 복잡한 워크플로우를 프로그래밍 방식으로 구축할 수 있습니다.
Agent SDK 기본 구조 (TypeScript)import { Agent } from '@anthropic-ai/claude-agent-sdk'; const reviewer = new Agent({ name: 'Code Reviewer', model: 'claude-sonnet-4-6', tools: ['read_file', 'search'], instructions: 'Review code for bugs and suggest fixes.' }); const result = await reviewer.run('Review the auth module');
Agent SDK는 Claude Code의 에이전트 파일(.md)보다 유연하지만, 설정이 복잡합니다. 단순 작업은 에이전트 파일, 프로덕션 파이프라인은 Agent SDK를 권장합니다.
에이전트 방식 비교
| 항목 | 서브에이전트 | Agent Teams | Agent SDK |
|---|---|---|---|
| 설정 난이도 | 낮음 (.md 파일) | 중간 (환경 변수 + 팀 구성) | 높음 (코드 작성) |
| 에이전트 간 통신 | 불가 (결과만 반환) | 메시지 버스 | 완전 커스텀 |
| 재귀 생성 | 불가 | 멤버별 서브에이전트 가능 | 제한 없음 |
| 적합한 상황 | 단일 작업 위임 | 팀 단위 협업 | 프로덕션 파이프라인 |
| 상태 | 정식 | 실험적 (2026.02~) | 정식 |
⚠️ 막히는 케이스: AGENTS.md를 자동 생성하면 오히려 비용이 약 20% 증가한다는 보고가 있습니다. 에이전트 파일은 실제 필요한 역할만 수동으로 정의하세요.
다음 편에서는 GitHub Actions 연동을 다룹니다. PR 자동 리뷰와 CI/CD 통합을 설정하는 방법을 알아봅니다.
claude-code클로드 코드에이전트서브에이전트코드리뷰