Ch11. 에이전트·서브에이전트
이 장을 끝내면 할 수 있는 것: 짧은 일은 메인 에이전트로, 큰 일은 서브에이전트로 — 두 자리를 1초 안에 구분해서 시킬 수 있다.
1. 두 컨셉 한눈 — 자리가 다르다
"에이전트"라는 말은 한 단어가 아니다. Anthropic 공식 분류로 두 자리가 있고, 자리만 다르고 동작은 같다.
| 컨셉 | 한 줄 정의 | 일하는 자리 | 결과를 누가 보나 |
|---|---|---|---|
| 메인 에이전트 | 메인 Claude가 직접 자율 동작 | 사용자와 같은 컨텍스트 | 사용자가 모든 단계 봄 |
| 서브에이전트 | 메인이 위임한 별도 워커 | 격리된 자기 컨텍스트 | 사용자는 요약만 봄 |
공식 한 줄: "Subagents work within a single session; agent teams coordinate across separate sessions." — Anthropic Sub-agents
비유로 한 줄:
- 메인 에이전트 = 사장님이 직접 책상 앞에서 일하는 모드
- 서브에이전트 = 사장님이 직원에게 일을 맡기고 결과 보고만 받는 모드
📌 에이전트 팀(여러 세션 사이 협업)은 이 책에서 다루지 않는다. 정상 작동하려면
TeamCreate·TaskCreate·SendMessage+ 별도 오케스트레이터까지 갖춰야 하는 영역으로, 비개발자가 한 시간 안에 손에 익히기엔 무겁다. 익숙해진 뒤 공식 Agent Teams 가이드로.
이 장이 책에서 다뤄질 가치는 한 가지다 — 자기 일을 두 자리 중 어디에 얹어야 하는지 1초 안에 결정한다. 결정의 기준은 단순하다 — 자료가 큰가, 작은가.
같은 자율 동작이 메인 자리(직접 일함)와 서브 자리(위임받아 일함)에서 다르게 작동한다
2. 메인 에이전트 — 사용자와 같은 자리에서 직접
메인 에이전트는 메인 Claude가 자기 컨텍스트 안에서 자율적으로 일하는 모드다. 단순 1턴 응답이 아니라 컨텍스트 파악 → 도구 선택 → 실행 → 평가 → 다음 단계 의 루프를 돈다.
| 비교 | 챗봇 | 메인 에이전트 |
|---|---|---|
| 동작 | 1턴 응답 | 다중 턴 자율 |
| 도구 사용 | 없거나 제한 | 자유 |
| 컨텍스트 | 휘발 | 누적 |
| 사용자 시야 | 답 한 번 | 모든 단계 보임 |
메인 에이전트에 맞는 일 — "작고 짧은 작업"
데이터가 컨텍스트에 들어와도 부담 없을 정도의 작은 일. 사용자가 중간 단계를 보고 싶은 일.
| 일 | 메인이 자율로 하는 5 단계 |
|---|---|
| 다음 주 일정 표 만들기 | ① 메모 읽기 → ② 요일·시간 추출 → ③ 표 생성 → ④ CLAUDE.md 형식 적용 → ⑤ 사용자에게 보여주기 |
| 받은 메일 50개 분류 | ① 메일 읽기 → ② 카테고리 자동 분류 → ③ 표 정리 → ④ 다음 액션 추천 |
| 회의록 1장 5줄 요약 | ① 파일 1개 읽기 → ② 핵심 5줄 → ③ 액션 표 → ④ output/ 저장 |
| CSV 한 장 통계 내기 | ① 파일 읽기 → ② 합계·평균 → ③ 카테고리 분포 표 |
기준 한 줄: 입력 자료가 5만 토큰 안쪽이면 메인. 사용자가 "방금 뭐 했지?" 묻고 싶으면 메인.
3. 서브에이전트 — 메인이 위임한 격리 워커
서브에이전트는 메인 Claude가 자기 일을 더 큰 일로 위임하는 별도 워커다. 자기만의 컨텍스트·시스템 프롬프트·도구로 작업하고, 작업이 끝나면 결과 요약만 메인에 반환한다.
| 축 | 메인 에이전트 | 서브에이전트 |
|---|---|---|
| 컨텍스트 | 사용자와 공유 | 자기만의 윈도우 (격리) |
| 사용자 시야 | 모든 단계 보임 | 결과 요약만 보임 |
| 호출 방 식 | 직접 메시지 | 메인이 Task 도구로 위임 |
| 도구 | 메인의 전체 권한 | 화이트리스트로 제한 |
| 적합한 자료 | 5만 토큰 안쪽 | 5만 토큰 초과·전문 작업 |
서브에이전트의 4가지 진짜 역할
서브에이전트는 단순히 "메인을 덜 무겁게" 하는 게 아니라 4가지 분명한 역할이 있다. 각각 다른 에이전트 예시.
역할 ① 큰 자료 탐색 — code-explorer
---
name: code-explorer
description: 큰 코드베이스에서 특정 기능의 위치를 찾는다. "어디에 로그인 로직 있어" 같은 표현에 사용.
tools: Read, Glob, Grep
model: sonnet
---
You are a code explorer. Search the entire codebase for the requested feature.
Return ONLY 3 most relevant file paths + 1-line description each. No code dumps.
사용 예: 50,000줄짜리 회사 코드. 메인 Claude에게 "로그인 로직 어디 있어?" 던지면 메인이 code-explorer에 위임.
- 서브에이전트가 50K줄을 자기 컨텍스트에서 다 훑음
- 메인에 반환: "3 파일:
auth.js(검증) /login.tsx(UI) /session.ts(토큰)" - 메인 컨텍스트엔 3 줄만 들어옴. 50K 줄 원문은 서브 안에서만 머묾.
역할 ② 전문 작업 격리 — security-reviewer
---
name: security-reviewer
description: 배포 전 시크릿 노출·취약점을 점검한다. "보안 점검", "git push 전" 표현에 사용.
tools: Read, Grep, Bash
model: opus
---
You are a security reviewer. Check git changes for:
1. API keys, tokens, .env leaks
2. XSS, SQL injection patterns
3. OWASP Top 10 risks
Return: PASS or list of findings with severity.
사용 예: GitHub push 직전. 메인 Claude에게 "보안 점검해줘" 한 줄.
- 서브에이전트가 모든 변경 파일을 자기 컨텍스트에서 스캔
- 메인에 반환: "발견 2건:
.env누출 + XSS 의심 1건" 또는 "PASS" - 메인은 그 결과로 다 음 행동만 결정 (push할지 멈출지).
역할 ③ 외부 리서치 — research-runner
---
name: research-runner
description: 경쟁사·논문·시장 자료를 웹에서 수집해 비교 표로 정리. "경쟁사 비교", "리서치" 표현에 사용.
tools: WebFetch, WebSearch
model: sonnet
---
You are a market researcher. Find requested companies/papers.
Return: comparison table only (no full transcripts).
사용 예: "우리 제품의 경쟁사 5곳 가격·기능 표로 정리해줘" 한 줄.
- 서브에이전트가 5개 웹사이트 풀 텍스트를 자기 컨텍스트에서 처리
- 메인에 반환: "5 × 4 비교 표 1장"
- 메인 컨텍스트엔 표만. 원본 5개 HTML 은 서브 안에만.
역할 ④ 긴 문서 압축 — doc-summarizer
---
name: doc-summarizer
description: 100페이지+ PDF·정책 문서에서 우리에게 필요한 5조항만 추출. "긴 문서 요약" 표현에 사용.
tools: Read
model: haiku
---
You are a document summarizer. Extract only the requested clauses.
Return: 5 most relevant clauses, each in 1 sentence.
사용 예: 100페이지 회사 정책 PDF. "우리 부서 출장 규정 5조 항목 5줄로" 한 줄.
- 서브에이전트(Haiku — 저렴)가 100페이지를 다 읽음
- 메인에 반환: "출장비 한도 5조 5줄"
- 비용 절감: Haiku 라우팅으로 Opus의 1/10 비용.
서브에이전트의 4 이득 (공식)
위 4 역할이 그대로 공식 이득과 매칭된다.
| 이득 | 매칭 역할 |
|---|---|
| Preserve context — 메인 대화 깨끗하게 | ① code-explorer · ④ doc-summarizer |
| Enforce constraints — tools 제한으로 안전 | ② security-reviewer (Bash 가능) |
| Reuse configurations — 모든 프로젝트 재사용 | 4 가지 모두 |
| Control costs — Haiku 같은 저렴 모델 라우팅 | ④ doc-summarizer (Haiku) |
제작 — YAML frontmatter (공식)
---
name: code-explorer
description: 큰 코드베이스 탐색. "어디에 X 있어" 표현.
tools: Read, Glob, Grep
model: sonnet
isolation: worktree
---
You are a code explorer. ...
저장 위치: ~/.claude/agents/NAME.md (모든 프로젝트) 또는 .claude/agents/NAME.md (이 프로젝트만).
4. 선택 가이드 — 1초 결정
| 질문 | 답 |
|---|---|
| 입력 자료가 5만 토큰 안쪽인가? | YES → 메인 에이전트 |
| 큰 자료를 훑어 핵심만 받고 싶나? | YES → 서브에이전트 ① (code-explorer 유) |
| 전문 도구 권한이 필요한가? (Bash·WebFetch) | YES → 서브에이전트 ② (security-reviewer 유) |
| 같은 작업을 여러 프로젝트에서 반복? | YES → 서브에이전트 ③ (재사용) |
| 비용을 줄이고 싶나? | YES → 서브에이전트 ④ (Haiku 라우팅) |
기억할 한 줄: 자료가 작으면 메인, 크면 서브. 그게 전부.
5. ⚠️ 처음 사람들이 자주 막히는 곳
함정 1. 서브에이전트 결과 = 요약만
서브에이전트는 자기 컨텍스트에서 깊이 작업하지만, 메인에 돌려주는 건 요약만이다. 디테일이 필요하면 description에 "5줄 + 원본 인용 3개" 같이 명시.
함정 2. 작은 일까지 서브로 위임
5천 토큰짜리 회의록 1장에 서브에이전트를 부르면 위임 오버헤드가 더 크다. 메인이 직접 하는 게 빠르다.
기준: 자료가 5만 토큰 넘을 때만 서브.
함정 3. tools 무제한 → 보안 사고
서브에이전트의 tools: 필드를 비워두거나 *로 두면 모든 도구 접근 가능. 화이트리스트로 좁힌다.
| 서브에이전트 | 추천 tools |
|---|---|
| code-explorer | Read, Glob, Grep (수정 X) |
| security-reviewer | Read, Grep, Bash (변경 X) |
| research-runner | WebFetch, WebSearch (로컬 X) |
| doc-summarizer | Read |
함정 4. 정의 파일 없이 prompt에 박는 안티패턴
급하다고 정의 파일을 안 만들고 prompt에 "넌 code-explorer야" 한 줄로 박으면 다음 세션에 재사용 못 한다. 반드시 .claude/agents/NAME.md 파일로.
좌: prompt에 박힌 임시 에이전트, 우: .claude/agents/NAME.md 정식 정의
6. 5분 미니 실습 — 메인 vs 서브 한 번씩
전제
- Ch10을 끝내 SKILL.md 한 장을 작성해봤다
- 작은 작업 1개 + 큰 작업 1개를 미리 정해 둔다
단계
Step 1 — 메인 에이전트 (작은 일)
새 대화창에 한 줄:
data/today-schedule.md 를 읽고 [요일 / 시간 / 항목] 표로 만들어줘.
✓ 체크포인트: 메인 Claude가 알아서 읽기 → 추출 → 표 생성의 자율 루프를 돈다. 모든 단계가 메시지 창에 보인다.
Step 2 — 서브에이전트 (큰 일)
.claude/agents/doc-summarizer.md 작성:
---
name: doc-summarizer
description: 긴 PDF·정책 문서에서 우리에게 필요한 5조항만 추출. "긴 문서 요약" 표현에 사용.
tools: Read
model: haiku
---
You are a document summarizer.
Read the file, extract only the 5 most relevant clauses.
Return: 5 sentences, each one clause. No full text.
같은 대화에서 큰 PDF/긴 마크다운에:
data/policy-100p.md 에서 출장 규정만 5조항 뽑아줘.
✓ 체크포인트: 메인이 doc-summarizer를 호출했다는 표시 + 메인 메시지창엔 5줄만 들어옴. 원본 100페이지는 안 보임.
Step 3 — 차이 직접 비교
두 작업의 메시지 창을 나란히 본다.
- Step 1 (메인): 모든 중간 단계가 메시지에 쌓임
- Step 2 (서브): 결과 5줄만. 깔끔.
결과 인증
이 실습을 끝냈다면:
- 같은 도메인의 작은 일·큰 일이 어떻게 다르게 다뤄지는지 안다
- 메인 메시지창의 "무게" 차이를 눈으로 봤다
- 다음 일에 1초 안에 자리 결정 가능
⚠️ 트러블슈팅
문제 1: 서브에이전트가 호출은 됐는데 결과가 어색합니다. → description의 트리거 표현 부족. 키워드 2~3개 명시.
문제 2: 서브에이전트가 권한 없는 도구를 시도합니다.
→ tools: 화이트리스트가 너무 좁음. 필요한 도구만 추가.
문제 3: 작은 일에 서브를 불렀더니 더 느려졌습니다. → 정상. 위임 오버헤드 때문. 5만 토큰 미만은 메인으로.
7. 끝맺으며 — 1시간 입문서를 닫는 한 장
여기까지 11장. 첫 페이지에서 약속한 한 줄을 다시 적는다.
"코딩을 한 번도 해본 적 없어도, 60분 안에 Claude Code를 자기 손에 익힌다."
11장의 길이는 책으로는 한 권이지만, 손에 익히는 데 필요한 시간은 60분이다. 매주 한 챕터씩 11주에 나눠 익혀도 된다. 한 권을 끝낸 시점에 손에 남는 건 다음 5가지.
| 손에 가진 것 | 어디서 |
|---|---|
| Claude Code 켜고 첫 응답 받는 손 | Ch1~Ch3 |
| CLAUDE.md · 자동화 3종 · 6 장치 큰 그림 | Ch4~Ch6 |
| 슬래시 사전 · 토큰 절약 | Ch7~Ch8 |
| 커넥터·스킬로 외부 연결·자동화 | Ch9~Ch10 |
| 메인·서브 에이전트로 자료 크기에 맞 게 위임 | Ch11 |
다음 단계는 자기 일 1개를 골라 위 5개 중 어울리는 자리에 얹는 것이다. Claude Code는 도구이지 결과물이 아니다. 결과물은 사용자가 자기 일을 줄여 만든 시간이다.
좋은 시간 보내시기를.
© 2026 COMMME · Built with Claude Code