7. 서브에이전트

한 줄 정의. 서브에이전트는 자기만의 컨텍스트 창과 프롬프트·도구를 가진 별도 일꾼이고, 리드 에이전트는 곁가지 작업을 거기로 위임한 뒤 길게 부풀린 과정이 아니라 요약만 돌려받는다.

서브에이전트란 무엇이고 왜 격리하는가

서브에이전트를 “별도 컨텍스트 창” 정도로만 이해하면 절반만 본 것입니다. 공식 정의는 네 가지 독립 요소를 묶습니다 — 각 서브에이전트는 자기 컨텍스트 창, 커스텀 시스템 프롬프트, 특정 도구 접근, 독립 권한을 가집니다.¹

컨텍스트만 분리되는 게 아니라 권한·모델·메모리·격리 수준까지 따로 돈다는 뜻입니다. 그래서 탐색용 서브에이전트는 읽기 전용 도구만 받아 절대 파일을 못 고치게 하고, 무거운 리서치는 값싼 모델로 돌리며, 위험한 작업은 격리된 git worktree 안에서만 하도록 묶을 수 있습니다.

언제 떼어 내야 하는지의 기준은 분명합니다. 곁가지 작업이 메인 대화를 다시는 참조하지 않을 검색 결과·로그·파일 내용으로 가득 채울 때, 그 일을 서브에이전트의 자기 컨텍스트에서 처리하고 요약만 돌려받습니다.¹

핵심은 “다시 안 본다”입니다. 수천 줄의 grep 결과를 메인이 두고두고 들춰 볼 일이 없다면, 그 줄들이 메인 컨텍스트에 남아 있을 이유도 없습니다.

이 분리가 5. 컨텍스트 엔지니어링에서 다룬 성능 저하를 막아 줍니다.

같은 종류의 일을 같은 지침으로 반복해서 시킨다면, 그때가 커스텀 서브에이전트를 정의할 시점입니다.¹ 일회성이면 그냥 위임하면 되지만, “코드 리뷰어”나 “테스트 작성기” 같은 일꾼을 매번 같은 프롬프트로 소환한다면 파일로 박제해 두는 편이 낫습니다.

공식 문서가 드는 효용은 다섯 가지입니다 — (1) 메인 컨텍스트 보존, (2) 도구 제한으로 제약 강제, (3) 유저 레벨 설정으로 프로젝트 간 재사용, (4) 집중된 시스템 프롬프트로 행동 특화, (5) Haiku 같은 더 빠르고 싼 모델로 비용 통제입니다.¹

description가 위임의 방아쇠다

Claude는 각 서브에이전트의 description 필드를 보고 “지금 이 일을 여기로 위임할지”를 결정합니다.¹ 그래서 description은 메모가 아니라 라우팅 신호입니다.

“코드를 검토한다”보다 “코드 수정 직후 능동적으로(use proactively) 변경 사항을 검토한다”처럼, 언제 불려야 하는지를 명시해야 자동 위임이 제대로 걸립니다.

내장 서브에이전트: 정의하기 전부터 일하는 기본 일꾼들

커스텀 서브에이전트를 한 줄도 만들지 않아도, Claude Code는 이미 내장 서브에이전트를 갖고 있습니다.¹ 대화형 세션에는 Explore, Plan, general-purpose가 항상 등록되고, statusline-setup이나 claude-code-guide 같은 헬퍼도 함께 따라옵니다.

사용자가 멀티 에이전트를 의식하지 않아도 Claude가 알아서 이 일꾼들에게 곁가지를 떠넘기고 있다는 뜻입니다.

세 주력 일꾼은 성격이 또렷이 다릅니다.

• Explore — 읽기 전용 코드베이스 탐색용입니다. 모델은 Haiku로 고정해 빠르고 저지연으로 돌리며, 도구는 read-only라 Write·Edit 호출을 거부합니다. 호출할 때 thoroughness 레벨을 quick / medium / very thorough 중에서 지정합니다.¹
• Plan — plan mode에서 컨텍스트를 모으는 리서치 에이전트입니다. 모델은 메인 대화에서 상속하고, 도구는 역시 read-only입니다.¹
• general-purpose — 탐색과 행동이 모두 필요한 복잡·다단계 작업용입니다. 모델은 메인 상속, 도구는 All tools라 실제로 파일을 고치고 명령을 실행할 수 있습니다.¹

