커스텀 서브에이전트 만들기

서브에이전트는 특정 종류의 작업을 처리하는 전문화된 AI 어시스턴트예요. 사이드 작업이 검색 결과·로그·파일 내용으로 메인 대화를 뒤덮을 때 서브에이전트에게 맡기면 그 작업이 자기 컨텍스트 안에서 끝나고 요약만 돌아오죠. 각 서브에이전트는 자체 시스템 프롬프트·도구 접근·권한으로 독립된 컨텍스트 윈도우에서 돌아갑니다. 이 문서에서는 내장 서브에이전트부터 커스텀 정의(frontmatter, 모델, 도구, 훅, 격리), 병렬 실행, 포크까지 다룹니다.

출처: 공식문서

본문

서브에이전트가 도와주는 일

컨텍스트 보존 — 탐색과 구현을 메인 대화 밖으로 분리
제약 강제 — 서브에이전트가 쓸 수 있는 도구 제한
구성 재사용 — 사용자 레벨 서브에이전트로 프로젝트 간 공유
행동 전문화 — 특정 도메인에 초점 맞춘 시스템 프롬프트
비용 통제 — Haiku 같은 빠르고 값싼 모델로 작업 라우팅

Claude는 각 서브에이전트의 description을 보고 언제 위임할지 정해요. 서브에이전트를 만들 때 클로드가 언제 쓸지 알 수 있게 설명을 잘 써야 해요. 설명은 컨텍스트를 차지하므로 짧게 유지하세요. 내장 서브에이전트를 제외한 당신 서브에이전트들의 설명 합계가 15,000 토큰을 넘으면, Claude Code는 시작 시 총 토큰 수와 함께 경고를 표시합니다. description은 줄이고 자세한 내용은 해당 서브에이전트가 실행될 때만 로드되는 시스템 프롬프트로 옮기세요.

서브에이전트는 단일 세션 안에서 작동해요. 여러 독립 세션을 병렬로 돌리고 한 곳에서 모니터링하려면 background agents, 서로 메시지를 주고받는 별도 세션은 cross-session messaging, Claude가 생성·감독하는 조정된 팀은 agent teams를 보세요.

내장 서브에이전트

Claude Code에는 적절할 때 Claude가 자동으로 쓰는 내장 서브에이전트가 있어요. 각각은 부모 대화의 권한을 상속하며, 대부분 제한된 도구 세트로 돌아갑니다.

Explore — 코드베이스 검색·분석에 최적화된 빠른 읽기 전용 에이전트.

모델: 메인 대화에서 상속하되 Claude API에서는 Opus에서 상한. CLAUDE_CODE_SUBAGENT_MODEL로 모든 서브에이전트에 강제하지 않는 한 Explore가 당신이 고른 모델보다 비싼 모델에서 돌지 않게 함
도구: 읽기 전용 도구; Write와 Edit는 거부됨
목적: 파일 발견, 코드 검색, 코드베이스 탐색

v2.1.198부터 Explore는 항상 Haiku로 도는 대신 메인 대화의 모델을 상속해요. Claude API에서 상속 모델은 Opus로 상한: 상위 단계 메인 대화는 Explore를 Opus로, Sonnet이나 Haiku 메인 대화는 같은 모델로 돌립니다. Amazon Bedrock, Google Cloud Agent Platform, Microsoft Foundry, Claude Platform on AWS 같은 다른 프로바이더에서는 Explore가 메인 대화 모델을 그대로 상속해요. Explore라는 이름의 user/project 서브에이전트는 내장 것을 덮어쓰고 자기 model 필드를 유지하므로, model: haiku로 정의하면 탐색을 저비용 모델에 유지할 수 있어요.

Claude는 변경 없이 코드베이스를 검색·이해해야 할 때 Explore에 위임합니다. Explore 호출 시 Claude는 철저도 수준을 지정해요: quick(목표 검색), medium(균형), very thorough(포괄 분석).

Plan — plan mode 중 계획을 제시하기 전에 컨텍스트를 모으는 리서치 에이전트.

모델: 메인 대화에서 상속 (CLAUDE_CODE_SUBAGENT_MODEL 미설정 시)
도구: 읽기 전용; Write·Edit 거부
목적: 계획을 위한 코드베이스 리서치

plan mode에서 Claude가 코드베이스를 이해해야 할 때 Plan 서브에이전트에 리서치를 위임해 탐색 출력을 별도 컨텍스트 윈도우에 두고 메인 대화는 읽기 전용으로 유지합니다.

General-purpose — 탐색과 실행이 모두 필요한 복잡한 다단계 작업용 에이전트.

모델: CLAUDE_CODE_SUBAGENT_MODEL을 설정했다면 그 모델, 아니면 메인 대화의 모델
도구: 서브에이전트에 사용 가능한 모든 도구
목적: 복잡한 리서치, 다단계 작업, 코드 수정

Claude는 탐색+수정, 결과 해석을 위한 복잡한 추론, 여러 종속 단계가 필요할 때 general-purpose에 위임해요.

기타 도우미 에이전트

에이전트	모델	Claude가 쓰는 때
`claude`	자체 모델 없음; 서브에이전트로 스폰될 때 모델 순서를 따름	더 전문화된 에이전트에 맞지 않는 작업. 서브에이전트에 사용 가능한 모든 도구를 가진 catch-all. 배치된 background 세션의 기본 에이전트이기도 함
`statusline-setup`	Sonnet	`/statusline`으로 스테이터스 라인 설정 시
`claude-code-guide`	Haiku	Claude Code 기능에 대해 물어볼 때

내장 서브에이전트는 인터랙티브 세션에서 기본 등록됩니다. 제한하려면:

특정 내장 유형을 차단하려면 Disable specific subagents처럼 permissions.deny에 추가
아무 서브에이전트에 위임하지 못하게 하려면 permissions.deny로 Agent 도구 자체를 거부
내장 Explore·Plan만 제거하려면 CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 설정. Claude가 위임 대신 파일을 직접 읽고 탐색. Claude Code v2.1.198 이상 필요
non-interactive mode와 Agent SDK에서는 CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1로 모든 내장 유형을 제거하고 당신 것만 공급

subagent_type을 생략한 Agent 도구 호출은 세션에 대체할 general-purpose 서브에이전트가 없으면 subagent_type is required로 실패합니다.

퀵스타트: 첫 서브에이전트 만들기

서브에이전트는 YAML frontmatter가 있는 Markdown 파일이에요. Claude에게 작성하라고 하거나 직접 파일을 쓸 수 있어요.

v2.1.198부터 /agents 명령은 인터랙티브 생성 마법사를 더 이상 열지 않고, Claude에게 부탁하거나 .claude/agents/를 직접 편집하라는 안내를 출력합니다. 서브에이전트 파일·frontmatter 필드·.claude/agents/·~/.claude/agents/ 위치는 그대로이며, 터미널 마법사만 제거됐어요.

Claude에게 서브에이전트 생성을 요청 — 원하는 서브에이전트와 저장 위치를 설명하세요.

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

Claude는 name, description, tools 목록, model, 시스템 프롬프트가 담긴 파일을 씁니다.

파일 검토 — ~/.claude/agents/code-improver.md를 열고 frontmatter가 요청과 일치하는지 확인하세요.

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

~/.claude/agents/에 있으므로 이 서브에이전트는 이 머신의 모든 프로젝트에서 쓸 수 있어요. 한 프로젝트로 한정하려면 그 프로젝트의 .claude/agents/로 옮기세요.

