Ch4. 서브에이전트 활용

독립 컨텍스트를 가진 서브에이전트를 frontmatter로 정의하고, 내장 에이전트(Explore·Plan)·도구 제한·모델 선택·worktree 격리·--agent 실행을 운영하는 방법

핵심 요약

서브에이전트는 한 세션 안에서 고유 컨텍스트 윈도우·시스템 프롬프트·도구 제한을 갖고 작업 후 요약 결과만 메인 대화로 반환합니다.
내장 에이전트는 Explore(Haiku·읽기 전용)·Plan(읽기 전용)·general-purpose(전체 도구)이며 Explore·Plan은 CLAUDE.md와 git status를 건너뜁니다.
정의는 .claude/agents/의 Markdown 파일이며 필수 필드는 name·description뿐, tools·model·isolation·memory 등은 선택입니다.
v2.1.63에서 Task 도구가 Agent로 이름이 바뀌었고, 최신 릴리스에서는 에이전트 중첩이 최대 3단계로 제한됩니다.
claude --agent <name>은 세션 전체를 그 에이전트의 시스템 프롬프트·도구·모델로 실행하며, 셸의 claude agents(Agent View)와는 다릅니다.

서브에이전트는 메인 세션 안에서 독립된 컨텍스트로 작업하는 하위 에이전트입니다. 탐색/리서치 같은 작업을 분리해 메인 컨텍스트를 덜 소모할 수 있습니다.

각 서브에이전트는 고유한 컨텍스트 윈도우와 커스텀 시스템 프롬프트, 제한된 도구 접근, 독립적인 권한을 갖습니다. Claude는 작업이 서브에이전트의 description과 맞으면 해당 서브에이전트에 위임하고, 서브에이전트는 혼자 작업한 뒤 요약 결과만 메인 대화로 돌려줍니다.

서브에이전트 vs 백그라운드 에이전트 vs 에이전트 팀

서브에이전트는 하나의 세션 안에서 동작합니다. 여러 독립 세션을 병렬로 돌리며 한 화면에서 관리하려면 백그라운드 에이전트(Agent View)를, 세션끼리 서로 메시지를 주고받게 하려면 에이전트 팀을 사용합니다.

서브에이전트의 장점

컨텍스트 격리: 하위 작업이 메인 컨텍스트를 덜 소모
작업 분리: 리서치/탐색을 분리해 집중도 향상
제약 강제: 서브에이전트가 사용할 수 있는 도구를 제한
설정 재사용: 유저 레벨 서브에이전트를 모든 프로젝트에서 활용
비용 제어: Haiku 같은 빠르고 저렴한 모델로 작업을 라우팅

내장 서브에이전트

Claude Code에는 적절한 상황에서 자동으로 쓰이는 내장 서브에이전트가 들어 있습니다.

에이전트	모델	도구	용도
Explore	Haiku	읽기 전용 (Write/Edit 차단)	파일 탐색, 코드 검색, 코드베이스 분석
Plan	메인 대화 상속	읽기 전용 (Write/Edit 차단)	plan 모드에서 계획 수립을 위한 리서치
general-purpose	메인 대화 상속	전체 도구	탐색+수정이 모두 필요한 복합·다단계 작업

Explore와 Plan은 빠른 리서치를 위해 CLAUDE.md 파일과 부모 세션의 git status를 건너뜁니다. 그 외 모든 내장/커스텀 서브에이전트는 둘 다 로드합니다. statusline-setup(Sonnet), claude-code-guide(Haiku) 같은 보조 에이전트도 특정 상황에서 자동 호출됩니다.

최신 v2.1.181~v2.1.190 기준 에이전트 중첩은 최대 3단계까지 허용됩니다. 과거 핸드북의 "서브에이전트는 다른 서브에이전트를 만들 수 없다"는 설명은 더 이상 운영 기준으로 쓰지 마세요. 중첩 에이전트는 권한·도구 허용 범위가 빠르게 복잡해지므로, Agent(agent_type) allowlist와 deny rule을 함께 검토해야 합니다.