여기에 미묘하지만 중요한 최적화가 하나 있습니다. Explore와 Plan만 CLAUDE.md와 git status 로드를 건너뜁니다.¹

빠르고 싸게 유지하기 위한 의도적 생략입니다. 그 외 모든 내장·커스텀 서브에이전트는 둘 다 로드하며, 이 로딩을 끄는 frontmatter 필드는 존재하지 않습니다.

즉 “내 커스텀 서브에이전트가 왜 매번 프로젝트 메모리를 읽나”의 답은 “Explore/Plan이 아니기 때문”입니다.

내장 서브에이전트를 막으려면

내장 일꾼이 끼어드는 게 싫다면 permissions.deny에 Agent(Explore)처럼 추가해 특정 에이전트를 차단합니다.¹ 전부 끄려면 비대화형/Agent SDK 환경에서 CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1을 설정합니다.

대화형 세션에서는 항상 등록되므로, 등록 자체를 막는 게 아니라 호출을 거부하는 방식으로 통제해야 합니다.

서브에이전트 정의 형식과 스코프

커스텀 서브에이전트는 YAML frontmatter + Markdown 본문으로 된 .md 파일입니다. 필수 필드는 name과 description 둘뿐이고, 나머지는 모두 선택입니다.¹

본문은 그대로 서브에이전트의 시스템 프롬프트가 됩니다. 중요한 점은, 서브에이전트가 받는 것은 이 프롬프트 + 기본 환경 정보(작업 디렉터리 등)뿐이라는 것입니다 — 전체 Claude Code 시스템 프롬프트는 상속하지 않습니다.¹

그래서 본문을 비워 두면 거의 백지 상태의 일꾼이 되고, 행동을 좁히려면 본문에 직접 지침을 다 써 줘야 합니다.

같은 name이 여러 곳에서 충돌할 수 있어서 스코프와 우선순위가 정해져 있습니다. 높은 쪽이 이깁니다.¹

순위	스코프	위치
1 (최우선)	Managed settings	조직 전역 정책
2	--agents CLI 플래그	세션 한정
3	프로젝트	.claude/agents/
4	유저 전역	~/.claude/agents/
5 (최하위)	플러그인	플러그인의 agents/

프로젝트 서브에이전트는 cwd에서 리포 루트까지 거슬러 올라가며 모든 .claude/agents/ 디렉터리를 스캔합니다. v2.1.178부터는 중첩 디렉터리에 같은 name이 있으면 cwd에 가장 가까운 정의를 씁니다.¹ 모노레포에서 하위 패키지가 루트의 기본 정의를 국소적으로 덮어쓸 수 있다는 뜻입니다.

--agents 플래그는 디스크에 저장하지 않는 세션 한정 JSON 서브에이전트입니다. 빠른 테스트나 자동화에 쓰며, JSON의 prompt 키가 본문(시스템 프롬프트)에 해당합니다.¹

디스크에서 직접 고치면 세션 재시작이 필요하다

서브에이전트 파일은 세션 시작 시 로드됩니다. 그래서 에디터로 .md를 직접 추가·편집하면 그 세션에는 반영되지 않고 재시작해야 합니다.

반면 /agents 인터페이스로 만든 변경은 즉시 반영됩니다.¹ 또 플러그인 서브에이전트는 보안상 hooks·mcpServers·permissionMode 필드를 지원하지 않아 적어도 무시됩니다.¹

frontmatter 필드 전체

필수는 name·description 둘뿐이지만, 지원되는 필드는 훨씬 많습니다 — name, description, tools, disallowedTools, model, permissionMode, maxTurns, skills, mcpServers, hooks, memory, background, effort, isolation, color, initialPrompt입니다.¹ 자주 쓰이는 핵심만 동작 원리와 함께 보겠습니다.

도구 지정(tools / disallowedTools). tools를 생략하면 모든 도구를 상속하고, 적으면 그것이 allowlist가 됩니다. disallowedTools는 상속·지정 목록에서 도구를 빼는 denylist입니다.

