Sub-agents로 작업 위임하기
⏱️ 20분
전문화된 하위 에이전트를 만들어 복잡한 작업을 효율적으로 처리하는 방법을 배웁니다.
목차
- 🎯 Sub-agents란?
- 📋 내장 Sub-agents
- 💡 Explore Agent
- 🎨 Plan Agent
- 🎯 general-purpose Agent
- 📝 사용자 정의 Agent 예제
- 🎓 실전 활용
- 🛠️ 사용자 정의 Sub-agent
- 📚 핵심 정리
- ⚠️ 주의사항
- 🔍 디버깅
- ✅ 완료
🎯 Sub-agents란?
Sub-agents는 같은 세션 내에서 특정 작업을 처리하는 전문화된 AI 어시스턴트입니다.
실생활 비유
회사에서 팀장이 업무를 전문가에게 위임하는 것과 같습니다:
- 디자인 작업 → 디자이너에게
- 보안 검토 → 보안 전문가에게
- 성능 최적화 → 성능 엔지니어에게
왜 필요한가?
컨텍스트 관리:
- 주 대화의 컨텍스트를 보존
- 탐색/연구 결과를 별도 윈도우에 격리
- 필요한 요약만 주 대화로 반환
제약 조건 적용:
- 특정 도구만 사용하도록 제한
- 읽기 전용 작업 보장
- 권한 모드 분리
Sub-agents vs Agent Teams:
Sub-agents (같은 세션 내)
┌─────────────────────────────────────────┐
│ 메인 대화 (세션 1) │
│ ┌──────────────────────────────────┐ │
│ │ 주 컨텍스트 윈도우 │ │
│ │ - 사용자와의 대화 │ │
│ │ - CLAUDE.md │ │
│ └──────────────────────────────────┘ │
│ ↓ 위임 │
│ ┌──────────────────────────────────┐ │
│ │ Sub-agent (격리된 윈도우) │ │
│ │ - 연구/검증 작업 │ │
│ │ - 결과만 반환 │ │
│ └──────────────────────────────────┘ │
│ ↑ 요약 반환 │
└─────────────────────────────────────────┘
Agent Teams (독립적인 세션들)
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 세션 1 │ │ 세션 2 │ │ 세션 3 │
│ 팀 리더 │◄──►│ 팀원 1 │◄──►│ 팀원 2 │
│ │ │ │ │ │
│ 작업 조율 │ │ Frontend 개발│ │ Backend 개발 │
└──────────────┘ └──────────────┘ └──────────────┘
↕ ↕ ↕
┌───────────────────────────────────────────┐
│ 공유 작업 목록 & 메시징 시스템 │
└───────────────────────────────────────────┘
| 비교 | Sub-agents | Agent Teams |
|---|---|---|
| 세션 | 같은 세션 내 | 독립적인 세션들 |
| 컨텍스트 | 격리된 윈도우 | 완전히 분리 |
| 용도 | 작업 위임 | 병렬 협업 |
| 통신 | 부모-자식 관계 | 세션 간 조율 |
📋 내장 Sub-agents
Claude Code는 3가지 핵심 내장 Sub-agents를 제공합니다.
핵심 Sub-agents
| 이름 | 역할 | 사용 시점 | 특징 |
|---|---|---|---|
Explore | 코드베이스 탐색 | 파일 찾기, 구조 분석 | 읽기 전용, 빠른 검색 |
Plan | 연구 및 계획 | Plan 모드 중 컨텍스트 수집 | 무한 중첩 방지 |
general-purpose | 복합 작업 처리 | 탐색 + 수정, 다단계 작업 | 복잡한 추론 가능 |
사용 방법
# Claude Code 대화 중
코드베이스를 탐색해서 인증 관련 파일을 찾아줘
Claude가 자동으로 적절한 Sub-agent를 선택합니다.
기타 도우미 Agents
Claude Code에는 특정 작업을 위한 추가 도우미 에이전트가 있습니다:
| Agent | 모델 | 자동 실행 시점 |
|---|---|---|
statusline-setup | Sonnet | /statusline 실행 시 |
Claude Code Guide | Haiku | Claude Code 기능 질문 시 |
💡 Explore Agent
코드베이스를 빠르게 탐색하는 전문 에이전트입니다.
특징
- 읽기 전용: 변경 없이 코드베이스 검색
- 컨텍스트 격리: 탐색 결과를 주 대화에서 분리
- 철저함 수준: Claude가 상황에 맞게 자동 선택
quick: 대상 조회medium: 균형 잡힌 탐색very thorough: 포괄적인 분석
사용 예제
파일 찾기:
인증 관련 파일들을 모두 찾아줘
구조 파악:
이 프로젝트의 전체 구조를 설명해줘
패턴 검색:
API 엔드포인트가 어떻게 정의되어 있는지 찾아줘
작동 방식
- Glob 도구로 파일 패턴 검색
- Grep 도구로 키워드 검색
- 파일 구조 분석
- 결과 정리 및 보고
🎨 Plan Agent
Plan 모드 중에 연구를 담당하는 에이전트입니다.
특징
- Plan 모드 전용: Plan 모드일 때만 활성화
- 무한 중첩 방지: Sub-agent는 다른 Sub-agent를 생성할 수 없음
- 컨텍스트 수집: 계획 수립에 필요한 정보 수집
사용 예제
기능 추가 계획:
사용자 로그인 기능을 추가하고 싶어. 구현 계획을 세워줘.
Plan Agent의 출력:
## 구현 계획: 사용자 로그인
### 1단계: 데이터베이스 스키마
- users 테이블 생성
- email, password_hash, created_at 컬럼
### 2단계: API 엔드포인트
- POST /api/auth/login
- POST /api/auth/logout
- GET /api/auth/me
### 3단계: 인증 미들웨어
- JWT 토큰 생성/검증
- 인증 필요한 라우트 보호
### 4단계: 프론트엔드 통합
- 로그인 폼 컴포넌트
- 인증 상태 관리
- 라우트 가드
### 5단계: 테스트
- 단위 테스트
- 통합 테스트
- E2E 테스트
장점
- 전체 그림을 먼저 파악
- 단계별로 체계적 진행
- 놓치기 쉬운 부분 사전 발견
🎯 general-purpose Agent
복잡한 다단계 작업을 처리하는 범용 에이전트입니다.
특징
- 탐색 + 작업: 읽기와 수정을 모두 수행
- 복잡한 추론: 결과 해석과 의사결정 가능
- 다단계 처리: 여러 종속 단계가 있는 작업
Claude가 위임하는 경우
- 탐색과 수정이 모두 필요한 작업
- 복잡한 추론이 필요한 작업
- 여러 종속 단계가 있는 작업
사용 예제
복합 작업:
인증 시스템의 버그를 찾아서 수정하고 테스트를 추가해줘
이 작업은 다음을 포함합니다:
- 탐색: 인증 관련 파일 찾기
- 분석: 버그 원인 파악
- 수정: 코드 수정
- 검증: 테스트 작성 및 실행
📝 사용자 정의 Agent 예제
위의 내장 agent 외에도 사용자 정의 agent를 만들 수 있습니다.
예제 1: Code Reviewer Agent
코드를 리뷰하고 개선점을 찾는 전문 에이전트입니다.
---
name: code-reviewer
description: 코드 품질 검증 및 개선점 도출
model: sonnet
---
# Code Reviewer Agent
당신은 코드 리뷰 전문가입니다.
## 검사 항목
1. **보안 취약점**
2. **성능 문제**
3. **코드 스타일**
4. **버그 가능성**
5. **테스트 커버리지**
## 출력 형식
### ✅ 잘된 점
- 목록
### ⚠️ 개선 필요
1. **카테고리**: 설명 (줄번호)
### 💡 제안
- 구체적인 개선 방법
예제 2: Code Simplifier Agent
복잡한 코드를 단순화하는 에이전트입니다.
---
name: code-simplifier
description: 코드 단순화 및 리팩토링
model: opus
---
# Code Simplifier Agent
당신은 리팩토링 전문가입니다.
## 목표
- 중복 제거
- 명확한 타입 정의
- 현대적인 문법 사용
- 가독성 향상
## 개선 사항
각 변경에 대해:
- **Before**: 기존 코드
- **After**: 개선된 코드
- **이유**: 왜 더 나은지 설명
🎓 실전 활용
패턴 1: 기능 개발 워크플로우
1단계: 계획 수립
로그인 기능을 추가하려고 해. Plan agent를 사용해서 구현 계획을 세워줘.
2단계: 구조 파악
Explore agent로 기존 인증 관련 코드를 찾아줘.
3단계: 구현
계획에 따라 단계별로 구현해줘.
4단계: 리뷰
Code reviewer agent로 작성한 코드를 리뷰해줘.
5단계: 리팩토링
Code simplifier agent로 코드를 정리해줘.
패턴 2: 레거시 코드 개선
1단계: 탐색
Explore agent로 복잡도가 높은 파일들을 찾아줘.
2단계: 분석
가장 복잡한 파일을 Code reviewer로 분석해줘.
3단계: 단순화
Code simplifier로 리팩토링해줘.
4단계: 검증
테스트가 여전히 통과하는지 확인해줘.
패턴 3: 버그 수정
1단계: 탐색
Explore agent로 에러 메시지와 관련된 파일을 찾아줘.
2단계: 분석
해당 파일들을 Code reviewer로 분석해서 버그 원인을 찾아줘.
3단계: 수정
버그를 수정해줘.
🛠️ 사용자 정의 Sub-agent
자신만의 Sub-agent를 만들 수 있습니다.
Agent 정의 파일 생성
mkdir -p ~/.claude/agents
cat > ~/.claude/agents/security-checker.md << 'EOF'
---
name: security-checker
description: 보안 취약점을 검사하는 전문 에이전트
model: sonnet
priority: 100
---
# Security Checker Agent
당신은 보안 전문가입니다. 코드에서 보안 취약점을 찾는 것이 임무입니다.
## 검사 항목
1. **인증/인가**
- 하드코딩된 비밀번호
- 약한 암호화
- 토큰 노출
2. **입력 검증**
- SQL 인젝션
- XSS 취약점
- 경로 탐색
3. **민감 데이터**
- 로그에 민감 정보
- 평문 저장
- 불필요한 노출
## 출력 형식
각 취약점에 대해:
- **위치**: 파일명:줄번호
- **심각도**: 높음/중간/낮음
- **설명**: 무엇이 문제인지
- **해결**: 어떻게 고치는지
EOF
우선순위 시스템
Agent 정의에 priority 필드를 추가하여 선택 우선순위를 설정할 수 있습니다:
---
name: my-agent
description: 설명
model: sonnet
priority: 100
---
우선순위 값:
- 높은 숫자 = 높은 우선순위
- 기본값: 0
- 내장 agent보다 우선하려면 100 이상 사용
동작 방식:
- Claude가 작업에 맞는 agent를 탐색
- 우선순위가 높은 사용자 정의 agent부터 평가
- 조건이 맞으면 해당 agent 선택
- 맞는 agent가 없으면 내장 agent 사용
사용 방법
# Claude Code 대화 중
security-checker agent를 사용해서 src/ 디렉토리를 검사해줘
Claude가 사용자 정의 Agent를 로드해서 실행합니다.
📚 핵심 정리
Sub-agents 선택 기준
Explore Agent:
- 읽기 전용 탐색
- 빠른 파일 검색
- 코드베이스 구조 파악
Plan Agent:
- Plan 모드 중 연구
- 컨텍스트 수집
- 무한 중첩 방지
general-purpose Agent:
- 탐색 + 수정 작업
- 복잡한 추론 필요
- 다단계 종속 작업
사용자 정의 Agent:
- 특정 도메인 전문화
- 프로젝트 특화 작업
- 우선순위로 내장 agent 대체
Agent 위임 시점
언제 위임하나:
- ✅ 작업이 복잡할 때
- ✅ 전문성이 필요할 때
- ✅ 컨텍스트 격리가 필요할 때
직접 처리:
- ✅ 간단한 작업
- ✅ 즉각적인 응답 필요
- ✅ 컨텍스트 유지 중요
사용자 정의 Agent 구조
---
name: agent-name
description: 에이전트 설명
model: sonnet|opus|haiku
priority: 100 # 선택적: 높을수록 우선
---
# Agent 이름
[에이전트의 역할과 목표]
## 작업 방식
[어떻게 작업을 수행하는지]
## 출력 형식
[결과를 어떤 형식으로 제공하는지]
⚠️ 주의사항
과도한 위임 피하기
나쁜 예:
파일을 읽어줘 (Explore agent 사용)
→ 불필요한 위임
좋은 예:
인증 관련 모든 파일을 찾고 각 파일의 역할을 정리해줘 (Explore agent 적합)
→ 복잡한 탐색 작업
컨텍스트 전달
Sub-agent는 독립적인 컨텍스트를 가집니다.
- 충분한 정보를 전달하세요
- 명확한 요청을 하세요
나쁜 예:
이거 리뷰해줘
좋은 예:
src/auth.ts 파일을 리뷰해줘. 특히 보안과 성능에 집중해줘.
결과 검증
Sub-agent의 결과를 항상 검토하세요:
- 제안이 적절한지
- 프로젝트 컨텍스트에 맞는지
- 부작용은 없는지
🔍 디버깅
Agent 실행 확인
# 상세 로그 활성화
export CLAUDE_DEBUG=true
claude
Agent 목록 확인
# 사용 가능한 agents 확인
ls ~/.claude/agents/
Agent 정의 검증
# Agent 파일 문법 확인
cat ~/.claude/agents/my-agent.md
✅ 완료
Sub-agents를 활용해서 작업을 효율적으로 위임하는 방법을 배웠습니다!
배운 것:
- ✅ Sub-agents 개념
- ✅ 내장 Agents 활용 (Explore, Plan, Code Reviewer, Code Simplifier)
- ✅ 실전 워크플로우 패턴
- ✅ 사용자 정의 Agent 생성
핵심 개념:
- Sub-agents는 전문화된 하위 에이전트
- 복잡한 작업을 작은 단위로 분할
- 각 Agent가 특정 작업에 집중
- 사용자 정의 Agent로 확장 가능
다음에는: Agent Teams로 여러 세션을 조율하는 방법을 배웁니다.