커스텀 에이전트 작성

가장 권하는 방법은 세션 안에서 /agents 슬래시 명령을 실행해 가이드 UI로 만드는 것입니다. 직접 작성하거나 자동화하려면 Markdown 파일을 손수 만들어도 됩니다.

/agents

/agents는 탭 인터페이스를 엽니다. Running 탭은 실행 중인 서브에이전트를 보여주고 열거나 중지할 수 있으며, Library 탭에서는 (내장/유저/프로젝트/플러그인) 전체 서브에이전트 조회, 가이드 또는 Claude 생성으로 신규 작성, 기존 설정·도구 접근 편집, 커스텀 서브에이전트 삭제를 할 수 있습니다.

에이전트 파일 위치와 우선순위

서브에이전트는 YAML frontmatter가 붙은 Markdown 파일입니다. 같은 name이 여러 곳에 있으면 우선순위가 높은 위치를 따릅니다.

위치	범위	우선순위	생성 방법
Managed settings 디렉토리의 `.claude/agents/`	조직 전역	1 (최고)	managed settings로 배포
`--agents` CLI 플래그	현재 세션	2	실행 시 JSON 전달 (디스크 미저장)
`.claude/agents/`	현재 프로젝트 (git 공유)	3	인터랙티브 또는 수동
`~/.claude/agents/`	모든 프로젝트	4	인터랙티브 또는 수동
플러그인의 `agents/` 디렉토리	플러그인 활성 범위	5 (최저)	플러그인 설치

.claude/agents/와 ~/.claude/agents/는 재귀적으로 스캔하므로 agents/review/, agents/research/처럼 하위 폴더로 정리할 수 있습니다. 서브에이전트는 오직 frontmatter의 name 필드로만 구분하며, 한 스코프 안에서 같은 name이 둘 이상이면 하나만 남고 나머지는 경고 없이 버려집니다.

에이전트 파일 구조

---
name: code-reviewer
description: 코드 리뷰 전문가. PR 변경사항을 분석하고 개선점을 제안합니다.
tools: Read, Glob, Grep, Bash
model: sonnet
memory: project
---

당신은 시니어 코드 리뷰어입니다.

## 리뷰 기준

- 보안 취약점
- 성능 문제
- 타입 안정성
- 에러 핸들링

frontmatter는 메타데이터와 설정을, 본문(body)은 시스템 프롬프트를 정의합니다. 서브에이전트는 이 시스템 프롬프트와 기본 환경 정보(작업 디렉토리 등)만 받고, Claude Code의 전체 시스템 프롬프트는 받지 않습니다.

디스크 직접 편집 시 재시작 필요

서브에이전트는 세션 시작 시 로드됩니다. 파일을 디스크에서 직접 추가/편집했다면 세션을 재시작해야 반영됩니다. /agents 인터페이스로 만든 서브에이전트는 재시작 없이 즉시 적용됩니다.

지원되는 frontmatter 필드

필수 필드는 name과 description뿐입니다. 나머지는 모두 선택입니다.