둘 다 있으면 disallowedTools를 먼저 적용한 뒤 tools를 해석하며, 양쪽에 같은 도구가 있으면 제거됩니다.¹

모델(model). sonnet/opus/haiku/fable, claude-opus-4-8 같은 전체 모델 ID, 또는 inherit을 받습니다. 기본값은 inherit, 즉 메인 대화와 같은 모델입니다.

그래서 아래 예제의 model: sonnet은 (메인이 Opus라면) 명시적 다운그레이드에 해당합니다.¹ 해석 순서는 (1) CLAUDE_CODE_SUBAGENT_MODEL 환경변수 → (2) 호출별 model 파라미터 → (3) frontmatter model → (4) 메인 대화 모델 순입니다.¹

격리(isolation). worktree로 설정하면 임시 git worktree에서 실행됩니다 — 리포의 격리된 사본을 (기본적으로 parent의 HEAD가 아니라 default branch에서) 브랜치합니다. 변경이 없으면 자동으로 정리됩니다.¹ 위험한 빌드·마이그레이션을 메인 작업 트리에서 떼어 내고 싶을 때 유용합니다.

기타. maxTurns는 서브에이전트가 멈추기 전 최대 에이전틱 턴 수입니다. effort는 low/medium/high/xhigh/max로 세션 effort를 오버라이드하며 가용 레벨은 모델마다 다릅니다.

background: true면 항상 백그라운드 작업으로 실행됩니다(기본 false). color는 red/blue/green/yellow/purple/orange/pink/cyan 중 UI 식별용입니다.¹

name은 파일명과 일치할 필요가 없다

name은 hooks가 agent_type로 받는 식별자이고, 파일명과 같을 필요는 없습니다.¹ 그래서 hook을 특정 서브에이전트에만 걸려면 파일명이 아니라 frontmatter의 name을 기준으로 매칭해야 합니다.

도구 접근 제어와 권한 모드

서브에이전트는 기본적으로 메인 대화의 내부 도구와 MCP 도구를 상속합니다. 다만 어떤 도구는 tools에 적어도 절대 가지 않습니다 — AskUserQuestion, EnterPlanMode, ExitPlanMode(permissionMode가 plan이 아닌 한), ScheduleWakeup, WaitForMcpServers가 그렇습니다.

모두 UI나 세션 상태에 의존하는 도구라 격리된 일꾼에게는 의미가 없기 때문입니다.¹

tools·disallowedTools는 MCP를 서버 단위로 다룰 수 있습니다. mcp__<server> 또는 mcp__<server>__*로 해당 서버 전체를 부여·제거하고, disallowedTools의 mcp__*는 모든 MCP 도구를 한 번에 제거합니다.¹

permissionMode 6종은 서브에이전트의 안전 동작을 결정합니다.¹

• default — 매번 프롬프트
• acceptEdits — 작업 디렉터리 내 편집과 공통 명령을 자동 수락
• auto — 백그라운드 분류기가 검토
• dontAsk — 자동 거부하되 명시적으로 허용한 도구는 작동
• bypassPermissions — 프롬프트를 건너뜀(주의)
• plan — 읽기 전용 탐색

부모의 권한 모드가 자식을 이긴다

부모가 bypassPermissions나 acceptEdits면 그게 우선이라 서브에이전트가 자기 frontmatter로 덮어쓰지 못합니다. 부모가 auto면 서브에이전트도 auto를 상속하고 frontmatter의 permissionMode는 무시됩니다.¹

또 bypassPermissions라도 만능은 아닙니다 — .git/.claude/.vscode 같은 보호 경로 쓰기는 허용하지만, 명시적 ask 룰과 rm -rf / 같은 루트·홈 삭제는 여전히 프롬프트합니다.¹

도구 단위보다 세밀한 통제가 필요하면 PreToolUse 훅을 씁니다. 예컨대 Bash는 허용하되 그 안에서 SQL write만 골라 막으려면, 훅이 명령을 검사해 exit code 2로 차단하면 됩니다.¹

특정 서브에이전트 자체를 막으려면 settings의 deny 배열에 Agent(subagent-name)을 넣거나 --disallowedTools 'Agent(Explore)'처럼 지정합니다.¹

자동 위임과 명시적 호출

