Claude Code Subagents 완전 가이드
개요
Claude Code Subagents는 개발 워크플로우를 혁신적으로 개선하는 전문화된 AI 보조 에이전트 컬렉션입니다. 각 서브에이전트는 특정 도메인의 전문가로 설계되어, 컨텍스트 기반으로 자동 호출되거나 명시적으로 요청할 수 있습니다.
핵심 특징
•
61개의 전문화된 서브에이전트 (wshobson/agents 기준)
•
자동 위임 시스템: 작업 컨텍스트에 따른 지능적 라우팅
•
멀티 에이전트 오케스트레이션: 복잡한 작업을 위한 병렬/순차 실행
•
컨텍스트 격리: 각 에이전트가 독립적인 컨버세이션 컨텍스트 보유
•
모델 최적화: 작업 복잡도에 따른 Claude 모델 자동 선택
설치 및 설정
설치 방법
# 1. wshobson의 프로덕션 레디 컬렉션 (61개 에이전트)
cd ~/.claude
git clone https://github.com/wshobson/agents.git
# 2. 추가 명령어 컬렉션 (선택사항)
git clone https://github.com/wshobson/commands.git
# 3. 프로젝트별 에이전트 설정
cd your-project-root
mkdir -p .claude/agents
# 프로젝트 특화 에이전트 파일들을 이곳에 배치
Bash
복사
디렉토리 구조
~/.claude/agents/ # 사용자 레벨 (전역)
.claude/agents/ # 프로젝트 레벨 (우선순위 높음)
Plain Text
복사
주요 서브에이전트 카테고리
아키텍처 & 설계
에이전트 | 역할 | 사용 케이스 |
backend-architect | RESTful API, 마이크로서비스, DB 스키마 설계 | API 엔드포인트 설계, 시스템 아키텍처 |
frontend-developer | React 컴포넌트, 반응형 레이아웃, 상태 관리 | UI/UX 구현, 클라이언트 사이드 개발 |
cloud-architect | AWS/Azure/GCP 인프라 설계, 비용 최적화 | 클라우드 아키텍처, 인프라 설계 |
graphql-architect | GraphQL 스키마, 리졸버, 페더레이션 | GraphQL API 설계 |
보안 & 품질
에이전트 | 역할 | 사용 케이스 |
security-auditor | 취약점 검토, OWASP 컴플라이언스 | 보안 감사, 코드 보안 검토 |
code-reviewer | 코드 품질, 보안, 유지보수성 검토 | 코드 리뷰, 베스트 프랙티스 검증 |
test-automator | 단위/통합/E2E 테스트 작성 | 테스트 스위트 구축 |
성능 & 최적화
에이전트 | 역할 | 사용 케이스 |
performance-engineer | 애플리케이션 프로파일링, 병목 최적화 | 성능 튜닝, 캐싱 전략 |
database-optimizer | SQL 쿼리 최적화, 인덱스 설계 | DB 성능 개선, 마이그레이션 |
DevOps & 배포
에이전트 | 역할 | 사용 케이스 |
devops-troubleshooter | 프로덕션 이슈 디버깅, 로그 분석 | 장애 해결, 운영 문제 해결 |
deployment-engineer | CI/CD 파이프라인, Docker, 클라우드 배포 | 배포 자동화, 컨테이너화 |
AI & 데이터
에이전트 | 역할 | 사용 케이스 |
ai-engineer | LLM 애플리케이션, RAG 시스템 구축 | AI 앱 개발, 프롬프트 파이프라인 |
data-scientist | SQL 쿼리, BigQuery, 데이터 인사이트 | 데이터 분석, 인사이트 도출 |
data-engineer | ETL 파이프라인, 데이터 웨어하우스 | 데이터 파이프라인 구축 |
언어별 전문가
에이전트 | 역할 | 특화 영역 |
python-pro | Python 코딩, 고급 기능 활용 | 비동기 프로그래밍, 최적화 |
golang-pro | Go 코딩, 고루틴, 채널, 인터페이스 | 동시성 프로그래밍, 마이크로서비스 |
사용 방법
1. 자동 위임 (Auto-Delegation)
Claude Code가 컨텍스트를 분석하여 자동으로 적절한 에이전트를 선택합니다.
# 예시 요청
"사용자 인증 기능을 구현해줘"
# 자동 실행 플로우
backend-architect → security-auditor → test-automator → frontend-developer
Bash
복사
2. 명시적 호출 (Explicit Invocation)
특정 에이전트를 직접 지정하여 호출합니다.
# 단일 에이전트 호출
"code-reviewer를 사용해서 최근 변경사항을 검토해줘"
"security-auditor로 취약점을 스캔해줘"
"performance-engineer에게 이 병목을 최적화해달라고 해"
# 순차적 멀티 에이전트
"backend-architect가 API를 설계한 다음, security-auditor가 검토하도록 해줘"
Bash
복사
3. 슬래시 명령어 (Slash Commands)
복잡한 워크플로우를 위한 사전 정의된 명령어들입니다.
# 전체 스택 개발
/api-scaffold user management with authentication
/full-stack-feature Build user dashboard with real-time analytics
# 보안 & 성능
/security-scan check for vulnerabilities
/multi-agent-optimize optimize payment flow performance
# 인시던트 대응
/incident-response Database connection pool exhausted
Bash
복사
에이전트 오케스트레이션 패턴
1. 순차 실행 (Sequential)
User Request → Agent A → Agent B → Agent C → Result
Plain Text
복사
예시: "새 API 기능 구축"
backend-architect → frontend-developer → test-automator → security-auditor
2. 병렬 실행 (Parallel)
User Request → Agent A + Agent B (동시) → 결과 병합
Plain Text
복사
예시: "애플리케이션 성능 최적화"
performance-engineer + database-optimizer → 종합 권장사항
3. 조건부 분기 (Conditional Routing)
User Request → 분석 → 적절한 전문가로 라우팅
Plain Text
복사
예시: "이 버그 수정"
debugger (분석) → backend-architect OR frontend-developer OR devops-troubleshooter
4. 검토 & 검증 (Review & Validation)
Primary Agent → Review Agent → 최종 결과
Plain Text
복사
예시: "결제 처리 구현"
payment-integration → security-auditor → 검증된 구현
에이전트 파일 구조
각 서브에이전트는 Markdown 파일로 정의됩니다:
---
name: subagent-name
description: 이 서브에이전트가 언제 호출되어야 하는지 설명
model: haiku # 선택사항: 사용할 Claude 모델 지정 (haiku/sonnet/opus)
tools: tool1, tool2 # 선택사항: 기본값은 모든 도구
---
서브에이전트의 역할과 능력을 정의하는 시스템 프롬프트
Markdown
복사
모델 선택 가이드
•
Claude Haiku: 간단하고 빠른 작업 (코드 포맷팅, 기본 리뷰)
•
Claude Sonnet: 일반적인 개발 작업 (대부분의 에이전트 기본값)
•
Claude Opus: 복잡한 아키텍처 설계, 심화 분석
성능 최적화 팁
1. 컨텍스트 관리
•
context-manager 에이전트 사용 (10k+ 토큰 프로젝트 필수)
•
관련성 우선, 완전성보다는 효율성 추구
2. 에이전트 선택 최적화
•
파일에 번호 접두사 (01_, 02_) 추가로 정렬 순서 제어
•
필요한 도구만 제한하여 보안성과 효율성 향상
•
시스템 프롬프트를 간결하게 유지
3. 병렬 처리 활용
•
최대 10개 작업 동시 실행 가능
•
독립적인 컨텍스트 윈도우로 "컨텍스트 오염" 방지
고급 활용 사례
Kubernetes 환경 최적화 (클라우드 TA 관점)
# 1. 클러스터 아키텍처 검토
"cloud-architect를 사용해서 현재 k8s 클러스터의 확장성을 분석해줘"
# 2. 성능 최적화
"performance-engineer와 devops-troubleshooter가 협력해서
파드 리소스 사용량을 최적화해줘"
# 3. 보안 감사
"security-auditor로 RBAC 설정과 네트워크 정책을 검토해줘"
Bash
복사
Python/Go 학습 경로 (개발자 성장 관점)
# Python 심화 학습
"python-pro에게 비동기 프로그래밍 베스트 프랙티스를 가르쳐달라고 해"
"ai-engineer와 협력해서 Python으로 RAG 시스템을 구축해보자"
# Go 마이크로서비스 개발
"golang-pro와 backend-architect가 협력해서
Go로 마이크로서비스 아키텍처를 설계해줘"
Bash
복사
트러블슈팅
일반적인 문제들
에이전트가 자동으로 호출되지 않는 경우:
•
요청에 도메인을 명확히 표시 (예: "성능 이슈" → performance-engineer)
•
작업 유형을 구체적으로 명시 (예: "코드 검토" → code-reviewer)
예상과 다른 에이전트가 선택되는 경우:
•
기술 스택과 요구사항에 대한 더 많은 컨텍스트 제공
•
필요시 명시적 호출 사용
여러 에이전트가 상충하는 조언을 제공하는 경우:
•
이는 정상적인 현상 (전문가들의 서로 다른 우선순위)
•
명확화 요청: "security-auditor와 performance-engineer의 권장사항을 조율해줘"
추가 리소스
주요 저장소들
•
wshobson/agents: 61개 프로덕션 레디 에이전트
•
wshobson/commands: 복잡한 워크플로우용 슬래시 명령어
•
lst97/claude-code-sub-agents: 풀스택 개발용 큐레이션된 컬렉션
•
vanzan01/claude-code-sub-agent-collective: 컨텍스트 엔지니어링 연구
커뮤니티
•
GitHub: 다양한 에이전트 컬렉션과 커스텀 에이전트
•
Reddit: Claude Code 커뮤니티 토론 및 업데이트
•
베스트 프랙티스
1.
명확한 요청: 구체적인 컨텍스트와 요구사항 제공
2.
적절한 위임: 복잡한 작업은 자동 위임, 특정 전문성 필요시 명시적 호출
3.
단계적 접근: 복잡한 프로젝트는 여러 에이전트를 순차적으로 활용
4.
컨텍스트 관리: 대규모 프로젝트에서는 context-manager 필수 사용
5.
지속적 학습: 새로운 에이전트와 패턴을 실험하여 워크플로우 개선
이 문서를 통해 Claude Code Subagents의 강력한 기능을 최대한 활용하여 개발 생산성을 혁신적으로 향상시키시기 바랍니다.