시험 — Claude에게 새 서브에이전트에 위임하라고 요청하세요.

Use the code-improver agent to suggest improvements in this project

트랜스크립트에서 위임은 code-improver(Suggest code improvements)처럼 서브에이전트 이름과 짧은 작업 설명이 붙은 도구 호출 행으로 나타납니다. Claude가 새 서브에이전트를 못 찾으면 Claude Code를 재시작하세요. 이는 세션 시작 전에 ~/.claude/agents/가 없었을 때만 발생하는데, 실행 중인 세션은 새로 생긴 agents 디렉터리를 감지하지 못하기 때문이에요.

서브에이전트 구성

서브에이전트 파일 위치가 누구에게 제공될지를, frontmatter가 무엇을 할 수 있는지를 결정합니다.

서브에이전트 범위 선택

위치	범위	우선순위	만드는 방법
Managed settings	조직 전체	1 (최고)	managed settings로 배포
`--agents` CLI 플래그	현재 세션	2	Claude Code 실행 시 JSON 전달
`.claude/agents/`	현재 프로젝트	3	Claude에 요청하거나 수동 생성
`~/.claude/agents/`	모든 프로젝트	4	Claude에 요청하거나 수동 생성
Plugin의 `agents/` 디렉터리	플러그인 활성 위치	5 (최저)	플러그인으로 설치

프로젝트 서브에이전트(.claude/agents/)는 코드베이스 특정용으로 이상적. 팀이 협업으로 쓰고 개선하도록 버전 관리에 커밋하세요. 프로젝트 서브에이전트는 현재 작업 디렉터리에서 위로 올라가며 발견되므로, 그 사이와 저장소 루트 사이의 모든 .claude/agents/가 스캔됩니다. v2.1.178부터 둘 이상의 중첩 디렉터리가 같은 name을 정의하면 작업 디렉터리에 가장 가까운 정의를 사용해요. --add-dir//add-dir로 디렉터리를 추가하면 그 .claude/agents/ 폴더도 프로젝트 서브에이전트 옆에 로드됩니다. --add-dir 없이 프로젝트 간 공유하려면 ~/.claude/agents/나 플러그인을 쓰세요.

사용자 서브에이전트(~/.claude/agents/)는 모든 프로젝트에서 쓸 수 있는 개인 서브에이전트입니다.

Claude Code는 .claude/agents/와 ~/.claude/agents/를 재귀적으로 스캔하므로 agents/review/ 같은 하위 폴더로 구성할 수 있어요. 서브디렉터리 경로는 식별·호출에 영향을 주지 않습니다. 정체성은 오직 name frontmatter 필드에서 나오기 때문이죠. name은 전체 트리에서 유일하게 유지하세요. 같은 .claude/agents/ 디렉터리(하위 폴더 포함) 안 두 파일이 같은 이름이면 문서화된 우선순위가 아니라 파일시스템 읽기 순서로 하나만 로드됩니다. /doctor 셋업 점검이 같은 디렉터리에서 이름을 공유하는 파일을 보고하고 하나만 남기도록 이름 바꾸기·제거를 제안합니다.

플러그인 agents/ 디렉터리도 재귀적으로 스캔됩니다. 프로젝트·사용자 범위와 달리, 플러그인 agents/ 내부의 하위 폴더는 scoped 식별자의 일부가 돼요: 플러그인 my-plugin의 agents/review/security.md는 my-plugin:review:security로 등록됩니다.

CLI 정의 서브에이전트는 Claude Code 실행 시 JSON으로 전달됩니다. 그 세션에만 존재하고 디스크에 저장되지 않아 빠른 테스트·자동화에 유용해요. 단일 --agents 호출로 여러 서브에이전트를 정의할 수 있어요:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

Windows PowerShell:

claude --agents @'
{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}
'@

--agents 플래그는 prompt 필드와 함께 frontmatter 필드(description, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, skills, initialPrompt, memory, effort, background, isolation)를 받아요. 시스템 프롬프트에는 파일 기반 서브에이전트의 마크다운 본문에 해당하는 prompt를 씁니다. JSON의 각 최상위 키가 에이전트 이름이에요. 이름을 -로 시작하지 마세요.

Managed 서브에이전트는 조직 관리자가 배포합니다. managed settings 디렉터리 안 .claude/agents/에 같은 frontmatter 형식으로 마크다운 파일을 두세요. Managed 정의는 같은 이름의 프로젝트·사용자 서브에이전트보다 우선합니다.

플러그인 서브에이전트는 설치한 플러그인에서 옵니다. 커스텀 서브에이전트와 함께 자동 로드되고 @-언급 타입어헤드에 scoped 이름으로 나타납니다.

보안상 플러그인 서브에이전트는 hooks, mcpServers, permissionMode frontmatter 필드를 지원하지 않습니다. 이 필드는 플러그인에서 에이전트를 로드할 때 무시돼요. 필요하면 에이전트 파일을 .claude/agents/나 ~/.claude/agents/로 복사하세요. 또한 settings.json/settings.local.json의 permissions.allow에 규칙을 추가할 수 있지만, 이 규칙은 플러그인 서브에이전트만이 아니라 세션 전체에 적용됩니다.

서브에이전트 파일 작성

서브에이전트 파일은 구성에 YAML frontmatter, 이어서 시스템 프롬프트를 마크다운으로 씁니다.

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

frontmatter는 메타데이터·구성을 정의하고, 본문은 행동을 이끄는 시스템 프롬프트가 됩니다. 서브에이전트는 이 시스템 프롬프트와 작업 디렉터리 같은 기본 환경 정보만 받으며 Claude Code 시스템 프롬프트는 받지 않아요.

non-interactive mode에서는 --append-subagent-system-prompt로 중첩 서브에이전트를 포함해 모든 서브에이전트의 시스템 프롬프트 끝에 텍스트를 추가할 수 있어요 (fork는 대화의 자체 프롬프트를 재사용하므로 제외). Claude Code v2.1.205 이상 필요. 명령줄로 넘기기엔 너무 길면 파일로 저장하고 --append-subagent-system-prompt-file로 경로를 넘기세요 (v2.1.261 이상 필요).

서브에이전트는 메인 대화의 현재 작업 디렉터리에서 시작해요. 서브에이전트 안의 cd는 Bash/PowerShell 도구 호출 사이에 유지되지 않고 메인 대화의 작업 디렉터리에도 영향을 주지 않아요. 대신 저장소의 격리된 사본을 주려면 isolation: worktree를 설정하세요.

isolation: worktree 서브에이전트는 Bash·PowerShell 명령을 자기 워크트리 안에서 실행합니다. 작업 디렉터리가 메인 체크아웃으로 해석되는 명령(예: 서브에이전트 실행 중 워크트리 디렉터리가 제거된 경우)은 오류로 실패해요. Bash 명령에 대해 Claude Code는 명령 자체를 두 가지로도 검사합니다: 메인 체크아웃으로 git을 리다이렉트하는 명령 차단, 명령 텍스트만으로 실행되는 git이 워크트리 안에 머무는지 검증할 수 없을 때(런타임에 명령 이름이 계산되는 경우) 거부. PowerShell 명령은 작업 디렉터리 검사만 받습니다. Monitor 명령은 Bash 명령과 같은 검사를 거칩니다.

지원되는 frontmatter 필드

name과 description만 필수입니다.