Claude는 요청의 작업 설명 + 서브에이전트의 description 필드 + 현재 컨텍스트를 종합해 자동으로 위임합니다. 능동 위임을 유도하려면 description에 “use proactively” 같은 문구를 넣습니다.¹ description이 위임 라우팅의 1차 입력이라는 점이 여기서 다시 확인됩니다.

명시적으로 부르는 방법은 영향 범위가 넓어지는 순서로 세 단계입니다.¹

1. 자연어로 이름 언급 — Claude가 위임할지 말지를 여전히 스스로 판단합니다.
2. @-mention — 특정 서브에이전트를 한 번 실행하도록 보장합니다.
3. --agent 플래그/agent 설정 — 세션 전체가 그 시스템 프롬프트·도구 제한·모델을 쓰게 합니다.

여기에 자주 오해하는 지점이 있습니다. @-mention을 해도 사용자의 전체 메시지는 Claude에게 가고, 서브에이전트의 task 프롬프트는 Claude가 작성합니다.

즉 @-mention은 “어떤” 서브에이전트인지만 고를 뿐 “무슨” 프롬프트를 줄지는 통제하지 않습니다.¹ 한편 --agent로 세션을 통째로 서브에이전트로 돌리면 그 시스템 프롬프트가 기본 Claude Code 시스템 프롬프트를 완전히 대체합니다(--system-prompt와 동일). 이때도 CLAUDE.md와 프로젝트 메모리는 정상 메시지 흐름으로 로드됩니다.¹

위임은 “알아서 해”가 아니다

리드가 목표·출력 형식·도구 지침·작업 경계를 제대로 넘기지 않으면 서브에이전트들이 같은 일을 중복하거나 빈틈을 남깁니다.² 위임은 범위를 잘라 건네는 작업이지, 모호한 지시를 던지는 게 아닙니다.

핸드오프: 제어권 자체를 넘긴다

위임과 결이 다른 패턴이 핸드오프입니다. OpenAI Agents SDK에서 handoff()는 한 에이전트가 다른 에이전트에게 작업을 넘기는 장치이고, LLM에게는 그냥 도구처럼 보입니다.

기본 생성되는 도구명은 transfer_to_<agent_name>입니다.³ 핸드오프가 일어나면 새 에이전트가 대화를 넘겨받아 이전 대화 기록 전체를 보게 되고, 제어권이 넘어가 돌아오지 않습니다.³

세밀한 제어를 위한 파라미터가 풍부합니다 — agent, tool_name_override, tool_description_override, on_handoff, input_type, input_filter, is_enabled, nest_handoff_history입니다.³ 동작 원리를 알아 두면 좋은 것들입니다.

• on_handoff 콜백은 input_type 유무로 시그니처가 갈립니다. 없으면 (ctx: RunContextWrapper[None]), 있으면 (ctx, input_data: <스키마>)의 비동기 함수입니다. 데이터 조회 같은 부수 작업이나 구조화 입력 수집에 씁니다.³
• input_type을 주면 SDK가 그 스키마를 핸드오프 도구의 parameters로 모델에 노출하고, 반환 JSON을 로컬에서 검증·파싱한 값을 on_handoff에 전달합니다.³
• input_filter는 HandoffInputData(input_history, pre_handoff_items, new_items, input_items, run_context)를 받아 다음 에이전트가 볼 내용을 가공합니다. 프리빌트 예로 agents.extensions.handoff_filters.remove_all_tools는 기록에서 모든 도구 호출을 제거합니다.³ 에이전트 사이에서 어떤 6. 메모리와 상태를 넘길지의 문제이기도 합니다.
• is_enabled는 bool 또는 함수로, 런타임 조건에 따라 핸드오프를 켜고 끕니다.³

핸드오프 안내를 프롬프트에 자동으로 넣으려면 agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX나 prompt_with_handoff_instructions()를 씁니다.³

도구로서의 에이전트: 제어권은 안 넘긴다

핸드오프의 반대편에 “도구로서의 에이전트(agent-as-tool)“가 있습니다. agent.as_tool()은 전문 에이전트를 하나의 도구로 감싸서, 중앙 오케스트레이터가 도구 호출처럼 부른 뒤 최종 출력만 받아 다음 행동을 정하게 합니다.