필드	설명
`name`	소문자·하이픈으로 된 고유 식별자. Hooks는 이 값을 `agent_type`으로 받음. 파일명과 일치할 필요는 없음
`description`	Claude가 언제 이 서브에이전트에 위임할지 판단하는 기준
`tools`	사용 가능한 도구. 생략 시 메인 대화의 도구를 모두 상속
`disallowedTools`	사용 금지 도구. 상속/지정 목록에서 제거됨
`model`	`fable`/`sonnet`/`opus`/`haiku`, full model ID(예: `claude-fable-5`, `claude-opus-4-8`), 또는 `inherit`. 기본값 `inherit`
`permissionMode`	`default`/`acceptEdits`/`auto`/`dontAsk`/`bypassPermissions`/`plan`. 플러그인 서브에이전트에서는 무시됨
`maxTurns`	서브에이전트가 멈추기 전 최대 에이전틱 턴 수
`skills`	시작 시 컨텍스트에 미리 주입할 Skills (description뿐 아니라 전체 내용 주입)
`mcpServers`	이 서브에이전트가 쓸 MCP 서버. 이름 참조 또는 인라인 정의. 플러그인 서브에이전트에서는 무시됨
`hooks`	이 서브에이전트에만 적용되는 라이프사이클 훅. 플러그인 서브에이전트에서는 무시됨
`memory`	지속 메모리 범위: `user`/`project`/`local`
`background`	`true`면 항상 백그라운드 작업으로 실행. 기본값 `false`
`effort`	이 서브에이전트의 추론 강도(세션 effort 오버라이드): `low`/`medium`/`high`/`xhigh`/`max` (모델 지원 범위 내)
`isolation`	`worktree`면 임시 git worktree에서 격리 실행
`color`	task 목록·트랜스크립트에서의 표시 색상: `red`/`blue`/`green`/`yellow`/`purple`/`orange`/`pink`/`cyan`
`initialPrompt`	이 에이전트가 메인 세션 에이전트(`--agent` 또는 `agent` 설정)로 실행될 때 첫 user 턴으로 자동 제출됨. 커맨드·스킬도 처리되며 사용자 프롬프트 앞에 덧붙음

effort / maxTurns / disallowedTools는 플러그인 전용이 아닙니다

과거 핸드북에서는 effort, maxTurns, disallowedTools를 "플러그인 제공 에이전트 전용"이라고 설명했지만 이는 틀린 내용입니다. 이 세 필드는 모든 서브에이전트가 쓸 수 있는 일반 frontmatter 필드입니다. 반대로 플러그인 서브에이전트는 보안상 hooks, mcpServers, permissionMode를 지원하지 않습니다(로드 시 무시됨). 이 필드가 필요하면 에이전트 파일을 .claude/agents/나 ~/.claude/agents/로 복사하세요.

`isolation: worktree` — git worktree 격리

frontmatter에 isolation: worktree를 지정하면 서브에이전트가 임시 git worktree에서 격리 실행됩니다. 저장소의 독립 복사본을 받으며, 기본적으로 부모 세션의 HEAD가 아니라 기본 브랜치(default branch) 에서 분기합니다. 서브에이전트가 아무것도 바꾸지 않으면 worktree는 자동으로 정리됩니다. (v2.1.49)

`background: true` — 항상 백그라운드 실행

frontmatter에 background: true를 지정하면 해당 에이전트가 항상 백그라운드에서 실행됩니다. (v2.1.49)

`memory` 스코프

memory로 대화 간에 유지되는 메모리 디렉토리를 제어합니다. 켜지면 시스템 프롬프트에 메모리 읽기/쓰기 지침과 MEMORY.md 앞부분(200줄 또는 25KB 중 먼저 도달)이 들어가고, Read/Write/Edit 도구가 자동으로 켜집니다.

값	위치	범위
`user`	`~/.claude/agent-memory/<에이전트명>/`	모든 프로젝트에 걸쳐 기억
`project`	`.claude/agent-memory/<에이전트명>/`	프로젝트 한정, 버전 관리로 공유 가능 (권장 기본값)
`local`	`.claude/agent-memory-local/<에이전트명>/`	프로젝트 한정, 버전 관리 제외

`initialPrompt` — 자동 시작 프롬프트 (v2.1.83)

frontmatter에 initialPrompt를 지정하면 에이전트가 메인 세션 에이전트로 실행될 때(--agent 또는 agent 설정) 첫 user 턴으로 해당 프롬프트가 자동 제출됩니다. 사용자 입력 없이 곧바로 작업을 시작하는 에이전트를 만들 수 있습니다. 슬래시 커맨드와 스킬도 처리되며, 사용자가 따로 프롬프트를 주면 그 앞에 덧붙습니다.

