CLAUDE CODE DEEP DIVE WORKSHOP · 시리즈 2/6
② Agents & Subagents — 전문 에이전트에게 위임하기
하나의 세션 안에서 역할별 하위 에이전트를 정의하고, Task 툴로 작업을 자동·병렬 위임하는 법.
.claude/agents/*.md로 정의하고, Task 툴로 자동/명시/병렬 위임하며, 5대 패턴으로 실전 자동화합니다.
1. 왜 서브에이전트인가
- Context Isolation — 별도 컨텍스트 창에서 동작 → 메인 세션 토큰 절약, 대화 오염 방지
- Tool Permission Isolation — 에이전트마다 허용 도구를 따로 제한(예: 리뷰어는 읽기 전용)
- Cost & Latency — 병렬 위임으로 처리량↑, 단 자체 컨텍스트라 비용·지연 트레이드오프 존재
2. 정의 방법
파일 위치는 프로젝트(.claude/agents/*.md, 팀 공유) 또는 사용자 전역(~/.claude/agents/*.md). 파일은 YAML frontmatter + 시스템 프롬프트 본문 구조입니다.
---
name: code-reviewer
description: PR diff를 검토하고 개선 사항을 제안하는 시니어 리뷰어
tools: Read, Grep, Glob, Bash(git diff:*)
model: claude-sonnet-4-5
---
당신은 시니어 코드 리뷰어입니다.
가독성·안전성·성능·테스트 관점에서 검토하세요.- name 고유 이름 · description 언제 쓸지(자동 위임 근거) · tools 도구 화이트리스트 · model 사용 모델
- Good description — 구체적으로 써야 자동 디스패치가 정확
- Permission inheritance — tools 미지정 시 부모 권한 상속, 지정 시 그 목록으로 제한
- 🆕 최신 20260703 에디션 — 스코프는 5계층, 프론트매터는 위 4개 핵심을 포함해 총 15필드(
color·proactive등)로 확장. 상세 표는 아래 심화 섹션 참고.
3. Task Tool — 위임 메커니즘
- Auto dispatch — description을 보고 Claude가 알아서 위임
- @멘션 호출 —
@code-reviewer처럼 이름으로 명시 호출 - Parallel — 독립 작업이면 여러 에이전트 동시 실행
- 🆕 fork · 중첩(nesting) · resume — 대화 분기, 에이전트 안의 에이전트, 세션 이어가기 (최신 에디션)
- Context passing / Cost tracking — 필요한 맥락만 전달, 에이전트별 토큰 추적
4. 5대 실전 패턴
| 패턴 | 핵심 |
|---|---|
| Code Reviewer 🔍 | 대화형/Headless 리뷰, GitHub Actions 통합, 멀티 에이전트 협업 |
| Tester 🧪 | 커버리지 워크플로(부족분 탐지→보강), CI 통합 |
| Security Scanner 🔒 | 의존성 취약점·시크릿 탐지, Pre-commit hook 통합 |
| Docs Writer 📝 | README·API 문서·ADR·다국어·Changelog 자동화 |
| Migration Bot 🔄 | 라이브러리 업그레이드·import 경로·API deprecation 대응 |
실습 체크리스트
☐ tools 필드로 읽기 전용 권한 격리 실습
☐ auto dispatch 관찰 + 명시 호출 둘 다 실행
☐ 5대 패턴 중 하나(리뷰어 추천) 실제 적용
☐ (심화) 리뷰어+테스터 협업 또는 pre-commit hook 연동
🧪 핸즈온 랩 — 전문 에이전트를 만들고 지휘하기
| Task | 내용 |
|---|---|
| 첫 Subagent | .claude/agents/code-reviewer.md 작성(frontmatter + 시스템 프롬프트) |
| 도구 권한 격리 | tools 필드로 읽기 전용 리뷰어 만들기 |
| 에이전트 3종 완성 | test-writer · docs-writer 추가 |
| Task 디스패치 3패턴 | 자동(auto) / 명시(explicit) / 병렬(parallel) |
| Headless·CI 맛보기 | 서브에이전트를 무인/CI에서 호출 |
산출물 — 재사용 가능한 .claude/agents/*.md 3종 + 디스패치 3패턴 경험
🧪 핸즈온 상세 실습 기록
1. 첫 Subagent — code-reviewer
cd ~/claude-lab/ch1
mkdir -p .claude/agents
cat > .claude/agents/code-reviewer.md << 'EOF'
---
name: code-reviewer
description: |
PR diff를 검토하여 가독성·안전성·성능·테스트 커버리지 관점에서
개선 사항을 제안하는 시니어 코드 리뷰어.
tools: Read, Grep, Glob, Bash(git diff:*), Bash(git log:*)
model: sonnet
---
당신은 10년 경력의 시니어 코드 리뷰어입니다. ...
EOF세션에서 호출:
code-reviewer 에이전트를 사용해서 최근 커밋(git diff HEAD~1)을 검토해 주세요
→ Agent(code-reviewer, "Review git diff HEAD~1")
[reviewer] Bash git diff HEAD~1 → Read src/userService.js
[메인] low: 옵셔널 체이닝 적절 / medium: 엣지 케이스 테스트 부재2. 도구 권한 격리 체험
tools: Read, Grep만 가진 에이전트는 파일 수정을 시도해도 Edit 권한이 없어 분석만 보고합니다. tools에 Edit을 추가하면 그때서야 수정 가능(승인 요청). 권한이 곧 안전 경계임을 체험하는 단계입니다.
[dangerous-test] Read src/users.js
[dangerous-test] 파일 수정이 필요하지만 Edit 도구 권한이 없습니다. 분석만 보고합니다.
# tools에 Edit 추가 후 재실행 → 이번엔 Edit 사용(승인 요청)3. 에이전트 3종 완성
test-writer(tools: Read/Grep/Glob/Edit/Write/Bash(npm test:*)) + docs-writer 추가. 세션에서 "사용 가능한 서브에이전트를 모두 알려주세요"로 3종 등록 확인.
4. Task 디스패치 3패턴
- 자동(auto) — "최근 변경을 코드 리뷰해 주세요" → description 매칭으로 code-reviewer 자동 선택
- 명시(explicit) — "test-writer 에이전트를 사용해서 …"로 직접 지정
- 병렬(parallel) — "리뷰·테스트·README를 병렬로" → 3개 동시 호출
[메인] 3개의 Subagent를 병렬로 호출
[reviewer] 이슈 2건 [tester] 엣지 케이스 1건 보강 [docs] README 초안
/cost → Main $0.09 + reviewer $0.11 + tester $0.13 + docs $0.09 = $0.425. Headless 통합 & CI 맛보기
git diff HEAD~1 | claude -p "code-reviewer로 이 diff를 검토" \
--output-format json > review-result.json
jq '.summary' review-result.json
jq '.issues | map(select(.severity == "high"))' review-result.jsonGitHub Actions pull_request 트리거로 PR마다 code-reviewer를 자동 실행하는 워크플로까지 구성.
/cost로 추적.
📚 심화 · 비교 · 트러블슈팅 · FAQ
🤔 언제 서브에이전트를 쓰고, 언제 메인에서 하나
| 상황 | 선택 |
|---|---|
| 반복적·전문적 작업(리뷰/테스트/문서) | 서브에이전트 (재사용) |
| 여러 작업을 동시에 처리 | 병렬 서브에이전트 |
| 메인 대화를 오염시키고 싶지 않은 탐색 | 서브에이전트(격리) |
| 일회성 간단한 수정 | 메인 세션에서 바로 |
✍️ description 잘 쓰는 법 (자동 위임의 핵심)
Claude는 description을 읽고 어떤 에이전트에 맡길지 판단합니다. 모호하면 위임이 빗나갑니다.
🔧 tools 필드 문법 치트시트
| 표기 | 의미 |
|---|---|
Read, Grep, Glob | 읽기 전용(안전한 리뷰어) |
Bash(git diff:*) | git diff 계열만 허용 |
Edit, Write | 파일 수정 권한(테스트 작성자 등) |
| (tools 생략) | 부모 세션 권한 상속 |
🧩 서브에이전트 vs 슬래시 커맨드 vs MCP
| 개념 | 무엇 | 한 줄 |
|---|---|---|
| 서브에이전트 | 역할별 전문 AI | "누가 일하나" |
| 슬래시 커맨드 | 재사용 프롬프트 매크로 | "무엇을 시키나"(Ch4) |
| MCP | 외부 도구 연결 프로토콜 | "무슨 도구를 쓰나"(Ch4) |
🧯 자주 막히는 지점
| 증상 | 처방 |
|---|---|
| 자동으로 위임이 안 됨 | description을 "사용 시점" 포함해 구체화, 또는 이름으로 명시 호출 |
| 에이전트가 수정을 못 함 | tools에 Edit/Write 누락 → 추가 |
| 비용이 예상보다 큼 | 병렬은 합산됨 → /cost 확인, 단순 작업은 model: haiku |
📐 스코프 5계층 (최신 20260703 에디션)
서브에이전트 정의 파일이 놓일 수 있는 위치는 우선순위를 가진 5계층입니다. 충돌 시 더 구체적인(가까운) 스코프가 이깁니다.
| 계층 | 위치 | 범위 |
|---|---|---|
| Enterprise | 관리자 배포 경로 | 조직 전체 강제 |
| User | ~/.claude/agents/ | 내 모든 프로젝트 |
| Project | .claude/agents/ | 팀 공유(Git) |
| Local | 프로젝트 개인 오버라이드 | 나만(미커밋) |
| Plugin | 플러그인 번들 | 배포 단위로 묶어 공유 |
🧾 프론트매터 — 핵심 4 + 확장 (총 15필드)
최소 4개만 있어도 동작하지만, 최신 에디션은 자동 위임·표시·권한을 정교하게 제어하는 필드를 제공합니다.
| 구분 | 필드 |
|---|---|
| 핵심 4 | name · description · tools · model |
| 표시·위임 | color · proactive(자동 위임 강도) 등 |
| 권한·범위 | 허용/차단 도구 세분화, 추가 디렉토리 등 |
💡 description에 "PROACTIVELY use when…"처럼 쓰면 자동 위임 적중률이 올라갑니다.
🚦 디스패치 5종 — 위임의 어휘
| 방식 | 설명 |
|---|---|
| 자동 위임 | description 매칭으로 Claude가 알아서 선택 |
| @멘션 | @code-reviewer로 특정 에이전트 지정 호출 |
| fork | 현재 맥락을 복제해 분기 작업 |
| 중첩(nesting) | 에이전트가 또 다른 에이전트를 호출 |
| resume | 이전 에이전트 세션을 이어서 재개 |
※ 병렬 실행은 자동 위임/멘션과 결합해 여러 작업을 동시에 처리할 때 쓰입니다.
💡 학습 팁 — PDF보다 Script가 빠르다
Ch2 PDF는 발표 자료라 설명이 얇습니다. 오히려 Script/workshop-code/ch2-agents/의 예시 md(파트당 5~10개)와 하단 한국어 발표자 노트가 이해에 훨씬 도움이 됩니다. (일부 스니펫은 코드블록이 여러 파일로 쪼개져 있으니 합쳐서 보세요.)
❓ FAQ
Q. 에이전트 파일은 어디에 두나요?
A. 팀 공유는 .claude/agents/(Git 커밋), 개인 전역은 ~/.claude/agents/.
Q. 몇 개까지 만들 수 있나요?
A. 제한은 없지만, 역할이 겹치면 자동 위임이 헷갈립니다. 명확히 구분되는 소수로 시작하세요.
조직 단위 배포·자격증명·거버넌스·SSO·감사를 다룹니다.