제어권을 넘기지 않는다는 점이 핸드오프와의 결정적 차이입니다 — 운전대를 쥔 채 전문가를 부르는 방식입니다.⁴

공식 예제는 번역 오케스트레이터입니다. orchestrator_agent가 spanish_agent.as_tool(tool_name='translate_to_spanish', ...)와 french_agent.as_tool(...)를 tools로 들고, 호출 결과를 모아 종합합니다.⁴

파라미터도 풍부합니다 — tool_name, tool_description, custom_output_extractor, is_enabled, max_turns, run_config, hooks, previous_response_id/conversation_id/session, needs_approval, parameters, include_input_schema, input_builder, on_stream 등입니다.⁴ 실무에서 자주 쓰는 둘은 다음과 같습니다.

• custom_output_extractor는 async (run_result: RunResult) -> str 시그니처로, 중첩 실행 결과를 후처리합니다. 예컨대 new_items를 역순으로 훑어 ToolCallOutputItem 중 '{'로 시작하는 출력을 골라 JSON만 뽑아 오케스트레이터에 반환할 수 있습니다.⁴
• is_enabled는 True/False 또는 (RunContextWrapper, AgentBase) -> bool 콜러블/비동기 콜러블입니다. 비활성 도구는 런타임에 LLM에서 완전히 숨겨집니다.⁴ 기본 입력은 {"input": "..."}이고, parameters를 주면 그 스키마에 맞는 구조화 인자를 받습니다.⁴

조건부 재시도·폴백은 as_tool로 하지 말 것

조건부 재시도·폴백·체이닝 같은 고급 제어가 필요하면 as_tool의 편의 파라미터에 의존하지 말고, @function_tool 안에서 Runner.run()을 직접 호출하라고 공식 문서가 권합니다.⁴ as_tool은 “한 번 부르고 결과만 받는” 단순 경로에 최적화돼 있습니다.

패턴	제어권	다음 에이전트가 보는 것	적합한 상황
핸드오프	받는 에이전트로 이전(돌아오지 않음)	이전 대화 기록 전체	분류 후 전담 부서로 넘기는 라우팅
도구로서의 에이전트	오케스트레이터가 계속 보유	input 또는 지정 스키마	여러 전문가를 호출해 결과를 종합

포크된 컨텍스트(/fork)와 명명 서브에이전트의 차이

지금까지의 명명 서브에이전트는 fresh 인스턴스입니다 — 프롬프트와 환경만 든 백지에서 시작합니다. 반면 포크는 다릅니다.

포크는 지금까지의 전체 대화를 상속하는 서브에이전트로, 시스템 프롬프트·도구·모델·메시지 기록이 메인과 동일합니다. 입력 격리는 포기하지만, 포크의 도구 호출은 메인에 남지 않고 최종 결과만 돌아와 메인 컨텍스트는 깨끗하게 유지됩니다.¹

축	포크	명명 서브에이전트
컨텍스트	전체 기록 상속	프롬프트만 든 fresh
시스템 프롬프트·도구	메인과 동일	정의 파일
모델	메인과 동일	model 필드
권한	프롬프트 표면화	백그라운드 자동 거부
프롬프트 캐시	메인과 공유	별도 캐시

이 캐시 공유가 경제적 이점입니다. 포크는 첫 요청에서 부모의 prompt cache를 재사용해 fresh 서브에이전트보다 저렴합니다.¹ 전체 기록이 필요한 곁가지를 떼어 낼 때 포크가 합리적인 선택이 되는 이유입니다.

버전과 활성화 조건을 챙겨야 합니다. 포크 서브에이전트는 v2.1.117+가 필요하고, v2.1.161부터 /fork 명령이 기본 활성화됩니다.

그 이전 버전에서는 CLAUDE_CODE_FORK_SUBAGENT=1이 필요합니다.¹ 사용법은 /fork <지시문>이며, Claude가 지시문의 첫 단어로 포크의 이름을 짓습니다.

포크는 백그라운드로 돌고 끝나면 결과가 메인 대화 메시지로 도착합니다.¹

포크는 또 다른 포크를 못 낳는다

