Subagent — 시니어 개발자처럼 위임하기
집중된 작업을 전문 Claude 인스턴스에 넘기기
⏱ 예상 ~6분
01 · 읽기
시니어 개발자는 모든 걸 직접 하지 않아요 — 위임해요. 주니어 개발자가 시니어에게 버그를 조사해 달라고 부탁할 때, 시니어는 자기 작업을 버리지 않아요. 누군가를 보내 조사하고 보고 받게 해요.
Subagent 는 Claude Code 에서 같은 걸 할 수 있게 해줘요. 모든 걸 처리하려는 큰 대화 하나 — 파일 읽기, 테스트 실행, 아키텍처 조사 — 대신, 집중된 작업을 전용 subagent 에게 위임할 수 있어요. 그들은 자기 context window 에서 일해요.
핵심 이점: subagent 가 메인 대화를 깔끔하게 유지해 줘요. 하나의 subagent 가 인증 시스템 이해를 위해 파일 50 개를 읽을 수 있지만, 짧은 요약만 여러분의 context window 로 돌아와요.
💡 상상해 봐요Subagent 를 도서관에 연구 조수를 보낸다고 생각해요. 직접 가서 책상에 책을 쌓는 게 아니라 — 그들이 가서 다 읽고 한 페이지 요약을 가져와요. 여러분의 책상은 중요한 작업을 위해 깔끔하게 유지돼요.
핵심 정리
- Subagent 는 메인 대화와 분리된 context window 에서 돌아요
- 독립적으로 작업을 조사, 분석, 실행해요
- 요약만 여러분 context 에 돌아와요 — 읽은 모든 파일이 아니라
- 메인 대화는 구현에 집중을 유지해요
02 · 읽기
Claude Code 에는 내장 subagent 타입이 몇 개 있고, 각각 특정 작업용으로 설계됐어요: - Explore — Read-only 연구. 파일 검색, 코드 읽기, codebase 질문에 답하기. 편집은 못 해요. - Plan — 아키텍처 설계. codebase 탐색, 구현 계획 제안. 여러분이 승인하기 전까지 read-only. - Bash — 명령 전문가. 터미널 명령 실행. 테스트, build, 시스템 점검에 써요.
Claude 는 격리해야 할 작업을 인식할 때 자동으로 subagent 를 생성해요 — 큰 codebase 조사나 테스트 스위트 실행 같은. 명시적으로 요청할 수도 있어요.
핵심 정리
- Explore: read-only 연구와 codebase 분석
- Plan: 아키텍처 설계와 구현 계획
- Bash: 터미널 명령과 시스템 작업
- Claude가 적절할 때 자동으로 subagent 를 생성해요
03 · 코드 예제
Claude에게 subagent 를 쓰라고 직접 요청할 수 있어요. 아래는 subagent 위임을 유발하는 prompt 예요.
subagent 를 유발하는 prompt
"Use a subagent to investigate how auth works in this codebase"
"Explore the database schema and summarize what tables we have"
"Run the test suite and report which tests fail"
"Analyze the API routes and list all endpoints"
Claude에게 "조사해", "탐색해", "분석해", 또는 "테스트 실행해" 라고 요청하면 종종 자동으로 subagent 에게 위임해요. Subagent 는 자기 context 에서 무거운 일을 하고 간결한 요약을 대화로 돌려보내요.
04 · 읽기
YAML frontmatter 가 있는 SKILL.md 를 작성해서 자기만의 커스텀 subagent 를 만들 수 있어요. 자기 지시, 도구 제한, 모델 선택을 가진 전문 agent 를 정의해요.
커스텀 agent 가 강력한 이유는 능력을 제한할 수 있기 때문이에요. Code reviewer 는 파일을 읽기만 하면 돼요 — 편집하거나 명령을 실행하면 안 돼요. Test runner 는 Bash 가 필요하지만 Edit 는 아니에요. 도구 제한이 agent 를 더 안전하고 더 집중되게 만들어요.
핵심 정리
- 커스텀 agent 는 YAML frontmatter 가 있는 SKILL.md 에 정의돼요
- tools: 필드가 agent 가 할 수 있는 걸 제한해요
- Reviewer 는 Read/Grep/Glob 가 필요해요 — Edit 나 Bash 가 아니라
- 제한이 agent 를 더 안전하고 더 집중되게 만들어요
05 · 코드 예제
아래는 커스텀 code-reviewer subagent 를 만드는 방법이에요. YAML frontmatter 가 그 행동을 설정해요.
.claude/skills/code-reviewer/SKILL.md
---
name: code-reviewer
description: Expert code review specialist. Use after code changes.
tools: Read, Grep, Glob
model: sonnet
---
Review code for:
1. Bug risks and logic errors
2. Security vulnerabilities (injection, auth bypass)
3. Performance issues (N+1 queries, unnecessary loops)
4. Style inconsistencies with the existing codebase
Provide specific line references and severity ratings.
이 agent 는 코드를 읽기만 할 수 있어요 — 파일을 편집하거나 명령을 실행할 수 없어요. tools: Read, Grep, Glob 제한이 리뷰에 집중되게 보장해요. model: sonnet 은 메인 대화 모델 대신 Sonnet (빠르고 cost-effective) 을 쓴다는 뜻이에요.
06 · 퀴즈
새 기능을 구현 중인데 기존 인증 시스템이 어떻게 작동하는지 이해해야 해요. 파일 20 개 이상을 읽어야 해요. context 효율이 가장 좋은 방법은?
- 메인 대화에서 직접 파일 20 개를 다 읽기
- Claude에게 파일을 읽지 말고 인증을 설명해 달라고 부탁
- 조사를 위해 새 Claude session 열기
- Subagent 를 써서 조사하고 요약 돌려받기
07 · 짝짓기
각 subagent 타입을 가장 잘 맞는 용도와 짝지어요.
(이 섹션은 인터랙티브해요 — JavaScript를 켜 주세요.)
⚠ 전체 인터랙티브 경험에는 JavaScript가 필요해요. JavaScript를 켜고 새로 고침해 주세요.
※ 이 사이트는 독립 운영되는 교육 프로젝트로, Anthropic의 공식 제품이 아니에요. Claude™ 는 Anthropic, PBC 의 상표예요.