필드	필수	설명
`name`	예	소문자·하이픈을 쓰는 유일 식별자. Hooks가 이 값을 `agent_type`으로 수신. 파일명은 일치할 필요 없음. 이름에 플러그인 scoped 식별자(`my-plugin:reviewer` 같은)용으로 예약된 `:`은 넣을 수 없음
`description`	예	Claude가 언제 이 서브에이전트에 위임할지
`tools`	아니오	서브에이전트가 쓸 도구. 생략 시 서브에이전트에 사용 가능한 모든 도구 상속. 목록의 어떤 항목도 도구로 해석되지 않으면 보통 실행 실패. Skill을 컨텍스트에 프리로드하려면 `Skill`을 나열하지 말고 `skills` 필드 사용
`disallowedTools`	아니오	거부할 도구. 상속·지정 목록에서 제거. `Bash(git push *)` 같은 지정자가 있는 항목도 전체 도구를 제거
`model`	아니오	모델: `sonnet`, `opus`, `haiku`, `fable`, `claude-opus-5` 같은 전체 모델 ID, 또는 `inherit`. 생략 시 서브에이전트 모델 순서대로 선택
`permissionMode`	아니오	권한 모드: `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan`, `default`의 별칭 `manual`(v2.1.200 이상). [플러그인 서브에이전트]에선 무시
`maxTurns`	아니오	서브에이전트가 멈추기 전 최대 에이전트 턴 수. 한도 도달 시 Claude Code는 출력을 partial로 표시하고 Claude는 재개 가능 (v2.1.246 이상)
`skills`	아니오	시작 시 서브에이전트 컨텍스트에 프리로드할 스킬. 설명뿐 아니라 전체 스킬 내용이 주입
`mcpServers`	아니오	이 서브에이전트에 제공될 MCP 서버. 구성된 서버를 참조하는 이름(`"slack"`) 또는 인라인 정의. [플러그인 서브에이전트]에선 무시
`hooks`	아니오	이 서브에이전트에 한정된 라이프사이클 훅. [플러그인 서브에이전트]에선 무시
`memory`	아니오	영구 메모리 범위: `user`, `project`, `local`. 세션 간 학습 활성화
`background`	아니오	`true`로 설정하면 Claude가 포그라운드 실행을 요청해도 이 서브에이전트를 백그라운드로 유지
`effort`	아니오	이 서브에이전트 활성 시 노력 수준. 세션 effort 수준을 덮어씀. 기본: 세션 상속. 값: `low`, `medium`, `high`, `xhigh`, `max`; 모델에 따라 다름
`isolation`	아니오	`worktree`로 설정하면 임시 git 워크트리에서 실행. 기본적으로 부모 세션의 `HEAD`가 아니라 기본 브랜치에서 분기. 변경이 없으면 워크트리는 자동 정리
`color`	아니오	작업 목록·트랜스크립트에서 표시 색상. `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`
`initialPrompt`	아니오	이 에이전트가 메인 세션 에이전트로 실행될 때(`--agent` 또는 `agent` 설정) 첫 사용자 턴으로 자동 제출. 명령·스킬 처리. 사용자 제공 프롬프트 앞에 붙음
`experimental`	아니오	실험 옵션 맵. `cacheTtl` 키를 `5m` 또는 `1h`로 설정해 프롬프트 캐시 수명을 선택 (v2.1.248 이상)

cacheTtl은 frontmatter 최상위가 아니라 experimental 맵 안에 쓰세요.

---
name: repo-auditor
description: Audits a large repository and reports what it finds
experimental:
  cacheTtl: 1h
---

Claude Code가 건너뛰는 서브에이전트 파일

프로젝트·사용자·managed agents 디렉터리의 파일이 다음 문제를 가지면 세션에 보고 없이 건너뜁니다: name 없음(문서로 취급), 파일 첫 줄이 아닌 시작 ---(frontmatter 없는 것으로 읽음), -로 시작하거나 :을 포함한 name(오류를 디버그 로그에 기록), name인데 description 없음(이유를 디버그 로그에 기록), 파싱 안 되는 YAML(파싱 오류를 디버그 로그에 기록). 디버그 로그는 --debug로 봅니다.

세션 전에 `agents` 디렉터리 검사

frontmatter가 파싱되지 않는 agents 디렉터리의 파일을 찾으려면 디렉터리에 대해 claude plugin validate를 실행하세요, 예: .claude/agents 또는 ~/.claude/agents. Claude Code는 지정한 디렉터리만 검사하고, 파싱은 되지만 name이 없는 파일은 표시하지 않아요 (v2.1.233 이상).

모델 선택

model 필드가 서브에이전트가 쓸 모델을 제어합니다: 모델 별칭(sonnet, opus, haiku, fable), 전체 모델 ID(claude-opus-5·claude-sonnet-5 같은, --model 플래그와 같은 값), inherit(메인 대화와 같은 모델).

Claude가 서브에이전트를 호출할 때 해당 호출에 model 파라미터를 넘길 수도 있어요. Claude Code는 서브에이전트 모델을 다음 순서로 해석합니다:

호출별 model 파라미터
서브에이전트 정의의 model frontmatter (inherit는 메인 대화 모델 선택)
모델 별칭·ID로 설정한 CLAUDE_CODE_SUBAGENT_MODEL 환경변수
메인 대화의 모델

CLAUDE_CODE_SUBAGENT_MODEL만 설정한다고 내장 Explore·Plan 서브에이전트의 모델이 바뀌진 않아요. 바꾸려면 Run every subagent on one model을 보세요. v2.1.251 이전에는 이 변수가 순서에서 첫 번째여서 호출별 파라미터와 frontmatter(model: inherit 포함)를 모두 덮어썼습니다. 변수를 inherit로 설정하는 건 설정 안 하는 것과 같아요.

Claude Code는 호출별 파라미터·frontmatter·환경변수 값을 조직의 availableModels 허용 목록과 대조합니다. 차단된 값은 다른 모델로 대체됩니다: 차단 값이 opus 같은 패밀리 별칭이면 허용 목록이 허용하는 그 패밀리의 최신 버전으로 실행하고, 다른 차단 값이면 상속된 모델로 실행합니다. 인터랙티브 세션에서는 요청된 모델과 실제 실행 모델을 명명하는 경고를 표시합니다. 서브에이전트가 어떤 모델로 도는지 보려면 /tasks를 실행하세요 (v2.1.242 이상에서 effort 수준도 표시).

v2.1.198부터 서브에이전트는 메인 대화의 확장 사고 구성도 상속합니다: 세션에서 thinking이 켜져 있으면 서브에이전트도 켜짐, 꺼져 있으면 꺼짐. 서브에이전트별 thinking 설정은 없어요. v2.1.198 이전에는 메인 대화 설정과 무관하게 서브에이전트는 확장 사고를 비활성화한 채 돌았습니다.

모든 서브에이전트를 하나의 모델로 실행

CLAUDE_CODE_SUBAGENT_MODEL은 기본값이므로 서브에이전트 정의나 Claude가 넘긴 모델이 여전히 우선해요. 모든 서브에이전트·팀메이트·워크플로우 에이전트에 하나의 모델을 적용하려면 CLAUDE_CODE_SUBAGENT_MODEL_FORCE도 1로 설정하세요 (v2.1.257 이상). 두 변수를 모두 설정하면 CLAUDE_CODE_SUBAGENT_MODEL의 모델로, CLAUDE_CODE_SUBAGENT_MODEL_FORCE만 설정하면 메인 대화 모델로 실행합니다.

예를 들어 모든 서브에이전트를 Haiku로 돌리려면 settings 파일의 env 블록에 둘 다 설정하세요:

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