---
name: daily-report
description: 매일 프로젝트 상태를 요약하는 에이전트
tools: Read, Glob, Grep, Bash
initialPrompt: "오늘의 git 커밋과 PR 변경사항을 요약해줘"
---

`@` 멘션 타입어헤드 (v2.1.88)

이름이 붙은(named) 서브에이전트는 @ 멘션 타입어헤드 제안에 뜹니다. 피커 없이 직접 입력할 때는 로컬 서브에이전트는 @agent-<이름>, 플러그인 서브에이전트는 @agent-<플러그인:이름> 형식을 씁니다. 실행 중인 백그라운드 서브에이전트도 상태와 함께 타입어헤드에 나타납니다.

모델 선택과 해석 순서

model 필드로 서브에이전트가 쓸 모델을 정합니다.

alias: fable, sonnet, opus, haiku
full model ID: claude-fable-5, claude-opus-4-8, claude-sonnet-4-6 등 (--model 플래그와 동일한 값). 재현성이 중요하면 alias보다 full model name 권장
inherit: 메인 대화와 동일한 모델
생략: 기본값은 inherit

Claude가 서브에이전트를 호출할 때 그 호출에만 적용되는 model 파라미터를 넘길 수도 있습니다(v2.1.72). 최종 모델은 다음 순서로 해석됩니다.

CLAUDE_CODE_SUBAGENT_MODEL 환경변수 (설정된 경우)
호출별 model 파라미터
서브에이전트 정의의 model frontmatter
메인 대화의 모델

운영 메모

Team agents는 리더(호출자)의 모델을 상속합니다. (v2.1.72)
Bedrock/Vertex/Foundry 환경에서는 서브에이전트의 모델 다운그레이드가 방지됩니다. (v2.1.73)
최신 릴리스에서는 Haiku를 메인 대화 모델로 쓰는 경로가 제한되지만, Explore나 커스텀 서브에이전트의 저비용 모델로는 계속 사용할 수 있습니다.
Agent View header의 모델은 새로 dispatch하는 background session의 기본 모델입니다. 각 background session은 claude --bg --model, attached session의 /model + s, 또는 subagent frontmatter의 model로 별도 모델을 사용할 수 있습니다.

도구 제한과 `Agent(agent_type)`

도구를 제한하려면 tools(허용 목록)나 disallowedTools(차단 목록)를 씁니다. 둘 다 설정하면 disallowedTools를 먼저 적용한 뒤 남은 풀에서 tools를 해석하며, 양쪽에 모두 있는 도구는 제거됩니다.

Agent, AskUserQuestion, EnterPlanMode, ExitPlanMode(단 permissionMode: plan 제외), ScheduleWakeup, WaitForMcpServers는 메인 대화의 UI/세션 상태에 의존하므로 tools에 적어도 서브에이전트에서는 쓸 수 없습니다.

Task → Agent 도구 이름 변경 (v2.1.63)

v2.1.63에서 Task 도구가 Agent로 이름이 바뀌었습니다. 기존 Task(...) 참조는 별칭(alias)으로 계속 동작하지만, 새 코드·문서에서는 Agent(...)를 사용하세요. (이 변경은 tool_name을 검사하는 PreToolUse/PostToolUse 훅 스크립트에 영향을 줄 수 있습니다.)

claude --agent로 에이전트가 메인 스레드로 실행될 때, 생성할 수 있는 서브에이전트 타입을 Agent(agent_type) 문법으로 제한할 수 있습니다. 팀 정책과 보안 측면에서 운영이 쉬워집니다.

---
name: orchestrator
description: 작업을 분배하고 결과를 합치는 오케스트레이터
tools: Agent(code-reviewer, test-runner), Read, Bash
model: sonnet
---

위는 허용 목록입니다. code-reviewer와 test-runner만 만들 수 있고, 다른 타입을 만들려 하면 요청이 실패합니다. 제한 없이 아무 서브에이전트나 만들려면 괄호 없이 Agent만 적습니다. tools에서 Agent를 아예 빼면 어떤 서브에이전트도 만들 수 없습니다.

