Sub-agent (서브에이전트)¶

한 줄 정의¶

별도의 Claude를 하나 더 띄워서 독립적으로 일을 시키고, 결과만 받는 것.

비유¶

프리랜서 외주. 일감을 주면 알아서 하고, 결과 보고서만 보내준다. 내 사무실(메인 대화)에 와서 일하는 게 아니라, 자기 사무실에서 일한다.

핵심 특징¶

항목	내용
실행 주체	새로운 Claude가 별도로 생성되어 실행
실행 환경	독립된 컨텍스트 (메인 대화와 분리)
저장 형식	`.claude/agents/이름.md` (마크다운 파일)
실행 방법	Claude가 자동 위임 또는 사용자가 지정
반복 사용	O (정의해두면 재사용)
코딩 필요	X (마크다운 자연어로 작성)

Skill과 핵심 차이¶

Skill:
  나 ↔ Claude (레시피 보고 직접 요리)
  → 대화 맥락을 공유함
  → 대량 작업 시 대화 맥락이 넘칠 수 있음

Sub-agent:
  나 ↔ Claude(메인) → Claude(팀원)
  → 팀원은 자기 공간에서 일함
  → 결과 요약만 메인에게 돌아옴
  → 메인 대화는 깔끔하게 유지

파일 구조¶

.claude/agents/researcher.md    ← 리서치 전문 서브에이전트
.claude/agents/reviewer.md      ← 리뷰 전문 서브에이전트

서브에이전트 파일 기본 형태¶

---
name: researcher
description: 주제에 대해 깊이 조사하는 리서치 전문가. 대량 자료 조사에 사용.
tools: Read, Grep, Glob, Bash
model: haiku                     # 저렴한 모델로 비용 절약
---

당신은 리서치 전문가입니다.
주어진 주제에 대해 깊이 조사하고, 핵심 발견사항을 요약하여 보고하세요.

조사 결과는 아래 형식으로 정리:
- 핵심 발견 3~5개
- 각 발견의 근거
- 추천 액션

Sub-agent의 3가지 장점¶

1. 컨텍스트 보호 (가장 실용적)¶

[대량 조사 Skill로 하면]
Claude가 파일 50개를 직접 읽음
→ 대화창이 조사 결과로 가득 참
→ 이후 "아까 그거 기반으로 글 써줘" 하면
→ 앞부분을 잊어버릴 수 있음

[Sub-agent로 하면]
팀원이 파일 50개를 자기 공간에서 읽음
→ "핵심 요약 5줄"만 메인에 전달
→ 메인 대화는 깔끔하게 유지

2. 모델 분리 (비용 절약)¶

model: haiku     # 간단한 조사: 빠르고 저렴
model: sonnet    # 일반 작업: 균형
model: opus      # 중요한 글쓰기: 최고 품질

3. 백그라운드 실행¶

Sub-agent에게 조사 시켜놓고
나는 메인 Claude와 다른 대화 계속 가능

실전 사용 예시¶

경쟁 도서 대량 분석¶

"경쟁 도서 30권의 목차와 리뷰를 분석해서 트렌드 보고서 만들어줘"
→ Sub-agent(haiku)가 대량 조사 → 요약만 돌아옴

웹 트렌드 리서치¶

"AI 글쓰기 시장 트렌드를 조사해줘. 백그라운드로 돌려놔"
→ 조사하는 동안 나는 다른 작업 진행

Sub-agent가 최적인 경우¶

파일 50개 이상 읽어야 하는 대량 조사
비용을 아끼고 싶을 때 (저렴한 모델로 돌리기)
동시에 다른 일을 하고 싶을 때 (백그라운드)
조사 결과로 메인 대화를 더럽히고 싶지 않을 때

Sub-agent가 과한 경우¶

사진 5장 보고 글 쓰는 정도 → Skill이면 충분
순차적 작업 → Skill이 더 간단
반복 워크플로우 → Skill의 /명령어가 더 편리

Skill과 Sub-agent 조합¶

Skill 안에서 context: fork를 쓰면, Skill의 편의성 + Sub-agent의 분리를 동시에 얻을 수 있다.

---
name: deep-research
description: 깊은 리서치
context: fork          # ← 이거 하나 추가하면 Sub-agent처럼 동작
agent: Explore         # ← 읽기 전용 에이전트로 실행
---

$ARGUMENTS 주제에 대해 깊이 조사하고 핵심만 요약해줘.

이렇게 하면 /deep-research AI 자서전 시장 명령어로 실행하면서도, 조사는 분리된 공간에서 진행되고 요약만 돌아온다.

주의사항 (실전에서 발견)¶

상세한 함정 목록과 체크리스트는 11-agent-design-guide.md 참조

WebFetch/WebSearch 사용 시: 프롬프트 맨 앞에 ToolSearch 사전 준비 블록 필수 (deferred tool 로딩)
권한 설정: 검색 전용이면 mode: "bypassPermissions", 파일 수정이면 mode: "default"
에이전트 간 결과 공유 불가: A의 결과를 B에 전달하려면 메인이 중계해야 함
1개가 여러 역할 하면 편향: 독립 관점 필요 시 별개 에이전트로 분리

참고¶

공식 문서
Agent 설계 실전 가이드 — 함정, 체크리스트, 사고 일지
Sub-agent는 "전문 팀원 고용"과 같다
대부분의 일상 업무는 Skill로 충분하지만, 규모가 큰 작업에는 Sub-agent가 효율적