CLAUDE_CODE_SUBAGENT_MODEL_FORCE가 켜져 있는 동안 Claude Code는 모든 서브에이전트 정의의 model 필드를 무시하고 Claude가 서브에이전트를 시작할 때 모델을 넘길 수 없어요. 그래도 메인 대화 모델로 도는 두 가지 서브에이전트: fork, model: inherit인 스킬 실행.

서브에이전트 기능 제어

사용 가능한 도구

서브에이전트는 메인 대화에서 사용 가능한 내장 도구와 MCP 도구를 상속하되 두 필터로 좁혀집니다. 첫 번째는 모든 서브에이전트에서 짧은 도구 목록을 제거하고, 두 번째는 기본인 백그라운드 실행 서브에이전트의 내장 도구 세트를 줄입니다. fork는 두 필터를 모두 건너뛰고 메인 대화의 정확한 도구 풀을 받아요.

첫 번째 필터가 제거하는 도구(tools 필드에 나열돼 있어도): Agent(깊이 한도에서; fork에서는 나열되지만 스폰 대신 오류 반환), AskUserQuestion, EndConversation(메인 대화만 끝낼 수 있음), EnterPlanMode, ExitPlanMode(서브에이전트 permissionMode가 plan이 아니면), ScheduleWakeup, TaskOutput, WaitForMcpServers, Workflow.

두 번째 필터는 백그라운드 실행 서브에이전트에 적용됩니다. 백그라운드 서브에이전트는 모든 MCP 도구를 유지하지만 내장 도구 중에는 Read, Grep, Glob, Bash, PowerShell, Edit, Write, NotebookEdit, WebFetch, WebSearch, TodoWrite, Skill, ToolSearch, EnterWorktree, ExitWorktree, Monitor, TaskStop, SendMessage, Artifact만 유지합니다. 다른 모든 내장 도구는 상속·나열 여부와 무관하게 제거됩니다. ListAgents는 어떤 내장 도구처럼 이 필터를 따릅니다: 포그라운드 서브에이전트는 크로스세션 메시징 활성 세션에서 상속, 백그라운드 서브에이전트는 유지하지 않아요. agent teams의 팀메이트는 추가로 작업·크론 도구(TaskCreate, TaskGet, TaskList, TaskUpdate, CronCreate, CronDelete, CronList)를 유지합니다.

도구를 제한하려면 tools 필드를 허용 목록으로, disallowedTools 필드를 거부 목록으로 쓰세요. 이 예는 tools로 Read, Grep, Glob, Bash만 허용합니다. 서브에이전트는 파일 편집·쓰기·MCP 도구를 쓸 수 없어요:

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

이 예는 disallowedTools로 Write와 Edit를 제외한 도구 풀을 상속합니다:

---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---

둘 다 설정하면 disallowedTools를 먼저 적용하고, 그 다음 남은 풀에 대해 tools를 해석합니다. 둘 다 나열된 도구는 제거돼요. tools 목록의 어떤 것도 도구로 해석되지 않으면(오타·이용 불가 도구) Claude Code는 보통 서브에이전트 출시를 거부하고 Agent 도구가 해석되지 않은 항목을 명명하는 오류를 반환합니다.

두 필드 모두 정확한 도구 이름 외에 MCP 서버 레벨 패턴을 받아요: mcp__<server> 또는 mcp__<server>__*는 해당 서버의 모든 도구를 부여·제거합니다. disallowedTools에서 mcp__*는 어떤 서버의 모든 MCP 도구도 제거합니다. 지정자(Bash(git push *) 같은)가 있는 disallowedTools 항목은 일치하는 명령만이 아니라 전체 도구를 제거해요. Bash를 유지하고 특정 명령만 차단하려면 settings의 permissions.deny에 Bash(git push *) 같은 Bash 거부 규칙을 추가하세요. 이 규칙은 메인 대화와 서브에이전트에 모두 적용됩니다.

스폰 가능한 서브에이전트 제한

에이전트가 claude --agent로 메인 스레드로 실행될 때 Agent 도구로 서브에이전트를 스폰할 수 있어요. 스폰 가능한 유형을 제한하려면 tools 필드에 Agent(agent_type) 구문을 쓰세요.

---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---

이것은 허용 목록입니다: worker와 researcher만 스폰 가능합니다. 다른 유형을 스폰하려 하면 요청이 실패하고 에이전트는 프롬프트에서 허용된 유형만 봅니다. 특정 에이전트만 차단하려면 permissions.deny를 쓰세요. 모든 에이전트를 제한 없이 스폰하려면 괄호 없이 Agent를 쓰세요 (tools: Agent, Read, Bash). tools 목록에서 Agent를 아예 빼면 어떤 서브에이전트도 스폰할 수 없습니다. Agent(agent_type) 구문은 claude --agent로 메인 스레드로 도는 에이전트에만 적용돼요.

서브에이전트로 MCP 서버 범위 지정

mcpServers 필드로 메인 대화에서 사용 가능하지 않은 MCP 서버에 서브에이전트가 접근하게 할 수 있어요. 여기 정의한 인라인 서버는 서브에이전트 시작 시 연결되고 끝나면 연결 해제됩니다. 문자열 참조는 부모 세션의 연결을 공유합니다. 각 항목은 인라인 정의이거나 세션에 이미 구성된 MCP 서버를 참조하는 문자열입니다:

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  # Inline definition: scoped to this subagent only
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  # Reference by name: reuses an already-configured server
  - github
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

인라인 정의는 .mcp.json 서버 항목과 같은 스키마를 쓰고 stdio, http, sse, ws 유형을 지원합니다. MCP 서버를 메인 대화에서 완전히 빼내고 도구 설명이 거기 컨텍스트를 잡아먹지 않게 하려면 .mcp.json이 아니라 여기에 인라인으로 정의하세요. 서브에이전트는 도구를 얻고 부모 대화는 얻지 않아요.

Claude Code는 프로젝트 .claude/agents/ 디렉터리나 --add-dir 디렉터리의 에이전트 파일에서 인라인 서버를, 해당 파일이 온 폴더를 신뢰한 후에만 로드합니다 (v2.1.238 이전에는 신뢰 검사 없이 로드). 부모 폴더의 신뢰와 -p/SDK 세션이 settings 파일 훅에 얻는 자동 신뢰는 신뢰로 인정되지 않아요. 그 전까지 Claude Code는 해당 에이전트 파일의 모든 인라인 서버를 건너뛰고 ~/.claude.json용 projects["<path>"].hasTrustDialogAccepted 키를 디버그 로그에 기록합니다. --add-dir 디렉터리는 신뢰된 워크스페이스 저장소 밖이면 자체 신뢰 항목이 필요해요.

이미 구성한 서버를 참조하는 이름, ~/.claude/agents/·--agents·SDK agents 옵션·managed settings로 공급되는 에이전트 파일의 인라인 서버는 신뢰 검사 없이 로드됩니다.

v2.1.153부터 메인 세션에 적용되는 MCP 제한이 서브에이전트 frontmatter에 선언된 서버에도 적용됩니다: --strict-mcp-config, --bare, Enterprise managed MCP 구성, allowedMcpServers/deniedMcpServers 정책. 이 중 하나가 서버를 차단하면 Claude Code가 서버를 건너뛰고 차단된 서버를 명명하는 경고를 표시합니다. --strict-mcp-config는 --agents/SDK agents 옵션으로 인라인 전달한 서버는 필터링하지 않아요(명시적 호출자 입력이므로).

권한 모드

