Claude Code 서브에이전트

한 줄 요약: Claude Code 공식 문서 "Create custom subagents". 서브에이전트를 "곁가지 작업을 자기 컨텍스트에서 하고 요약만 돌려주는 전문 어시스턴트"로 정의하고, 내장 서브에이전트(Explore·Plan·general-purpose 등), 첫 서브에이전트 만들기, 정의 파일 위치 5곳과 우선순위, frontmatter 전체 필드, 모델·effort 결정 순서, 도구·MCP·권한 모드·스킬·메모리·훅으로 능력 제한하기, 자동 위임과 명시 호출(@-mention, --agent), 포그라운드·백그라운드, 중첩 깊이와 동시 실행 한도, 시작 때 로드되는 것, 재개, 출력 검사, 포크(/subtask), 예시 정의 4개를 다룬다.

원본 정보#

• 제목: Create custom subagents
• 발행: Anthropic, Claude Code 공식 문서 (원본 날짜 미상)
• URL: https://code.claude.com/docs/en/sub-agents (새 창)
• 수집(fetch)일: 2026-10-18. 본문의 버전 조건(v2.1.63 ~ v2.1.296), 환경 변수, 설정 키, 명령은 이 날짜 기준이다.

핵심 주장#

1. 서브에이전트는 메인 대화를 다시 보지 않을 출력으로 채우지 않으려고 쓴다. 원본 첫 문단: 곁가지 작업이 검색 결과·로그·파일 내용으로 메인 대화를 채울 때 서브에이전트가 자기 컨텍스트에서 그 일을 하고 요약만 돌려준다. 같은 지시로 같은 종류의 작업자를 계속 띄우게 되면 커스텀 서브에이전트를 정의한다. 서브에이전트는 자기 요청을 보내고, 그 요청은 메인 대화와 같은 사용량 한도에 잡힌다. → 서브에이전트
2. 정의 파일은 YAML frontmatter + 마크다운 본문(시스템 프롬프트)이고, 필수는 name·description 둘뿐이다. 위치는 managed settings > --agents CLI 플래그 > .claude/agents/ > ~/.claude/agents/ > 플러그인 agents/ 순으로 이름이 겹칠 때 이긴다. 철자가 틀린 필드는 오류 없이 무시되고, name이 없거나 YAML이 깨진 파일은 세션에 알리지 않고 건너뛴다. → 서브에이전트 정의 파일 레퍼런스, Claude Code 서브에이전트 문제 해결
3. 기본 중첩 한도는 메인 대화 아래 3층이고 바꿀 수 있다. 서브에이전트는 기본으로 자기 서브에이전트를 메인 아래 세 층까지 띄운다. 한도에 닿은 서브에이전트에게서는 Agent 도구를 뺀다(포크는 도구가 남지만 호출하면 오류). CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH로 바꾸고 1이면 중첩이 꺼진다. 이전 버전 기본값: v2.1.172~v2.1.216은 최대 5층(변경 불가), v2.1.217~v2.1.218은 1, v2.1.219부터 3. 동시 실행 한도는 별도로 기본 20개다(CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS). → 서브에이전트의 ‘원본끼리 달랐던 점’ 상자 근거
4. 도구·권한 제한에는 조건이 붙는다. tools(허용 목록)와 disallowedTools(거부 목록)로 도구를 좁히지만, disallowedTools의 Bash(git push *) 같은 지정자는 명령 일부가 아니라 도구 전체를 뺀다(특정 명령만 막으려면 permissions.deny). permissionMode는 메인 대화가 bypassPermissions·acceptEdits·auto 모드면 무시되고, 서브에이전트가 bypassPermissions로 도는 것은 메인도 그 모드일 때뿐이다(v2.1.267 이상). 플러그인 서브에이전트는 보안상 hooks·mcpServers·permissionMode를 무시한다. 프로젝트 서브에이전트의 frontmatter 훅과 인라인 MCP 서버는 그 폴더를 신뢰한 뒤에만 돈다. → 서브에이전트 정의 파일 레퍼런스, 권한 모드
5. 포크는 지금까지 대화를 물려받는 서브에이전트다. 입력 격리를 포기하는 대신 다시 설명할 필요가 없고, 부모의 프롬프트 캐시를 재사용해 같은 맥락이 필요한 작업에서 새 서브에이전트보다 싸다. /subtask <작업>으로 직접 띄우고(v2.1.212 이상, v2.1.161~v2.1.211은 /fork), 대화형 세션은 기본으로 포크 모드가 켜져 있어 Claude가 띄우는 서브에이전트가 모두 백그라운드에서 돈다(인프로세스 에이전트 팀 팀원이 띄운 서브에이전트와 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1일 때는 포그라운드). → Claude Code 서브에이전트 만들기·운영

내장 서브에이전트 (원본 기준)#

