서브 에이전트 (Sub-agents)
읽는 시간: 13분 | 난이도: 고급자
Claude Code의 서브 에이전트 시스템을 활용하여 특수화된 작업을 효율적으로 위임하고 병렬 처리하는 방법을 배웁니다.
개요
서브 에이전트는 특정 작업에 특화된 전문가 AI 에이전트입니다. 메인 에이전트가 작업을 분석하고 적절한 서브 에이전트에게 위임하여 병렬 처리와 전문성을 달성합니다.
1. 서브 에이전트 기초 (Sub-agent Basics)
1.1 서브 에이전트란?
서브 에이전트는 특정 도메인이나 작업 유형에 특화된 AI 에이전트입니다:
서브 에이전트 구조:
[메인 에이전트]
↓ 작업 분석
↓
├── [개발자 에이전트] → 코드 작성
├── [테스터 에이전트] → 테스트 작성
├── [리뷰어 에이전트] → 코드 리뷰
└── [문서작성가 에이전트] → 문서 생성
1.2 내장 서브 에이전트
Claude Code는 다음과 같은 내장 서브 에이전트를 제공합니다:
내장 서브 에이전트:
1. 개발자 (Developer)
- 코드 작성 및 수정
- 리팩토링
- 버그 수정
2. 테스터 (Tester)
- 테스트 코드 작성
- 테스트 전략 수립
- 테스트 실행 및 분석
3. 리뷰어 (Reviewer)
- 코드 리뷰
- 품질 검사
- 베스트 프랙티스 제안
4. 아키텍트 (Architect)
- 시스템 설계
- 기술 스택 선정
- 패턴 및 구조 제안
5. 문서작성가 (Writer)
- 문서 작성
- README 생성
- API 문서화
6. 디버거 (Debugger)
- 버그 분석
- 문제 진단
- 해결책 제안
2. 서브 에이전트 사용법 (Using Sub-agents)
2.1 명시적 위임
# 개발자 에이전트에게 코드 작성 요청
"개발자 에이전트에게 위임: 사용자 인증 컴포넌트를 작성해줘"
# 테스터 에이전트에게 테스트 작성 요청
"테스터 에이전트에게 위임: 이 컴포넌트의 테스트를 작성해줘"
# 리뷰어 에이전트에게 코드 리뷰 요청
"리뷰어 에이전트에게 위임: 이 PR을 리뷰해줘"
2.2 자동 위임
# 메인 에이전트가 자동으로 적절한 서브 에이전트 선택
"전자상거래 앱을 만들어줄래?"
# 메인 에이전트 분석:
# 1. 아키텍트 에이전트: 시스템 설계
# 2. 개발자 에이전트: 코드 구현
# 3. 테스터 에이전트: 테스트 작성
# 4. 문서작성가 에이전트: 문서 생성
2.3 병렬 위임
# 여러 서브 에이전트에게 동시에 작업 위임
"다음을 병렬로 처리해줘:
1. 개발자 에이전트: 새로운 API 엔드포인트 구현
2. 테스터 에이전트: 기존 기능 테스트
3. 리뷰어 에이전트: 코드 품질 검사
4. 문서작성가 에이전트: API 문서 업데이트"
3. 커스텀 서브 에이전트 (Custom Sub-agents)
3.1 서브 에이전트 정의
# .claude/agents/security-expert.yaml
name: "security-expert"
description: "보안 전문가 에이전트"
role: |
당신은 보안 전문가입니다. 코드의 보안 취약점을 분석하고
개선 방안을 제시합니다.
capabilities:
- "보안 취약점 스캔"
- "코드 보안 강화"
- "보안 패턴 제안"
- "취약점 보고서 작성"
expertise:
- "OWASP Top 10"
- "일반적인 보안 취약점"
- "암호화 best practices"
- "인증/인가 패턴"
tools:
- "security_scanner"
- "dependency_checker"
- "secrets_detector"
context_requirements:
- "코드베이스 전체 접근"
- "의존성 목록"
- "환경 설정 파일"
3.2 서브 에이전트 등록
# .claude/agents/registry.yaml
agents:
- name: "security-expert"
file: ".claude/agents/security-expert.yaml"
enabled: true
- name: "performance-optimizer"
file: ".claude/agents/performance-optimizer.yaml"
enabled: true
- name: "database-specialist"
file: ".claude/agents/database-specialist.yaml"
enabled: true
3.3 전문화된 에이전트 예시
# .claude/agents/performance-optimizer.yaml
name: "performance-optimizer"
description: "성능 최적화 전문가"
role: |
당신은 성능 최적화 전문가입니다. 코드의 성능 병목을
찾아내고 최적화 방안을 제시합니다.
specialization:
- "렌더링 최적화"
- "메모리 사용 최적화"
- "네트워크 요청 최적화"
- "데이터베이스 쿼리 최적화"
optimization_patterns:
- pattern: "memoization"
description: "불필요한 재계산 방지"
- pattern: "lazy_loading"
description: "지연 로딩으로 초기 로딩 시간 감소"
- pattern: "debouncing"
description: "빈번한 이벤트 처리 최적화"
analysis_tools:
- "profiler"
- "performance_monitor"
- "memory_analyzer"
4. 에이전트 오케스트레이션 (Agent Orchestration)
4.1 순차적 실행
# .claude/workflows/sequential.yaml
name: "feature-development"
description: "새로운 기능 개발 파이프라인"
steps:
# 1단계: 설계
- agent: "architect"
task: "시스템 아키텍처 설계"
output: "architecture.md"
# 2단계: 개발
- agent: "developer"
task: "코드 구현"
depends_on: "architecture.md"
output: "source_code"
# 3단계: 테스트
- agent: "tester"
task: "테스트 작성 및 실행"
depends_on: "source_code"
output: "test_results"
# 4단계: 리뷰
- agent: "reviewer"
task: "코드 리뷰"
depends_on: "source_code"
output: "review_report"
# 5단계: 문서화
- agent: "writer"
task: "문서 작성"
depends_on: ["source_code", "architecture.md"]
output: "documentation"
4.2 병렬 실행
# .claude/workflows/parallel.yaml
name: "comprehensive-analysis"
description: "종합적인 코드 분석"
steps:
# 병렬 실행
- parallel:
# 보안 분석
- agent: "security-expert"
task: "보안 취약점 분석"
# 성능 분석
- agent: "performance-optimizer"
task: "성능 병목 분석"
# 코드 품질 분석
- agent: "reviewer"
task: "코드 품질 검사"
# 테스트 커버리지
- agent: "tester"
task: "테스트 커버리지 분석"
# 결과 집계
- agent: "architect"
task: "종합 보고서 작성"
aggregate: true
4.3 조건부 실행
# .claude/workflows/conditional.yaml
name: "smart-review"
description: "조건부 리뷰 프로세스"
steps:
# 코드 크기 확인
- check: "code_size"
condition:
- if: "lines > 1000"
then:
# 대규모: 전체 리뷰
- agent: "reviewer"
task: "전체 코드 리뷰"
thorough: true
- if: "lines <= 1000"
then:
# 소규모: 빠른 리뷰
- agent: "reviewer"
task: "빠른 코드 리뷰"
focus: "critical_issues"
5. 에이전트 커뮤니케이션 (Agent Communication)
5.1 메시지 전달
# .claude/agents/communication.yaml
communication:
# 에이전트 간 메시지
messages:
- from: "developer"
to: "tester"
type: "code_ready"
content: "코드가 준비되었습니다. 테스트를 작성해주세요"
- from: "tester"
to: "developer"
type: "test_failed"
content: "테스트가 실패했습니다. 버그를 수정해주세요"
# 상태 공유
state_sharing:
enabled: true
shared_state:
- "test_results"
- "code_coverage"
- "performance_metrics"
5.2 협업 워크플로우
# .claude/workflows/collaborative.yaml
name: "bug-fix-collaboration"
description: "협업 버그 수정"
steps:
# 1. 디버거가 문제 분석
- agent: "debugger"
task: "버그 원인 분석"
output: "bug_report"
# 2. 개발자가 수정
- agent: "developer"
task: "버그 수정"
input: "bug_report"
output: "fixed_code"
notify: ["tester", "reviewer"]
# 3. 테스터가 검증
- agent: "tester"
task: "수정 사항 테스트"
input: "fixed_code"
output: "test_results"
notify: ["developer"]
# 4. 리뷰어가 최종 검토
- agent: "reviewer"
task: "최종 코드 리뷰"
input: ["fixed_code", "test_results"]
output: "final_approval"
6. 에이전트 모니터링 (Agent Monitoring)
6.1 실행 추적
# .claude/agents/monitoring.yaml
monitoring:
# 에이전트 실행 로그
logging:
enabled: true
level: "info"
include:
- "agent_name"
- "task_description"
- "start_time"
- "end_time"
- "duration"
- "status"
- "output"
# 성능 메트릭
metrics:
- "execution_time"
- "memory_usage"
- "success_rate"
- "error_count"
6.2 상태 대시보드
# 에이전트 상태 확인
claude agents status
# 출력:
에이전트 상태:
├── developer: 활성 (작업 중: 컴포넌트 작성)
├── tester: 대기 중
├── reviewer: 활성 (작업 중: PR #123 리뷰)
└── security-expert: 대기 중
최근 작업:
- developer: Header 컴포넌트 작성 완료 (5분 전)
- tester: 로그인 테스트 통과 (3분 전)
- reviewer: PR #123 리뷰 중 (진행 중)
요약
서브 에이전트 시스템은 특화된 전문가 에이전트를 통해 효율적인 작업 분산과 병렬 처리를 가능하게 합니다.
핵심 개념
- 내장 에이전트: 개발자, 테스터, 리뷰어 등
- 커스텀 에이전트: 프로젝트별 특화 에이전트
- 오케스트레이션: 순차, 병렬, 조건부 실행
- 커뮤니케이션: 에이전트 간 협업
- 모니터링: 실행 추적 및 상태 관리
모범 사례
- 적절한 에이전트 선택
- 명확한 작업 정의
- 효율적인 병렬 처리
- 지속적인 모니터링
다음 단계
- Agent Teams - 에이전트 팀 워크플로우
- Plugins - 플러그인 개발
- CLI Reference - 명령줄 참조
이 가이드가 도움이 되셨나요?
서브 에이전트에 대한 질문이 있으시면 언제든지 물어보세요!