permissionMode로 서브에이전트가 실행될 권한 모드를 선택하세요. 모드의 구성 값을 쓰므로 Manual 모드는 default입니다. 설정하지 않으면 서브에이전트가 메인 대화의 모드를 상속합니다(Pro·Max·Team 플랜에서 기본은 auto mode).

메인 대화의 권한 모드가 당신이 설정한 값을 쓸지 결정합니다:

메인 대화가 bypassPermissions, acceptEdits, auto mode일 때: 서브에이전트는 같은 모드로 돌고 permissionMode는 무시됩니다. auto mode에서 분류기가 메인 대화의 block·allow 규칙으로 서브에이전트 도구 호출을 평가합니다.
메인 대화가 default, dontAsk, plan일 때: 서브에이전트는 설정한 권한 모드로 돌지만 bypassPermissions는 제외입니다. (v2.1.267부터) bypassPermissions를 선언한 서브에이전트는 대신 메인 대화의 모드를 유지합니다.

모드	동작
`default`	Manual 모드: 권한 요청
`acceptEdits`	작업 디렉터리/`additionalDirectories` 경로의 파일 편집·일반 파일시스템 명령 자동 수락
`auto`	Auto mode: 백그라운드 분류기가 명령·보호 디렉터리 쓰기 검토
`dontAsk`	권한 프롬프트 자동 거부. 명시적으로 허용된 도구는 여전히 동작
`bypassPermissions`	권한 프롬프트 건너뛰기. 메인 대화가 그 모드일 때만 실행
`plan`	Plan 모드(읽기 전용 탐색)

스킬을 서브에이전트에 프리로드

skills 필드로 스킬 내용을 시작 시 서브에이전트 컨텍스트에 주입합니다. 실행 중 스킬을 발견·로드할 필요 없이 도메인 지식을 줍니다.

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