이 제한은 claude --agent로 메인 스레드로 실행되는 에이전트에 특히 중요합니다. 최신 Claude Code는 중첩 에이전트를 최대 3단계까지 허용하므로, 오케스트레이터 패턴을 쓰는 팀은 Agent(agent_type) allowlist와 disallowedTools deny rule을 각 단계에서 명시하세요.

세션 전체를 서브에이전트로 실행 — `--agent`

자동 위임이나 @ 멘션 말고도, --agent <name>으로 세션 전체가 해당 서브에이전트의 시스템 프롬프트·도구 제한·모델을 쓰도록 할 수 있습니다.

claude --agent code-reviewer

이때 서브에이전트의 시스템 프롬프트가 기본 Claude Code 시스템 프롬프트를 통째로 대체합니다(--system-prompt와 동일). CLAUDE.md와 프로젝트 메모리는 평소처럼 메시지 흐름으로 로드됩니다. 프로젝트 기본값으로 두려면 .claude/settings.json에 "agent": "code-reviewer"를 설정합니다(CLI 플래그가 설정보다 우선).

`claude agents` = Agent View (백그라운드 세션 관리)

`/agents`와 `claude agents`는 다릅니다

세션 안에서 커스텀 서브에이전트를 만들고 관리하는 것은 슬래시 명령 /agents 입니다. 셸에서 실행하는 claude agents 는 백그라운드 Claude Code 세션을 한 화면에서 관리하는 Agent View를 엽니다. 두 기능을 혼동하지 마세요.

claude agents

Agent View는 실행 중(working), 입력 대기(needs input), 완료(completed) 상태의 background session을 한 화면에 보여주고 attach/detach/rename/pin/delete할 수 있습니다. 각 background session은 터미널 없이도 계속 도는 완전한 Claude Code 대화입니다. (research preview, v2.1.139+)

`claude agents`가 서브에이전트 목록만 출력한다면

claude agents가 Agent View를 열지 않고 서브에이전트 개수와 목록만 출력하고 종료된다면 해당 환경에서 Agent View가 비활성 상태입니다. 과거 버전에서는 Bedrock/Vertex AI/Foundry 연결 등 일부 환경에서 열리지 않았습니다. claude update로 최신 버전을 설치하세요.

Agent View에서 시작하는 background session

Agent View 입력창에서 다음 prefix를 사용할 수 있습니다.

입력	동작
`<agent-name> <prompt>`	첫 단어가 custom subagent 이름이면 해당 agent를 main agent로 실행
`@<agent-name>`	prompt 어디에서든 명시적으로 subagent를 main agent로 지정
`@<repo>`	Agent View를 연 상위 디렉토리 아래 repository로 session dispatch
`/<command>`	skills/commands를 prompt로 dispatch
`! <command>`	Claude 호출 없이 shell command를 background job row로 실행
`#<number>` 또는 PR URL	해당 PR을 처리 중인 session이 있으면 새로 만들지 않고 선택

# 현재 세션을 background session으로 전환 (/background의 별칭)
/bg run tests and fix failures

# 셸에서 바로 background session 시작
claude --bg --agent code-reviewer "review PR 1234"

# 모델 호출 없이 shell job을 Agent View에 띄우기
claude --bg --exec 'pytest -x'

셸에서 background session 관리

명령	용도
`claude agents`	Agent View 열기
`claude agents --cwd <path>`	해당 디렉토리 아래에서 시작된 session만 표시 (v2.1.141+)
`claude attach <id>`	현재 터미널에 session attach
`claude logs <id>`	session의 최근 출력 표시
`claude stop <id>`	session 중지 (`claude kill`도 가능)
`claude respawn <id>`	대화를 유지한 채 session 재시작 (`--all`로 전체)
`claude rm <id>`	session을 목록에서 제거
`claude daemon status`	supervisor 상태·버전·소켓 디렉토리·worker 수 출력