포크는 자기 자식으로 또 다른 포크를 spawn하지 못합니다. 다만 다른 명명 서브에이전트 타입은 spawn할 수 있고, 그건 depth 카운트에 포함됩니다.¹ 또 CLAUDE_CODE_FORK_SUBAGENT=1을 켜면 background 필드와 무관하게 모든 서브에이전트 spawn이 백그라운드로 실행되니 주의합니다.¹

Claude Code에서는 스킬 frontmatter의 context: fork 필드로 특정 스킬을 포크 형태로 실행시킬 수도 있습니다(스킬 기본형 참고).

전경/백그라운드 실행과 세 가지 격리 수준

서브에이전트는 단일 세션 안에서 동작합니다. 여러 독립 세션을 병렬로 돌리며 한곳에서 관찰하려면 백그라운드 에이전트(agent view)를, 서로 통신하는 세션이 필요하면 에이전트 팀(agent teams)을 씁니다.¹

세 가지는 격리 수준이 다릅니다 — 서브에이전트는 한 세션 내부의 분리된 컨텍스트, 백그라운드 에이전트는 서로 독립된 세션, 에이전트 팀은 통신하는 다수 세션입니다. 여러 에이전트를 어떻게 엮어 돌릴지는 8. 오케스트레이션 패턴에서 더 깊게 다룹니다.

여기서 실무 핵심은 전경/백그라운드 실행 모드입니다.¹

• Foreground 서브에이전트는 메인 대화를 블로킹하고, 권한 프롬프트가 사용자에게 그대로 전달됩니다.
• Background 서브에이전트는 동시 실행되지만, 세션에 이미 부여된 권한으로만 작동합니다. 프롬프트가 떠야 하는 도구 호출은 묻지 않고 자동 거부됩니다.

이 자동 거부가 백그라운드 작업이 조용히 실패하는 흔한 원인입니다. 다행히 복구 경로가 있습니다 — 백그라운드 서브에이전트가 권한 부족으로 실패하면, 같은 작업으로 전경 서브에이전트를 새로 띄워 대화형 프롬프트로 재시도할 수 있습니다.¹

백그라운드 제어 변수

실행 중인 작업은 Ctrl+B로 백그라운드화할 수 있습니다. 백그라운드 기능 전체를 끄려면 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1을 설정합니다. 반대로 CLAUDE_CODE_FORK_SUBAGENT=1이면 모든 서브에이전트 spawn이 background 필드와 무관하게 백그라운드로 실행됩니다.¹

중첩 서브에이전트·재개·컨텍스트 라이프사이클

v2.1.172부터 서브에이전트가 자기 서브에이전트를 spawn할 수 있습니다. depth는 메인 아래 서브에이전트 레벨 수로 셉니다.

depth 5의 서브에이전트는 Agent 도구를 받지 못해 더 못 spawn하며, 이 한계는 고정값이라 설정으로 바꿀 수 없습니다.¹ 중첩을 막고 싶으면 tools에서 Agent를 빼거나 disallowedTools에 넣으면 그 서브에이전트는 다른 에이전트를 spawn하지 못합니다.

--agent 메인 스레드에서는 Agent(worker,researcher)처럼 spawn 가능 타입의 화이트리스트를 지정할 수 있습니다.¹

Task는 이제 Agent다

v2.1.63부터 Task 도구가 Agent로 개명됐습니다. 기존 Task(...) 별칭은 유지됩니다.¹ 오래된 설정에서 Task(...)를 봐도 같은 도구를 가리킵니다.

비포크 서브에이전트의 초기 컨텍스트가 정확히 무엇으로 채워지는지 알면 디버깅이 쉬워집니다. (1) 시스템 프롬프트(자기 것 + 환경 정보, 전체 Claude Code 프롬프트가 아님), (2) Task 메시지(Claude가 쓴 위임 프롬프트), (3) CLAUDE.md·메모리 계층, (4) git status 스냅샷, (5) preloaded skills로 구성됩니다.¹

결정적으로, 서브에이전트는 대화 기록·이미 invoke한 스킬·이미 읽은 파일을 보지 못합니다. “메인에서 방금 읽은 그 파일을 서브에이전트가 왜 모르나”의 답이 여기 있습니다 — 각 호출은 fresh 컨텍스트의 새 인스턴스이기 때문입니다.¹