나열된 각 스킬의 전체 내용이 시작 시 서브에이전트 컨텍스트에 주입됩니다. disable-model-invocation: true를 설정한 스킬([/verify 스킬 포함)은 프리로드할 수 없어요. 나열된 스킬이 없거나 정책으로 비활성화되면 Claude Code가 건너뛰고 디버그 로그에 경고를 기록합니다.

영구 메모리 활성화

memory 필드는 세션 간에 유지되는 영구 디렉터리를 서브에이전트에 줍니다. 서브에이전트는 시간이 지나며 코드베이스 패턴·디버깅 인사이트·아키텍처 결정 같은 지식을 쌓는 데 이 디렉터리를 씁니다.

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.

메모리가 얼마나 넓게 적용돼야 하는지에 따라 범위를 고르세요:

범위	위치	쓰는 때
`user`	`~/.claude/agent-memory/<name-of-agent>/`	모든 프로젝트에 걸쳐 학습 기억
`project`	`.claude/agent-memory/<name-of-agent>/`	지식이 프로젝트 특정이고 버전 관리로 공유 가능
`local`	`.claude/agent-memory-local/<name-of-agent>/`	지식이 프로젝트 특정이되 버전 관리에 커밋하면 안 됨

서브에이전트 메모리는 auto memory의 일부입니다: autoMemoryEnabled 설정이나 CLAUDE_CODE_DISABLE_AUTO_MEMORY로 auto memory를 끄면 memory 필드는 효과가 없고 서브에이전트는 메모리 지시 없이 실행됩니다.

메모리가 활성화되면: 서브에이전트 시스템 프롬프트에 메모리 디렉터리 읽기·쓰기 지시가 포함되고, 메모리 디렉터리 MEMORY.md의 처음 200줄 또는 25KB(먼저 오는 쪽)도 포함되며, Read·Write·Edit 도구가 자동 활성화됩니다.

영구 메모리 팁: project가 권장 기본 범위(버전 관리로 공유 가능). 작업 시작 전 서브에이전트가 메모리를 확인하게 하세요("Review this PR, and check your memory for patterns you've seen before."). 작업 완료 후 메모리를 갱신하게 하세요. 서브에이전트 마크다운 파일에 메모리 지시를 직접 포함해 지식 베이스를 능동적으로 유지하게 하세요.

훅으로 조건부 규칙

PreToolUse 훅으로 실행 전 작업을 검증할 수 있어요. 이 예는 읽기 전용 DB 쿼리만 허용하는 서브에이전트를 만듭니다:

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

Claude Code는 훅 입력을 JSON으로 stdin으로 훅 명령에 전달합니다. 검증 스크립트는 이 JSON을 읽고 Bash 명령을 추출해 코드 2로 종료해 쓰기 작업을 차단합니다:

#!/bin/bash
# ./scripts/validate-readonly-query.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Block SQL write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi

exit 0

macOS·Linux에서는 스크립트를 실행 가능하게 하세요: chmod +x ./scripts/validate-readonly-query.sh. Windows에서는 PowerShell로 쓰고 훅 항목에 shell: powershell을 추가하세요.

특정 서브에이전트 비활성화

settings의 deny 배열에 Agent(subagent-name) 형식으로 추가하면 특정 서브에이전트 사용을 막을 수 있어요:

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

내장·커스텀 모두 동작합니다. CLI 플래그로는 claude --disallowedTools "Agent(Explore)".

서브에이전트용 훅 정의

서브에이전트는 라이프사이클 중 도는 훅을 정의할 수 있어요. 서브에이전트 frontmatter에 정의하면 그 서브에이전트가 활성인 동안만, settings.json에 정의하면 서브에이전트 안에서도 발화하는 세션 전체 훅입니다. settings·managed policy·플러그인의 훅은 모두 서브에이전트 안에 적용됩니다.

frontmatter 훅은 에이전트가 Agent 도구·@-언급으로 서브에이전트로 스폰될 때, 그리고 --agent/agent 설정으로 메인 세션으로 실행될 때 발화합니다. 프로젝트 레벨 서브에이전트의 frontmatter 훅이 도려면 에이전트 파일을 담은 폴더의 워크스페이스 신뢰 대화상자를 수락하세요. ~/.claude/agents/의 사용자 레벨 서브에이전트와 --agents로 전달한 정의 훅은 이 단계 없이 실행됩니다. 폴더를 신뢰할 때까지 서브에이전트는 여전히 돌지만 Claude Code는 frontmatter 훅을 건너뛰고 신뢰 방법을 설명하는 오류를 디버그 로그에 기록합니다. 부모 폴더 신뢰만으로는 부족하고 -p 세션도 신뢰로 치지 않는, settings 파일 훅보다 엄격한 규칙이에요 (v2.1.218 이전에는 신뢰하지 않은 폴더에서도 실행 가능).

이벤트	matcher 입력	발화 시점
`PreToolUse`	도구 이름	서브에이전트가 도구를 쓰기 전
`PostToolUse`	도구 이름	서브에이전트가 도구를 쓴 후
`Stop`	(없음)	서브에이전트 완료 시 (런타임에 `SubagentStop`으로 변환)

서브에이전트로 호출될 때 frontmatter의 Stop 훅은 자동으로 SubagentStop 이벤트로 변환됩니다. 프로젝트 레벨 서브에이전트 이벤트용 훅은 settings.json에서 SubagentStart(에이전트 유형 이름 matcher, 시작 시)와 SubagentStop(완료 시)로 구성합니다. 하이픈 matcher(db-agent 같은)는 v2.1.195 이상에서 정확히 일치합니다.

서브에이전트로 작업하기

자동 위임 이해

Claude는 요청의 작업 설명, description 필드, 현재 컨텍스트를 바탕으로 자동으로 작업을 위임합니다. "use proactively" 같은 문구를 description에 넣어 적극적 위임을 유도하세요. 설명은 간결히:

Claude Code는 서브에이전트 설명 합계가 15,000 토큰 한도를 넘을 때 시작 경고를 보여주고 여전히 모든 서브에이전트를 로드합니다.

서브에이전트 명시적으로 호출

일회성 제안에서 세션 전체 기본값까지 세 가지 패턴이 있습니다:

자연어: 프롬프트에서 서브에이전트를 명명하면 Claude가 위임 여부를 결정
@-언급: 한 작업에 그 서브에이전트가 실행됨을 보장
세션 전체: --agent 플래그나 agent 설정으로 전체 세션이 그 서브에이전트의 시스템 프롬프트·도구 제한·모델 사용

자연어는 특별한 구문이 없어요. Use the test-runner subagent to fix failing tests처럼 명명하면 Claude가 보통 위임합니다.

@-언급: @를 치고 타입어헤드에서 서브에이전트를 고르면, 파일을 @-언급하는 것처럼 특정 서브에이전트가 실행됩니다. @"code-reviewer (agent)" look at the auth changes처럼. 전체 메시지는 여전히 Claude로 가고, Claude가 질문 내용으로 서브에이전트 작업 프롬프트를 씁니다. @-언급은 Claude가 어떤 서브에이전트를 호출할지 제어하지 프롬프트는 제어하지 않아요. 플러그인이 제공하는 서브에이전트는 scoped 이름(my-plugin:code-reviewer 같은)으로 타입어헤드에 나타납니다. 수동 입력은 로컬이면 @agent-<name>, 플러그인이면 @agent- 다음에 scoped 이름(@agent-my-plugin:code-reviewer)입니다.

전체 세션을 서브에이전트로 실행: --agent <name>로 메인 스레드 자체가 그 서브에이전트의 시스템 프롬프트·도구 제한·모델을 취하는 세션을 시작하세요:

claude --agent code-reviewer

서브에이전트 시스템 프롬프트가 기본 Claude Code 시스템 프롬프트를 완전히 대체합니다. 에이전트 이름은 시작 헤더에 @<name>으로 나타납니다. 세션 재개 시 선택이 유지됩니다. 프로젝트의 모든 세션 기본으로 만들려면 .claude/settings.json에 "agent": "code-reviewer"를 설정하세요. 둘 다 있으면 CLI 플래그가 설정을 덮어씁니다.

포그라운드·백그라운드에서 서브에이전트 실행

포그라운드 서브에이전트는 완료까지 메인 대화를 차단. 권한 프롬프트가 그대로 전달됨
백그라운드 서브에이전트는 당신이 계속 작업하는 동안 동시에 실행. 권한이 필요한 도구 호출에 이르면 Claude Code가 메인 세션에 프롬프트를 표시하고 요청하는 서브에이전트를 명명. 승인하거나 Esc로 그 도구 호출 하나만 거부

Claude Code는 Agent 도구로 Claude가 스폰하는 각 서브에이전트의 포그라운드/백그라운드를 다음 순서로 정합니다:

in-process agent team 팀메이트가 스폰했다면 포그라운드로 실행
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS를 1로 설정했다면 어떤 세션이든 포그라운드로 실행
fork 모드가 켜져 있으면(인터랙티브 세션 기본) 백그라운드로 실행
fork 모드가 꺼져 있으면 기본 백그라운드, 계속하기 전에 결과가 필요할 때 포그라운드

백그라운드 서브에이전트는 포그라운드보다 작은 내장 도구 세트로 돌아요. 모든 권한 프롬프트를 메인 세션에 표시하고, 한 도구 호출을 넘어 지속되는 선택(세션 나머지 grant 같은)은 전체 세션에 적용됩니다. 백그라운드 서브에이전트는 백그라운드 Bash·PowerShell 명령을 턴 끝을 넘어 계속 실행할 수 있어요.

백그라운드 서브에이전트 결과는 나중 턴에 완료 알림으로 Claude에게 도착합니다. Claude는 그 알림을 기다린 뒤 결과를 보고합니다. 직접 조종도 가능합니다: fork 모드가 꺼진 곳에서는 백그라운드/포그라운드 실행을 요청하고, Ctrl+B로 실행 중 작업을 백그라운드로 보낼 수 있어요.

성공적으로 끝난 백그라운드 서브에이전트는 즉시 행이 제거되고, 실패·정지한 것은 30초 유지됩니다 (/tasks에서 실행 트랜스크립트 열기). 백그라운드 서브에이전트가 완료하면 /tasks에 done으로 표시되어 30초간 나열됩니다.

서브에이전트 이름

Claude는 Agent 도구 호출에서 name 파라미터를 넘겨 서브에이전트에 이름을 줄 수 있어요. 이름 덕분에 서브에이전트는 주소 지정 가능해져, 완료 후 이름으로 메시지·재개할 수 있습니다. 인터랙티브 세션에서 agent teams이 활성화된 경우, 메인 대화에서 name을 가진 서브에이전트는 fork가 아니고 호출에 isolation을 넘기지 않았다면 팀메이트로 실행됩니다.

서브에이전트의 API 오류

v2.1.199부터 API 오류(사용 한도·반복 서버 오류)로 끝난 서브에이전트는 오류 텍스트를 조사 결과처럼 반환하는 대신 실패를 Claude에게 보고합니다. 포그라운드: rate limit·과부하·서버 오류가 이미 텍스트 출력을 낸 서브에이전트를 끊으면 Agent 도구는 그 부분 출력을 "잘렸고 작업을 끝내지 못했다"는 메모와 함께 반환합니다. 아무것도 낸 게 없거나 도구 호출만 있으면 Agent terminated early due to an API error로 실패합니다. 백그라운드: 실패로 표시되고, 끝날 때 Claude가 받는 메시지가 API 오류를 명명하며 마지막 출력을 포함해 부분 작업이 유실되지 않게 합니다.

fallback model chain을 구성했고 서브에이전트가 체인이 커버하는 실패(모델 이용 불가 등)를 만나면, Claude Code는 요청을 수락하는 체인 첫 모델로 서브에이전트를 전환합니다.

서브에이전트 출력 스캔

Claude Code는 Claude가 읽기 전에 각 서브에이전트의 최종 보고를 스캔합니다. 서브에이전트는 당신이 검토하지 않은 파일·웹 페이지·명령 출력을 읽었을 수 있고, 그 텍스트가 메인 대화를 겨냥한 지시를 실을 수 있기 때문이에요. 스캔은 아무것도 제거·재작성하지 않으며 두 가지 변경을 만들 수 있습니다:

백슬래시 삽입: Claude Code 자체 출력을 흉내 내는 텍스트(<system-reminder> 태그, Human:·Assistant:로 시작하는 줄)에 백슬래시를 삽입해 대화의 일부로 오인되지 않게 합니다
마커 줄: 보고서가 <system-reminder> 같은 태그를 흉내 내거나 bypassPermissions·--dangerously-skip-permissions 같은 권한 설정을 언급하면 [harness: subagent output matched instruction-shaped pattern(s):로 시작하는 줄을 앞에 붙입니다

스캔은 콘텐츠가 악의적인지 판단하지 않고, 보고서의 지시가 할 수 있는 일도 바꾸지 않습니다. 보고서가 Claude로 하여금 하게 하는 도구 호출은 여전히 세션의 권한 검사와 샌드박싱을 거칩니다. (v2.1.210 이상)

일반 패턴

고용량 작업 격리: 테스트 실행, 문서 가져오기, 로그 파일 처리 같은 많은 출력을 내는 작업을 서브에이전트에 위임하세요. Use a subagent to run the test suite and report only the failing tests with their error messages.

병렬 리서치: 독립 조사에 여러 서브에이전트를 동시에 스폰하세요. Research the authentication, database, and API modules in parallel using separate subagents. 각자 자기 영역을 독립 탐색하고 Claude가 종합합니다. 리서치 경로가 서로 독립적일 때 가장 잘 동작해요.

많은 서브에이전트가 각자 상세 결과를 반환하면 메인 대화 컨텍스트를 상당히 소비할 수 있습니다.

서브에이전트 체이닝: 다단계 워크플로우에서 순차로 서브에이전트를 쓰라고 요청하세요. Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them.

서브에이전트와 메인 대화 선택

메인 대화를 쓰세요: 잦은 왕복·반복 개선이 필요할 때, 여러 단계가 계획·구현·테스트 같은 상당한 컨텍스트를 공유할 때, 빠른 목표 변경일 때, 지연이 중요할 때(fork가 아닌 서브에이전트는 새로 시작해 컨텍스트를 모으는 데 시간이 걸릴 수 있음).

서브에이전트를 쓰세요: 작업이 메인 컨텍스트에 필요 없는 장황한 출력을 낼 때, 특정 도구 제한·권한을 강제하고 싶을 때, 작업이 자기완결적이고 요약을 반환할 수 있을 때.

대화에 이미 있는 것에 대한 질문은 서브에이전트 대신 /btw를 쓰세요. 전체 컨텍스트를 보지만 도구 접근이 없고 답이 히스토리에 추가되지 않아요.

서브에이전트가 자기 서브에이전트를 스폰하게 하기

기본적으로 서브에이전트는 메인 대화 아래 최대 3층까지 자기 서브에이전트를 스폰할 수 있어요. 깊이 한도에서 Claude Code는 fork를 제외한 모든 서브에이전트에서 Agent 도구를 보류합니다. 중첩 서브에이전트는 위임 작업 자체가 병렬 하위 작업으로 갈라질 때(리뷰어 서브에이전트가 항목마다 검증자를 파견하는 경우) 어울려요. 한도를 바꾸려면 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH를 원하는 층 수로 설정하세요:

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
  }
}