서브에이전트 이어가기 — `resume` 제거와 `SendMessage`

Breaking Change (v2.1.77)

Agent 도구의 resume 파라미터가 제거되었습니다. 새 Agent 호출은 항상 fresh하게 시작하므로, 기존 서브에이전트를 이어서 실행하려면 SendMessage({to: agentId}) 방식을 사용해야 합니다. 기존 코드에서 resume을 사용하고 있다면 마이그레이션이 필요합니다.

// 이전 방식 (v2.1.76 이하) — 더 이상 동작하지 않음
// Agent({ resume: agentId, prompt: "계속해줘" })

// 새 방식 (v2.1.77+)
SendMessage({ to: agentId, content: "계속해줘" })

SendMessage는 에이전트 팀 플래그가 필요합니다

SendMessage 도구는 에이전트 팀이 활성화된 경우에만 도구 목록에 주입됩니다. 즉 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1을 설정하지 않으면 SendMessage 호출이 "No such tool available: SendMessage"로 실패합니다. 중지된 서브에이전트가 SendMessage를 받으면 새 Agent 호출 없이 백그라운드에서 자동으로 재개됩니다. 에이전트 ID는 트랜스크립트 파일(~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl)에서도 확인할 수 있습니다.

백그라운드 실행과 알림

서브에이전트는 포그라운드(메인 대화를 블로킹, 권한 프롬프트가 그대로 전달됨) 또는 백그라운드(동시 실행, 세션에서 이미 허용된 권한으로 동작하며 프롬프트가 필요한 호출은 자동 거부)로 실행됩니다.
Claude가 작업 성격에 따라 포그라운드/백그라운드를 결정하며, "백그라운드로 실행해"라고 요청하거나 실행 중 Ctrl+B로 전환할 수 있습니다.
백그라운드 에이전트 완료 알림에는 output file 경로가 포함됩니다. (v2.1.71)
모든 백그라운드 작업을 끄려면 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1을 설정합니다.

대화 포크 (fork) — 실험 기능

CLAUDE_CODE_FORK_SUBAGENT=1을 설정하면 포크(fork) 가 켜집니다(v2.1.117+, 인터랙티브·claude -p·SDK에서 동작). 포크는 처음부터 시작하는 대신 지금까지의 전체 대화를 물려받는 서브에이전트입니다. 시스템 프롬프트·도구·모델·메시지 히스토리를 메인 세션과 똑같이 보므로, 배경을 다시 설명하지 않고 곁다리 작업을 맡길 수 있습니다. 포크의 도구 호출은 메인 대화에 남지 않고 최종 결과만 돌아옵니다.

Claude가 general-purpose 서브에이전트를 쓸 상황에서 대신 포크를 생성합니다(Explore 등 named 서브에이전트는 그대로).
포크든 named 서브에이전트든 모든 spawn이 백그라운드로 실행됩니다(CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1로 동기 실행 가능).
/fork <지시문>으로 직접 포크를 시작할 수 있습니다. 첫 request는 부모의 prompt cache를 재사용하므로 새 서브에이전트보다 저렴합니다.
포크는 다시 포크를 생성할 수 없습니다.

참고 문서

서브에이전트 개요: https://code.claude.com/docs/en/sub-agents (영어)
Agent View(백그라운드 에이전트): https://code.claude.com/docs/en/agent-view (영어)
에이전트 팀: https://code.claude.com/docs/en/agent-teams (영어)
Changelog (memory, Agent(agent_type), Agent View): https://code.claude.com/docs/en/changelog (영어)
Release v2.1.98: https://github.com/anthropics/claude-code/releases/tag/v2.1.98
Release v2.1.101: https://github.com/anthropics/claude-code/releases/tag/v2.1.101
Release v2.1.108: https://github.com/anthropics/claude-code/releases/tag/v2.1.108