• 내장 에이전트는 모두 부모 대화의 권한 규칙을 물려받고, 대부분 좁은 도구 세트로 돈다.
• Explore와 Plan은 CLAUDE.md와 git status 스냅샷 없이 시작한다(빠르고 싸게 조사하려고). 나머지 내장·커스텀 서브에이전트는 둘 다 로드한다.
• 사용자·프로젝트 레벨에 Explore라는 이름의 서브에이전트를 두면 내장을 덮어쓰고 자기 model을 쓴다. 원본 예: model: haiku로 탐색을 저비용 모델에서 돌린다.
• 끄는 방법: 특정 종류는 permissions.deny에 Agent(이름), 위임 전체는 Agent 도구 거부, Explore·Plan만은 CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1(v2.1.198 이상), 비대화형 모드·Agent SDK에서 내장 전부는 CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1.
• subagent_type을 빼고 Agent 도구를 부르면, 세션에 기댈 general-purpose가 없을 때 subagent_type is required 오류가 난다.

원본의 주요 사실 (2026-10-18 기준)#

• 설명(description) 예산: 내장을 뺀 서브에이전트 설명의 합이 15,000토큰을 넘으면 시작 때 총 토큰 수와 함께 경고가 뜬다(모든 서브에이전트는 그래도 로드된다). 설명은 줄이고 세부는 실행할 때만 로드되는 시스템 프롬프트로 옮기라고 한다.
• /agents: 지금은 Claude에게 부탁하거나 .claude/agents/·~/.claude/agents/를 직접 고치라는 안내만 출력한다. v2.1.197 이하에서는 Running·Library 탭이 있는 대화형 마법사였다.
• 파일 감시: ~/.claude/agents/와 .claude/agents/의 추가·수정은 몇 초 안에 감지돼 다음 위임부터 반영된다. 재시작이 필요한 세 경우: 세션 시작 때 없던 agents 디렉터리에 첫 파일을 만들 때, --add-dir 디렉터리의 .claude/agents/, --disable-slash-commands 세션.
• 시스템 프롬프트: 본문이 시스템 프롬프트가 되고, 서브에이전트는 이것과 작업 디렉터리 같은 기본 환경 정보만 받는다(Claude Code 시스템 프롬프트는 받지 않음). 비대화형 모드에서 --append-subagent-system-prompt(v2.1.205 이상)·--append-subagent-system-prompt-file(v2.1.261 이상)로 모든 서브에이전트(중첩 포함, 포크 제외) 프롬프트 끝에 덧붙인다.
• 작업 디렉터리: 메인 대화의 현재 디렉터리에서 시작하고, 서브에이전트 안의 cd는 도구 호출 사이에 유지되지 않으며 메인에 영향을 주지 않는다. isolation: worktree면 임시 git worktree에서 돌고(기본으로 기본 브랜치에서 분기), 변경이 없으면 자동 정리된다. 단 에이전트 팀이 켜진 대화형 세션에서 메인이 name을 붙여 띄운 서브에이전트는 팀원으로 떠서 frontmatter isolation과 상관없이 메인 세션의 작업 디렉터리에서 돈다(포크나 호출 자체에 isolation을 넘긴 경우 제외). worktree 서브에이전트의 Bash·PowerShell 명령이 메인 체크아웃으로 가면 실패한다. Bash는 git을 메인 체크아웃으로 돌리는 명령을 막고, 명령 텍스트로 git이 worktree 안에 머무는지 확인할 수 없으면 거부한다. PowerShell은 작업 디렉터리 검사만 받는다.
• 모델 결정 순서: 호출별 model 인자 > frontmatter model(inherit는 메인 모델) > CLAUDE_CODE_SUBAGENT_MODEL > 메인 모델. v2.1.251 이전에는 환경 변수가 맨 앞이었다. CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1(v2.1.257 이상)을 함께 두면 모든 서브에이전트·팀원·워크플로 에이전트에 한 모델을 강제한다(포크와 model: inherit 스킬 서브에이전트는 메인 모델 유지). 조직의 availableModels 허용 목록에 막힌 값은 다른 모델로 대체되고 대화형 세션에서는 경고가 뜬다. /tasks로 실제 모델을 확인한다(v2.1.242 이상).
• extended thinking: v2.1.198부터 서브에이전트는 메인 대화의 thinking 설정을 물려받는다. 서브에이전트별 설정은 없다.
• 도구 필터 두 단계: (1) 모든 서브에이전트에서 빠지는 도구(tools에 적어도): 깊이 한도의 Agent, AskUserQuestion, EndConversation, EnterPlanMode, ExitPlanMode(permissionMode: plan 제외), ScheduleWakeup, WaitForMcpServers, Workflow. (2) 백그라운드 서브에이전트(기본값)는 MCP 도구는 모두 유지하되 내장 도구는 정해진 목록(Read, Grep, Glob, LSP, Bash, PowerShell, Edit, Write, NotebookEdit, WebFetch, WebSearch, TodoWrite, Skill, ToolSearch, EnterWorktree, ExitWorktree, Monitor, TaskStop, SendMessage, Artifact, 그리고 그것으로 보고하는 서브에이전트의 SubagentHandback)만 남는다. 같은 정의가 포그라운드와 백그라운드에서 다른 도구로 풀릴 수 있다. 포크는 두 필터를 건너뛴다. v2.1.63에서 Task 도구가 Agent로 이름이 바뀌었고 Task(...)는 별칭으로 동작한다.
• 포그라운드·백그라운드: 포크 모드가 켜진 곳(대화형 기본)에서는 Claude가 띄우는 서브에이전트가 모두 백그라운드다(인프로세스 에이전트 팀 팀원이 띄운 서브에이전트는 포그라운드). 포크 모드가 꺼진 곳(-p, Agent SDK 기본)에서는 기본 백그라운드, 결과가 있어야 계속할 때 포그라운드. CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1이면 항상 포그라운드. 백그라운드 서브에이전트의 권한 확인은 메인 세션에 뜨고, 그 한 번을 넘어 지속되는 승인(세션 끝까지 등)을 주면 메인 대화를 포함한 세션 전체에 적용된다. Ctrl+B로 실행 중 작업을 백그라운드로 보낸다.
• 재개: 호출마다 새 인스턴스다. 이어 하려면 Claude가 SendMessage(에이전트 ID나 이름을 to로)로 재개하며, 재개된 서브에이전트는 이전 도구 호출·결과·추론을 모두 갖는다. Explore·Plan은 일회용이라 재개할 수 없다. 트랜스크립트는 ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl에 따로 저장돼 메인 대화 컴팩션의 영향을 받지 않고, cleanupPeriodDays(기본 30일) 뒤 지워진다.
• 에이전트 메시지의 한계: 서브에이전트는 띄운 에이전트의 메시지를 작업 지시로 따르되, 어떤 에이전트의 메시지도 대기 중인 권한 확인의 승인이 되지 않고 서브에이전트의 권한 설정·CLAUDE.md·구성을 바꿀 수 없다. 승인은 권한 시스템이나 사용자 자신의 메시지만 준다.
• 출력 검사(v2.1.210 이상): Claude가 읽기 전에 서브에이전트 최종 보고서를 검사해 Claude Code 출력을 흉내 낸 텍스트(<system-reminder> 태그, Human:·Assistant:로 시작하는 줄)에 백슬래시를 넣고, 그런 태그나 bypassPermissions·--dangerously-skip-permissions 같은 권한 설정 언급이 있으면 [harness: subagent output matched instruction-shaped pattern(s):로 시작하는 표시 줄을 붙인다. 원본은 이 검사가 악의 여부를 판단하지 않고, 보고서가 이끄는 도구 호출은 여전히 권한 검사·샌드박스를 거치며, 서브에이전트가 닿는 범위를 제한하는 것을 대신하지 않는다고 밝힌다.
• API 오류: 포그라운드는 텍스트를 낸 뒤 끊기면 부분 출력과 메모를, 아무것도 못 냈으면 Agent terminated early due to an API error를 돌려준다. 백그라운드는 실패로 표시되고 마지막 출력을 함께 전한다. fallback 모델 체인을 설정하면 체인이 다루는 실패에서 다음 모델로 바꿔 계속한다.
• 자동 컴팩션: 서브에이전트 자기 창이 차면 컴팩션되고 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE도 적용된다. 트랜스크립트에 compact_boundary와 preTokens가 기록된다. autoCompactWindow(100000~1000000, v2.1.296 이상)로 한 서브에이전트만 일찍 컴팩션한다.

메인 대화 vs 서브에이전트 (원본 기준)#

메인 대화 맥락에서 도는 재사용 프롬프트·워크플로가 필요하면 스킬을, 이미 대화에 있는 것에 대한 질문이면 /btw(전체 맥락을 보지만 도구가 없고 답이 기록에 남지 않음)를 쓰라고 한다.

예시 정의 (원본)#

원본은 code-reviewer(읽기 전용, model: inherit), debugger(Edit 포함), data-scientist(model: sonnet), db-reader(PreToolUse 훅으로 읽기 전용 SQL만 허용) 네 개를 든다. 원문은 Claude Code 서브에이전트 만들기·운영에 그대로 옮겼다. 원본의 모범 사례: 한 가지 일에 집중한 서브에이전트, 하나의 서브에이전트로 라우팅되는 구체적 설명(15,000토큰 예산 안), 필요한 도구만, 프로젝트 서브에이전트는 버전 관리에 넣어 팀과 공유.

원본이 링크한 관련 문서#

Costs(사용량 한도), Context window(→ Claude Code 컨텍스트 창), Background agents(agent view), Cross-session messaging, Agent teams(팀원에 서브에이전트 정의 쓰기), Model config(별칭, extended context, fallback 체인, availableModels), Errors(15,000토큰 경고, zero tools, --agents 설정 오류 등), Env vars, Worktrees(격리 강제 방식), Permissions(작업 공간 신뢰 → Claude Code 권한 설정, 작업 공간 신뢰, --add-dir, Bash 규칙), Plugins components·CLI reference(claude plugin validate), Plugin evals, Prompt caching(cacheTtl, 서브에이전트와 캐시), Managed MCP, Tools reference, Headless, Agent SDK, Workflows, Mods(agent.spawn)