1을 설정하면 중첩을 끕니다. 중첩된 서브에이전트도 탑레벨과 같은 범위에서 해석돼요. 한 서브에이전트가 중첩 중에 스폰하지 못하게 하려면 tools 목록에서 Agent를 빼거나 disallowedTools에 추가하세요. Claude Code는 중첩 서브에이전트를 서브에이전트 패널에 트리로 표시합니다.

이전 버전 기본값: v2.1.172~v2.1.216: 기본 5층까지 중첩(변경 불가). v2.1.217~v2.1.218: 기본 1(직접 서브에이전트 스폰 불가), v2.1.219에서 기본 3으로 인상.

동시 서브에이전트 한도

서브에이전트 사용을 제어하는 두 한도가 있습니다: 이 한도는 너무 많이 돌 때 Claude가 더 스폰하지 못하게 하고, 깊이 한도는 얼마나 깊이 중첩되는지를 제한합니다. 세션 동안 Claude가 스폰할 수 있는 총 서브에이전트 수에는 한도가 없어요.

기본적으로 세션에서 20개가 돌 때 Agent 도구로 또 스폰하면 Concurrent subagent limit reached로 실패하고 오류가 재시도하지 말라고 지시합니다. 한도를 바꾸려면 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS를 양의 정수로 설정하세요. ultracode 활성 세션은 면제됩니다 (v2.1.217 이상). 세션 안 fork는 슬롯을 차지하지만 한도에 막히지 않고, 재개는 슬롯을 재확인 없이 차지해 실행 수를 한도 위로 밀 수 있어요. 워크플로우 에이전트·agent team 팀메이트 같은 다른 기능이 실행하는 에이전트는 각자 자체 한도를 따릅니다.

서브에이전트 컨텍스트 관리

시작 시 로드되는 것

각 서브에이전트는 새롭고 격리된 컨텍스트 윈도우로 시작합니다. 대화 히스토리, 호출한 스킬, Claude가 읽은 파일을 보지 못해요. 예외는 fork입니다. non-fork 서브에이전트의 초기 컨텍스트에는 다음이 포함됩니다:

시스템 프롬프트: 에이전트 자체 프롬프트 + Claude Code가 덧붙이는 환경 정보. 커스텀 서브에이전트는 마크다운 본문이나 prompt 필드에 정의
작업 메시지: Claude가 작업을 넘길 때 쓰는 위임 프롬프트
CLAUDE.md 파일: 메인 대화가 로드하는 모든 CLAUDE.md 계층. 내장 Explore·Plan 에이전트는 이것을 건너뜀
Git 상태: 부모 세션 시작 시의 스냅샷. git 저장소가 아니거나 includeGitInstructions가 false이면 없음. Explore·Plan은 무조건 건너뜀
프리로드 스킬: skills 필드에 명명된 스킬의 전체 내용. 내장 에이전트는 스킬을 프리로드하지 않음
형제 명단: main과 세션의 다른 모든 명명된 에이전트를 나열하는 시스템 알림 (v2.1.206 이상). 서브에이전트 도구가 SendMessage를 포함하고 다른 에이전트가 하나라도 이름을 가질 때만 나타남

일부 메인 대화 상태는 non-fork 서브에이전트에 도달하지 않아요: 출력 스타일(서브에이전트는 자기 시스템 프롬프트로 돌음), auto memory(메인 대화의 것이 로드되지 않음; 자기 영구 메모리는 memory 필드로), 컨텍스트 윈도우 크기(자기 모델이 결정).

서브에이전트 재개

각 서브에이전트 호출은 이전 것을 이어가는 대신 새 인스턴스를 만듭니다. 기존 서브에이전트 작업을 이어가려면 Claude에게 재개를 요청하세요. 재개된 서브에이전트는 모든 이전 도구 호출·결과·추론을 포함한 전체 대화 히스토리를 유지합니다.

서브에이전트가 완료되면 Claude가 agent ID를 받습니다
내장 Explore·Plan은 일회성이고 agent ID를 반환하지 않아 재개할 수 없음. general-purpose나 커스텀을 쓰세요
서브에이전트가 maxTurns 한도에서 멈추면 Claude Code는 반환 출력을 partial로 표시

Claude는 SendMessage 도구를 agent ID나 이름을 to 필드로 해 재개합니다. SendMessage는 agent teams 활성화를 요구하지 않아요. 서브에이전트·팀메이트 외에, 크로스세션 메시징 활성 세션에서는 같은 도구로 당신의 다른 Claude Code 세션에도 메시지를 보낼 수 있습니다.

Use the code-reviewer subagent to review the authentication module
[Agent completes]

Continue that code review and now analyze the authorization logic
[Claude resumes the subagent with full context from previous conversation]

Claude가 SendMessage 도구로 완료된 서브에이전트에 메시지를 보내면, 서브에이전트는 새 Agent 호출 없이 백그라운드에서 재개됩니다. 재개된 실행은 원래 도구 세트를 유지합니다. SendMessage를 가진 서브에이전트도 그 메시지를 보낼 수 있어요. 당신이 /tasks의 x나 SDK stop_task로 직접 멈춘 서브에이전트는 자동 재개되지 않습니다.