재개하면 이야기가 달라집니다. 재개된 서브에이전트는 이전 도구 호출·결과·추론을 포함한 전체 기록을 유지합니다.

다만 Explore와 Plan은 one-shot이라 agent ID를 반환하지 않아 재개가 불가능합니다 — 재개가 필요하면 general-purpose나 커스텀을 써야 합니다.¹ 재개는 SendMessage 도구(to=agent ID)로 하는데, 이는 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1로 agent teams를 켰을 때만 가용합니다.¹

서브에이전트 트랜스크립트는 따로 산다

서브에이전트 기록은 메인과 별도 파일에 저장됩니다 — ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl 경로입니다. 그래서 메인의 compaction과 무관하게 보존되며, cleanupPeriodDays(기본 30일)로 정리됩니다.¹

서브에이전트도 메인과 같은 로직으로 auto-compaction을 지원하고, CLAUDE_AUTOCOMPACT_PCT_OVERRIDE가 적용됩니다.¹

멀티에이전트의 경제성·병렬화·신뢰성

서브에이전트를 나눌지 말지는 결국 비용 대비 효과의 문제입니다. Anthropic의 멀티에이전트 리서치 시스템은 오케스트레이터-워커 패턴을 씁니다 — 리드가 쿼리를 분석하고 전략을 세운 뒤 서브에이전트를 띄워 측면을 동시에 탐색하게 하고, 각 서브에이전트는 “검색 도구를 반복 사용하는 지능형 필터” 역할을 합니다.²

실제로 Opus 4 리드 + Sonnet 4 서브에이전트 구성이 단일 Opus 4보다 내부 리서치 평가에서 90.2% 우위를 보였습니다.²

비용은 만만치 않습니다. 에이전트는 챗 대비 약 4배, 멀티에이전트는 약 15배의 토큰을 씁니다. BrowseComp 평가에서는 토큰 사용량 단독이 성능 분산의 80%를 설명했고, 나머지 약 15%는 도구 호출 수와 모델 선택이 갈랐습니다.² 비싼 만큼 값어치가 있을 때만 나누라는 신호입니다.

그래서 “노력 스케일링”이라는 경험칙이 나옵니다.²

• 단순 사실 확인 — 1 에이전트, 도구 호출 3~10회
• 직접 비교 — 24 서브에이전트, 각 1015회
• 복잡 리서치 — 10+ 서브에이전트

병렬화의 위력은 분명합니다. 리드가 3~5 서브에이전트를 병렬로 spawn하고 각 서브에이전트가 3개 이상의 도구를 병렬로 쓰면, 복잡 쿼리의 리서치 시간을 최대 90% 단축합니다.²

코딩 대부분은 멀티에이전트에 부적합하다

멀티에이전트는 무거운 병렬화와 단일 컨텍스트를 초과하는 정보량에 유효합니다. 반대로 모든 에이전트가 같은 컨텍스트를 공유해야 하는 도메인(대부분의 코딩)이나 진짜 병렬화 가능한 작업이 적은 경우에는 부적합합니다.²

프로덕션 난점도 큽니다 — 상태성과 오류 누적 때문에 재시작이 아니라 resumable 체크포인트가 필요하고, 실행 중인 에이전트를 방해하지 않으려 rainbow deployment를 쓰며, 동기 서브에이전트 실행은 병목이 됩니다(비동기는 결과 조정·상태 일관성·오류 전파 관리 부담을 새로 안깁니다).²

언제 나누고 언제 안 나누나

나누는 쪽이 이득인 신호는 또렷합니다. 곁가지 작업이 메인 대화를 다시 안 볼 내용으로 가득 채울 때, 같은 종류의 일꾼을 같은 지침으로 반복 소환할 때(그러면 커스텀 서브에이전트로 정의), 여러 측면을 병렬로 탐색하는 편이 빠를 때입니다.¹ 도구를 제한해 위험 작업을 막거나, 값싼 모델로 비용을 낮추고 싶을 때도 분리가 유효합니다.

