Claude Code를 쓰다 보면 “이 작업은 항상 같은 방식으로 처리되는데”라는 생각이 드는 순간이 있습니다. 코드 리뷰, 배포 점검, 릴리스 노트 작성, 데이터 분석 — 반복되는 패턴이 있는 작업들이죠. 이를 해결하는 것이 바로 Claude Code 서브에이전트입니다.
VoltAgent/awesome-claude-code-subagents 레포지토리에는 현재 154개 이상의 서브에이전트가 10개 카테고리로 정리되어 있습니다. 이 글에서는 서브에이전트의 개념부터 직접 만드는 방법, 그리고 직군별 실전 활용법까지 한 번에 정리합니다.
📌 목차
1. Claude Code 서브에이전트란?
서브에이전트는 Claude Code의 전문화된 AI 어시스턴트입니다. 일반 Claude Code 세션과의 차이는 이렇습니다.
| 구분 | 일반 Claude Code 세션 | 서브에이전트 |
|---|---|---|
| 컨텍스트 | 하나의 대화 흐름 공유 | 독립적인 컨텍스트 윈도우 |
| 전문성 | 범용 | 특정 도메인 최적화 |
| 재사용 | 매번 지시 필요 | 이름 하나로 즉시 호출 |
| 배포 | 개인 사용 | 프로젝트/팀/오픈소스 공유 |
| 도구 권한 | 전체 적용 | 에이전트별 세분화 설정 |
핵심은 “독립적인 컨텍스트 윈도우”입니다. 서브에이전트를 호출하면 기존 대화와 분리된 새 컨텍스트에서 실행되기 때문에, 이전 작업의 노이즈 없이 해당 도메인에만 집중합니다. 복잡한 프로젝트에서 여러 서브에이전트를 순서대로 또는 병렬로 실행하는 멀티에이전트 워크플로도 가능합니다.
비유: 일반 Claude Code가 만능 직원이라면, 서브에이전트는 각 분야의 전문 컨설턴트입니다. 법무, 마케팅, DevOps 전문가를 필요할 때 호출하는 방식입니다.
저장 위치
~/.claude/agents/— 전역 설치 (모든 프로젝트에서 사용).claude/agents/— 프로젝트별 설치 (해당 프로젝트에서만 사용)
2. 서브에이전트 만드는 방법
설치 방법 (3가지)
# 방법 1: 플러그인으로 설치 (권장)
claude plugin marketplace add VoltAgent/awesome-claude-code-subagents
claude plugin install backend-developer
# 방법 2: 대화형 설치 스크립트
git clone https://github.com/VoltAgent/awesome-claude-code-subagents
cd awesome-claude-code-subagents
./install-agents.sh
# 방법 3: 수동 복사
cp agents/backend-developer.md ~/.claude/agents/서브에이전트 파일 구조
서브에이전트는 마크다운 파일 하나로 정의됩니다. YAML 전면부에 메타데이터를 쓰고, 본문에 Claude에게 줄 지침을 작성합니다.
---
name: weekly-report-writer
description: 주간 업무 보고서를 자동 작성하는 서브에이전트. 데이터와 맥락을 입력하면 구조화된 보고서를 생성합니다.
tools:
- read
- write
---
# Weekly Report Writer
## 역할
너는 경험 많은 비즈니스 애널리스트야.
입력받은 데이터와 업무 내용을 바탕으로 다음 형식의 주간 보고서를 작성해:
## 출력 구조
1. **이번 주 핵심 성과** (bullet 3~5개)
2. **주요 지표 변화** (표: 지표명 / 전주 / 이번 주 / 증감률)
3. **이슈 및 리스크** (있을 경우만)
4. **다음 주 계획** (bullet 3개)
## 규칙
- 분량: A4 1페이지 이내
- 숫자는 반드시 포함
- 전문 용어는 한국어로 풀어서 설명호출 방법
# Claude Code 세션 내에서
> /weekly-report-writer
# 또는 서브에이전트를 직접 지명
> @backend-developer API 엔드포인트 설계해줘
> @security-auditor 이 코드 취약점 검토해줘잘 만든 서브에이전트의 조건
- 단일 책임 — 하나의 에이전트가 하나의 역할만 담당
- 명확한 description — Claude가 언제 이 에이전트를 자동 선택할지 판단하는 기준이 됨
- 출력 형식 명시 — 표, bullet, 코드 블록 등 구체적으로 지정
- 도구 권한 최소화 — 필요한 도구만 허용 (read-only 에이전트에 write 권한 금지)
- 예외 처리 포함 — 입력이 부족할 때 어떻게 요청할지 명시
3. 154개 서브에이전트 카테고리별 목록
VoltAgent/awesome-claude-code-subagents의 10개 카테고리를 정리했습니다. 실무에서 바로 쓸 수 있는 것들을 중심으로 선별했습니다.
🏗️ 01. Core Development — 핵심 개발
| 에이전트 | 역할 |
|---|---|
| fullstack-developer | 엔드투엔드 기능 개발 전담 |
| api-designer | REST/GraphQL API 설계 |
| frontend-developer | React, Vue, Angular UI/UX |
| backend-developer | 확장성 있는 서버사이드 개발 |
| microservices-architect | 분산 시스템 설계 |
| websocket-engineer | 실시간 통신 전문 |
| mobile-developer | 크로스플랫폼 모바일 개발 |
🌐 02. Language Specialists — 언어별 전문가 (32개)
| 에이전트 | 역할 |
|---|---|
| python-pro | Python 생태계 전반 |
| typescript-pro | TypeScript 타입 시스템 전문 |
| rust-engineer | 시스템 프로그래밍 / 메모리 안전성 |
| golang-pro | Go 동시성 · 마이크로서비스 |
| nextjs-developer | Next.js 14+ 풀스택 |
| react-specialist | React 18+ 현대식 패턴 |
| java-architect | 엔터프라이즈 Java |
| fastapi-developer | FastAPI 비동기 Python API |
| flutter-expert | Flutter 3+ 크로스플랫폼 |
| sql-pro | DB 쿼리 최적화 |
| + 22개 추가 | Swift, Kotlin, PHP, Rails, Angular, Elixir 등 |
⚙️ 03. Infrastructure — 인프라 (16개)
| 에이전트 | 역할 |
|---|---|
| devops-engineer | CI/CD 파이프라인 자동화 |
| kubernetes-specialist | 컨테이너 오케스트레이션 |
| terraform-engineer | Infrastructure as Code |
| cloud-architect | AWS/GCP/Azure 멀티클라우드 |
| sre-engineer | Site Reliability Engineering |
| incident-responder | 장애 대응 및 복구 |
| docker-expert | 컨테이너화 · 이미지 최적화 |
| security-engineer | 인프라 보안 강화 |
🔍 04. Quality & Security — 품질·보안 (17개)
| 에이전트 | 역할 |
|---|---|
| code-reviewer | 코드 품질 리뷰 |
| security-auditor | 보안 취약점 스캔 |
| penetration-tester | 윤리적 해킹 (침투 테스트) |
| qa-expert | 테스트 자동화 |
| performance-engineer | 성능 최적화 |
| debugger | 고급 디버깅 |
| compliance-auditor | 규제 준수 (GDPR, SOC2 등) |
| ai-writing-auditor | AI 작성 패턴 탐지 및 재작성 |
📊 05. Data & AI — 데이터·AI (13개)
| 에이전트 | 역할 |
|---|---|
| data-analyst | 데이터 인사이트 및 시각화 |
| data-engineer | 데이터 파이프라인 설계 |
| llm-architect | LLM 시스템 설계·배포 |
| ml-engineer | 머신러닝 모델 개발 |
| mlops-engineer | MLOps · 모델 운영 |
| prompt-engineer | 프롬프트 최적화 |
| postgres-pro | PostgreSQL 성능 튜닝 |
| nlp-engineer | 자연어 처리 전문 |
🛠️ 06. Developer Experience — 개발자 경험 (15개)
| 에이전트 | 역할 |
|---|---|
| documentation-engineer | 기술 문서 자동 작성 |
| readme-generator | GitHub README 생성 |
| refactoring-specialist | 코드 리팩토링 |
| legacy-modernizer | 레거시 코드 현대화 |
| git-workflow-manager | Git 브랜칭 · PR 워크플로 |
| mcp-developer | Model Context Protocol 개발 |
| dx-optimizer | 개발자 경험 개선 |
| dependency-manager | 패키지 · 의존성 관리 |
🎯 07. Specialized Domains — 특수 도메인 (14개)
| 에이전트 | 역할 |
|---|---|
| fintech-engineer | 금융 기술 (결제, 뱅킹 API) |
| payment-integration | 결제 시스템 연동 |
| blockchain-developer | Web3 / 스마트 컨트랙트 |
| game-developer | 게임 엔진 · 로직 |
| iot-engineer | IoT 시스템 개발 |
| seo-specialist | 검색엔진 최적화 |
| quant-analyst | 정량 분석 · 퀀트 전략 |
| risk-manager | 리스크 평가 및 관리 |
💼 08. Business & Product — 비즈니스·제품 (16개)
| 에이전트 | 역할 |
|---|---|
| product-manager | 제품 전략 · 로드맵 |
| business-analyst | 요구사항 분석 · 문서화 |
| content-marketer | 콘텐츠 마케팅 전략 |
| technical-writer | 기술 문서 · 사용 설명서 |
| ux-researcher | 사용자 리서치 · 인터뷰 설계 |
| scrum-master | Agile 스프린트 관리 |
| backlog-grooming | 백로그 정제 · 우선순위 |
| legal-advisor | 법률 · 계약 리뷰 지원 |
| wordpress-master | WordPress 개발 · 최적화 |
| growth-loops | PLG 성장 루프 설계 |
🤖 09. Meta & Orchestration — 오케스트레이션 (14개)
| 에이전트 | 역할 |
|---|---|
| multi-agent-coordinator | 멀티에이전트 워크플로 설계 |
| workflow-orchestrator | 복잡한 자동화 파이프라인 |
| airis-mcp-gateway | Docker 기반 MCP 멀티플렉서 (60+ 도구, 97% 토큰 절감) |
| pied-piper | SDLC 전체 워크플로 오케스트레이션 |
| codebase-orchestrator | 안전한 대규모 리팩토링 거버넌스 |
| context-manager | 컨텍스트 윈도우 최적화 |
| agent-installer | GitHub에서 에이전트 검색 · 설치 |
🔬 10. Research & Analysis — 리서치·분석 (11개)
| 에이전트 | 역할 |
|---|---|
| research-analyst | 종합 리서치 보고서 생성 |
| competitive-analyst | 경쟁 인텔리전스 수집 · 분석 |
| market-researcher | 시장 분석 · 소비자 인사이트 |
| ab-test-analysis | A/B 테스트 결과 해석 |
| cohort-analysis | 사용자 코호트 보존율 분석 |
| trend-analyst | 신흥 트렌드 예측 |
| project-idea-validator | 냉철한 사업 아이디어 검증 |
4. 직군별 활용 시나리오
📊 데이터 직무
데이터 직무에서 서브에이전트의 가장 큰 가치는 분석 → 해석 → 보고 사이클의 자동화입니다. 특히 독립 컨텍스트 덕분에 여러 데이터셋을 오염 없이 병렬 분석할 수 있습니다.
시나리오 ① 지표 이상 감지 + 원인 분석
@data-analyst에게 주요 지표 데이터를 입력하면 이상 패턴을 탐지하고, 이어서 @research-analyst에게 원인 가설 도출을 맡깁니다. 두 에이전트가 독립 컨텍스트에서 실행되므로 결과가 섞이지 않습니다.
> @data-analyst 이번 주 전환율 데이터 분석해줘 [data.csv 첨부]
# → 이상 지점: 화요일 오후 전환율 31% 급락
> @research-analyst 화요일 오후 전환율 급락 원인 가설 3개 도출해줘
# → 가설 목록 + 검증 방법 제시시나리오 ② A/B 테스트 설계부터 결과 해석까지
실험 전엔 @ab-test-analysis로 샘플 사이즈와 기간을 계산하고, 결과가 나오면 같은 에이전트로 통계적 유의성을 판단합니다. @cohort-analysis와 조합하면 실험군/대조군의 장기 보존율 차이까지 추적할 수 있습니다.
시나리오 ③ PostgreSQL 쿼리 최적화
느린 쿼리 로그를 @postgres-pro에게 넘기면 인덱스 설계, 쿼리 재작성, 실행 계획 분석까지 한 번에 처리합니다. @database-optimizer와 함께 쓰면 전체 DB 성능 리포트를 얻을 수 있습니다.
핵심 이점: 데이터 분석가가 SQL 튜닝, 통계 검정, 보고서 작성을 각각 다른 에이전트에게 병렬로 맡길 수 있습니다. 혼자라도 팀처럼 일하는 효과입니다.
💼 비개발자 (마케팅 · 영업 지원)
Claude Code CLI를 몰라도 괜찮습니다. Business & Product와 Research & Analysis 카테고리의 에이전트들은 코딩 없이 순수하게 업무 결과물을 만들어냅니다.
시나리오 ① 경쟁사 인텔리전스 보고서
@competitive-analyst에게 경쟁사 URL과 분석 기준을 입력하면 포지셔닝, 메시지 전략, 차별화 포인트를 구조화된 보고서로 정리합니다. @market-researcher와 조합하면 시장 전체 그림까지 확장됩니다.
> @competitive-analyst
경쟁사: A사, B사
분석 기준: 가격 정책, 주요 메시지, 타겟 고객
결과물: 비교표 + 우리 전략 시사점 3개시나리오 ② 콘텐츠 기획부터 발행까지
@content-marketer로 한 달치 콘텐츠 캘린더를 기획하고, @technical-writer로 개별 글 초안을 뽑고, @ai-writing-auditor로 AI 작성 흔적을 제거합니다. 세 에이전트가 순서대로 실행되는 파이프라인입니다.
시나리오 ③ 신사업 아이디어 검증
@project-idea-validator는 냉철하게 아이디어의 약점을 지적합니다. 시장 크기, 경쟁 강도, 기술적 실현 가능성, 수익화 경로를 구조적으로 점검하고 Go/No-Go 판단 근거를 제시합니다.
핵심 이점: 마케터나 영업 담당자가 기술 지식 없이도 분석, 기획, 검증 작업을 전문가 수준으로 처리할 수 있습니다. 외부 컨설턴트 비용을 대폭 줄일 수 있는 영역입니다.
⌨️ 개발자
개발자에게 서브에이전트는 페어 프로그래밍 파트너이자 코드 리뷰어이자 문서 작성자입니다. 특히 멀티에이전트 오케스트레이션이 개발 워크플로를 크게 바꿉니다.
시나리오 ① PR 제출 전 자동 파이프라인
코드 작성 후 PR 올리기 전, 세 에이전트를 순서대로 실행합니다.
@code-reviewer→ 코드 품질, 패턴, 중복 체크@security-auditor→ OWASP 기준 취약점 스캔@performance-engineer→ 병목 지점 및 최적화 제안
세 리뷰가 독립 컨텍스트에서 진행되므로 결과가 섞이지 않고 각각의 전문적 관점이 유지됩니다.
시나리오 ② 레거시 코드 현대화
@legacy-modernizer는 오래된 코드베이스를 분석해 현대화 로드맵을 제시합니다. @refactoring-specialist와 조합하면 단계별 리팩토링 계획까지 나옵니다. @test-automator가 리팩토링 전후 테스트 커버리지를 확보합니다.
시나리오 ③ pied-piper로 SDLC 전체 자동화
@pied-piper는 SDLC 전체를 오케스트레이션하는 메타 에이전트입니다. 요구사항 분석(@business-analyst)부터 설계(@api-designer), 구현(@backend-developer), 테스트(@qa-expert), 문서화(@documentation-engineer)까지 파이프라인을 자동으로 구성합니다.
시나리오 ④ airis-mcp-gateway로 토큰 97% 절감
@airis-mcp-gateway는 Docker 기반 MCP 멀티플렉서입니다. 60개 이상의 도구를 하나의 게이트웨이로 묶어 매번 도구를 로드하는 오버헤드를 줄입니다. 공식 측정 기준 토큰 사용량 97% 절감이 보고되었습니다.
핵심 이점: 개발자 혼자서도 풀 팀의 리뷰 체계를 갖출 수 있습니다. 스타트업 개발자나 1인 개발자에게 특히 강력합니다.
지금 바로 시작하는 법
- 레포 방문 — github.com/VoltAgent/awesome-claude-code-subagents 에서 내 업무에 맞는 에이전트 찾기
- Claude Code 설치 —
npm install -g @anthropic-ai/claude-code - 에이전트 설치
# 플러그인으로 설치 claude plugin marketplace add VoltAgent/awesome-claude-code-subagents claude plugin install data-analyst # 또는 수동 설치 cp agents/data-analyst.md ~/.claude/agents/ - 호출 —
claude실행 후@data-analyst 분석해줘
개발자가 아니라면 Claude.ai 웹앱에서 에이전트 마크다운 내용을 System Prompt에 붙여넣는 것만으로도 비슷한 효과를 낼 수 있습니다.
마치며
Claude Code 서브에이전트는 “필요한 전문가를 즉시 호출하는” 개념입니다. 154개 에이전트 중 내 업무와 가장 가까운 것 하나만 골라서 써보세요. 한 번 루틴에 정착하면 자연스럽게 파이프라인이 만들어집니다.
데이터 직무라면 @data-analyst부터, 마케터라면 @competitive-analyst부터, 개발자라면 @code-reviewer부터 시작하는 것을 권장합니다.
어떤 에이전트를 가장 먼저 써보셨나요? 댓글로 공유해주시면 같이 활용법을 발전시켜 보겠습니다.