v2.1.199부터 SendMessage는 이름이 여전히 이전에 대화에서 닿은 같은 에이전트를 가리키는지 확인합니다. v2.1.198부터 서브에이전트는 자기 실행자로부터의 메시지를 정상 작업 지시로 취급합니다. 단, 그 메시지가 보류 중 권한 프롬프트에 대한 승인으로 여겨지거나 서브에이전트 권한 설정·CLAUDE.md·구성을 바꿀 수는 없습니다.

agent ID는 ~/.claude/projects/{project}/{sessionId}/subagents/의 트랜스크립트 파일에서 찾을 수 있어요. 각 트랜스크립트는 agent-{agentId}.jsonl로 저장됩니다.

서브에이전트 트랜스크립트는 메인 대화와 독립적으로 유지됩니다: 메인 대화 압축(영향 없음, 별도 파일), 세션 지속성(세션 내 유지, 같은 세션 재개로 재개 가능), 자동 정리(cleanupPeriodDays 보존 기간 후 삭제, 기본 30일).

자동 압축

서브에이전트는 메인 대화와 같은 로직으로 자동 압축을 지원합니다. CLAUDE_AUTOCOMPACT_PCT_OVERRIDE도 서브에이전트에 적용됩니다. 압축 이벤트는 서브에이전트 트랜스크립트 파일에 기록됩니다:

{
  "type": "system",
  "subtype": "compact_boundary",
  "compactMetadata": {
    "trigger": "auto",
    "preTokens": 167189
  }
}

preTokens 값은 압축 전 사용된 토큰 수를 보여줍니다.

현재 대화 포크하기

포크는 새로 시작하는 대신 지금까지의 전체 대화를 상속하는 서브에이전트예요. 포크는 메인 세션과 같은 시스템 프롬프트·도구·모델·메시지 히스토리를 보므로 상황을 다시 설명하지 않고 사이드 작업을 넘길 수 있고, 포크의 도구 호출은 여전히 대화 밖에 남아 최종 결과만 돌아옵니다. 다른 서브에이전트가 유용하려면 너무 많은 배경이 필요할 때, 같은 출발점에서 여러 접근을 병렬로 시도하고 싶을 때 쓰세요.

Claude는 Agent 도구로 fork 서브에이전트 유형을 요청해 포크를 시작합니다. fork 모드(인터랙티브 세션 기본 on)가 허용하는지에 달렸어요. 포크는 /subtask 다음에 작업으로 직접 시작할 수 있습니다 (v2.1.212 이상; v2.1.161~v2.1.211에서는 /fork):

/subtask draft unit tests for the parser changes so far

포크는 프롬프트 아래 패널에 나타나 백그라운드로 실행되고, 끝나면 결과가 메인 대화에 메시지로 도착합니다.

실행 중 포크 관찰·조종: 포크는 프롬프트 입력 아래 패널에 나타나며 main 행과 각 포크 행이 있습니다. 성공적으로 끝나면 행이 제거되고, 실패·정지한 것은 30초 유지됩니다. 키: ↑/↓(행 이동), Enter(선택 포크 트랜스크립트 열고 후속 메시지 전송), x(실행 중이면 중지, 아니면 행 해제), Esc(프롬프트 입력으로 포커스 복귀). 포크·서브에이전트 트랜스크립트가 열린 상태에서 후속 메시지·스킬은 그 에이전트로 가지만 내장 명령은 메인 대화에서 실행됩니다.

포크가 다른 서브에이전트와 다른 점:

	포크	Non-fork 서브에이전트
컨텍스트	전체 대화 히스토리	넘긴 프롬프트가 있는 새 컨텍스트
시스템 프롬프트·도구	메인 세션과 같음	정의 파일에서, 백그라운드용으로 필터링
모델	메인 세션과 같음	`model` 필드에서
권한	프롬프트가 터미널에 표시	백그라운드 실행 시 메인 세션에 표시
프롬프트 캐시	메인 세션과 공유	별도 캐시

포크의 시스템 프롬프트·도구 정의는 부모와 동일하므로 첫 요청이 부모의 프롬프트 캐시를 재사용합니다. 같은 컨텍스트가 필요한 작업에서는 새 서브에이전트 스폰보다 포크가 더 저렴해요. Claude가 Agent 도구로 포크를 스폰할 때 isolation: "worktree"를 넘겨 파일 편집이 체크아웃 대신 별도 git 워크트리에 쓰이게 할 수 있습니다. 포크는 더 이상 포크를 스폰할 수 없어요.

fork 모드 켜기/끄기: Claude Code는 인터랙티브 세션에서 기본 on, non-interactive mode의 -p와 Agent SDK에서는 기본 off로 fork 모드를 설정합니다. 인터랙티브 기본값은 v2.1.232 이상 필요. 이전 버전은 CLAUDE_CODE_FORK_SUBAGENT를 1로 설정. 1은 non-interactive·Agent SDK에서도 켜고, 0은 모든 세션에서 끕니다. fork 모드를 켜두되 Claude가 포크를 스폰하지 못하게 하려면 Agent(fork) 규칙으로 fork 유형을 거부하세요.

예시 서브에이전트

모범 사례: 각 서브에이전트를 한 가지에 특화시키기, 설명을 하나의 서브에이전트에만 맞게 작성(Claude가 위임 시기 결정, 15,000 토큰 설명 예산 유지), 도구 접근 제한, 프로젝트 서브에이전트를 버전 관리에 커밋.

코드 리뷰어 — 수정 없이 코드를 리뷰하는 읽기 전용 서브에이전트. Edit·Write를 제외하도록 도구 접근을 제한하고 상세 프롬프트를 지정하는 예.

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

디버거 — 분석과 수정을 모두 하는 서브에이전트. 버그 수정은 코드 수정이 필요하므로 Edit를 포함합니다.

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not the symptoms.

데이터 사이언티스트 — 데이터 분석 작업용 도메인 특화 서브에이전트. model: sonnet을 명시해 더 강력한 분석을 씁니다.

---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.

DB 쿼리 검증기 — Bash는 허용하되 읽기 전용 SQL만 허용하도록 명령을 검증하는 서브에이전트. tools 필드보다 세밀한 제어가 필요할 때 PreToolUse 훅을 쓰는 예입니다.

---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.

When asked to analyze data:
1. Identify which tables contain the relevant data
2. Write efficient SELECT queries with appropriate filters
3. Present results clearly with context

You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

검증 스크립트:

#!/bin/bash
# Blocks SQL write operations, allows SELECT queries

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if [ -z "$COMMAND" ]; then
  exit 0
fi

# Block write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then
  echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2
  exit 2
fi

exit 0

macOS·Linux에서는 chmod +x ./scripts/validate-readonly-query.sh로 실행 가능하게, Windows에서는 PowerShell로 쓰고 shell: powershell을 추가하세요. exit code 2가 작업을 차단하고 오류 메시지를 Claude로 되돌립니다. 시스템 프롬프트가 쓰기 요청을 거부하라고 하므로 훅은 백스톱입니다: 서브에이전트가 그래도 쓰기를 시도하면 Claude Code가 명령을 차단합니다.

더 알아보기

플러그인으로 서브에이전트 배포 — 팀·프로젝트 간 서브에이전트 공유
Agent SDK로 프로그래밍 방식 실행 — CI/CD·자동화
MCP 서버 사용 — 서브에이전트에 외부 도구·데이터 접근 부여
관련 가이드: 배경 에이전트, 크로스세션 메시징, 에이전트 팀

커스텀 서브에이전트 만들기