반대로 단순하고 순차적인 작업, 혹은 단계마다 직전 맥락이 그대로 필요한 작업이라면 단일 에이전트가 더 빠르고 쌉니다. 멀티에이전트의 15배 토큰과 조율 부담을 감안하면,² “나눌 이유가 분명할 때만 나눈다”가 안전한 기본값입니다.

예제

Claude Code에서 읽기 전용 코드 리뷰 서브에이전트를 정의하는 최소 형태입니다. frontmatter로 도구를 좁히고 값싼 모델을 명시한 뒤, 본문이 곧 서브에이전트의 시스템 프롬프트가 됩니다.

---
name: code-reviewer
description: 코드 변경을 검토하고 개선점을 제안한다. 코드 수정 직후 능동적으로 사용.
tools: ["Read", "Grep", "Glob"]
model: sonnet
---

당신은 시니어 코드 리뷰어다. 코드 품질·보안·모범 사례에 집중한다.
이슈마다 현재 코드와 개선안을 함께 제시하라.

리드 에이전트는 이 서브에이전트의 description을 보고 “지금 위임할지”를 판단합니다.¹ 위임받은 서브에이전트는 자기 컨텍스트 창에서 코드베이스를 훑어 리뷰를 만들고, 그 과정의 검색 결과가 아니라 정리된 제안만 메인 대화로 돌려줍니다.

여기서 model: sonnet은 (메인이 Opus라면) 의도적 다운그레이드이고, tools를 세 개로 좁힌 것은 이 일꾼이 절대 파일을 못 고치게 강제하는 안전장치입니다.

요약 · 체크리스트

• 서브에이전트가 컨텍스트·프롬프트·도구·권한의 네 요소를 독립적으로 갖는다는 것과, 다섯 가지 효용(컨텍스트 보존·제약 강제·재사용·행동 특화·비용 통제)을 설명할 수 있습니다.
• 내장 Explore(Haiku·read-only)·Plan(상속·read-only)·general-purpose(상속·All tools)의 차이와, Explore/Plan만 CLAUDE.md·git status를 건너뛴다는 점을 압니다.
• frontmatter의 tools/disallowedTools 해석 순서, model 기본값 inherit, isolation: worktree, permissionMode 6종과 부모 우선 규칙을 구분합니다.
• 위임(요약만 회수)·핸드오프(제어권 이전·기록 전체 전달)·도구로서의 에이전트(제어권 보유)의 차이를 한 문장씩 설명할 수 있습니다.
• 포크(전체 기록 상속·캐시 공유)와 명명 서브에이전트(fresh·별도 캐시)의 차이, 전경/백그라운드 실행과 자동 거부, depth 5 한계와 트랜스크립트 경로를 압니다.
• 멀티에이전트가 약 15배 토큰을 쓰고 토큰량이 성능 분산의 80%를 설명한다는 비용 구조와, 코딩 대부분이 부적합하다는 신호를 압니다.

관련 장

• 6. 메모리와 상태
• 8. 오케스트레이션 패턴
• 5. 컨텍스트 엔지니어링

Footnotes

1. Create custom subagents — Claude Code Docs ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹ ↩¹⁰ ↩¹¹ ↩¹² ↩¹³ ↩¹⁴ ↩¹⁵ ↩¹⁶ ↩¹⁷ ↩¹⁸ ↩¹⁹ ↩²⁰ ↩²¹ ↩²² ↩²³ ↩²⁴ ↩²⁵ ↩²⁶ ↩²⁷ ↩²⁸ ↩²⁹ ↩³⁰ ↩³¹ ↩³² ↩³³ ↩³⁴ ↩³⁵ ↩³⁶ ↩³⁷ ↩³⁸ ↩³⁹ ↩⁴⁰ ↩⁴¹ ↩⁴² ↩⁴³ ↩⁴⁴ ↩⁴⁵ ↩⁴⁶ ↩⁴⁷ ↩⁴⁸ ↩⁴⁹ ↩⁵⁰ ↩⁵¹ ↩⁵² ↩⁵³ ↩⁵⁴ ↩⁵⁵ ↩⁵⁶ ↩⁵⁷

2. How we built our multi-agent research system — Anthropic Engineering ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹

3. Handoffs — OpenAI Agents SDK ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸

4. Tools (Agents as tools) — OpenAI Agents SDK ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