Claude Code 서브에이전트

작업별 워크플로와 향상된 컨텍스트 관리를 위해 Claude Code에서 특화된 AI 서브에이전트를 만들고 사용하세요.

서브에이전트는 특정 유형의 작업을 처리하는 특화된 AI 어시스턴트입니다. 곁가지 작업이 검색 결과, 로그, 다시 참조하지 않을 파일 내용으로 메인 대화를 가득 채울 것 같을 때 서브에이전트를 사용하세요. 서브에이전트는 그 작업을 자체 컨텍스트에서 처리하고 요약만 돌려줍니다. 같은 지시로 같은 종류의 작업자를 계속 띄우게 된다면, 커스텀 서브에이전트를 정의하세요.

각 서브에이전트는 커스텀 시스템 프롬프트, 특정 도구 접근 권한, 독립적인 권한을 갖춘 자체 컨텍스트 윈도에서 실행됩니다. Claude가 어떤 서브에이전트의 description에 들어맞는 작업을 만나면, 그 서브에이전트에게 작업을 위임하고, 서브에이전트는 독립적으로 작업을 수행한 뒤 결과를 반환합니다. 실제로 컨텍스트가 어떻게 절약되는지는, 서브에이전트가 별도 윈도에서 리서치를 처리하는 세션을 보여주는 컨텍스트 윈도 시각화 자료에서 확인할 수 있습니다.

서브에이전트는 하나의 세션 안에서 동작합니다. 여러 독립 세션을 병렬로 실행하면서 한곳에서 모니터링하려면 백그라운드 에이전트를, 서로 통신하는 세션이 필요하다면 에이전트 팀(agent teams)을 참고하세요.

서브에이전트는 다음과 같은 데 도움이 됩니다.

• 탐색과 구현을 메인 대화 밖에 두어 컨텍스트를 보존합니다
• 서브에이전트가 사용할 수 있는 도구를 제한해 제약을 강제합니다
• 사용자 수준 서브에이전트로 여러 프로젝트에서 설정을 재사용합니다
• 특정 도메인에 초점을 맞춘 시스템 프롬프트로 동작을 특화합니다
• Haiku처럼 더 빠르고 저렴한 모델로 작업을 라우팅해 비용을 관리합니다

Claude는 각 서브에이전트의 description을 보고 언제 작업을 위임할지 결정합니다. 서브에이전트를 만들 때는 Claude가 언제 사용해야 하는지 알 수 있도록 description을 명확하게 작성하세요.

Claude Code에는 Explore, Plan, general-purpose 같은 여러 내장 서브에이전트가 포함되어 있습니다. 특정 작업을 처리할 커스텀 서브에이전트를 직접 만들 수도 있습니다.

내장 서브에이전트

Claude Code에는 Claude가 적절한 상황에서 자동으로 사용하는 내장 서브에이전트가 포함되어 있습니다. 각 서브에이전트는 부모 대화의 권한을 상속하되 추가적인 도구 제한이 적용됩니다.

Explore와 Plan은 리서치를 빠르고 저렴하게 유지하기 위해 CLAUDE.md 파일과 부모 세션의 git 상태를 건너뜁니다. 그 외 모든 내장 및 커스텀 서브에이전트는 둘 다 로드합니다. 서브에이전트에 무엇이 전달되는지에 대한 전체 내역은 "시작 시 로드되는 항목"을 참고하세요.

Explore

코드베이스 검색과 분석에 최적화된 빠른 읽기 전용 에이전트입니다.

• 모델: Haiku — 빠르고 지연이 낮습니다
• 도구: 읽기 전용 도구. Write와 Edit는 차단됩니다
• 목적: 파일 발견, 코드 검색, 코드베이스 탐색

Claude는 변경 없이 코드베이스를 검색하거나 이해해야 할 때 Explore에 위임합니다. 이렇게 하면 탐색 결과가 메인 대화 컨텍스트 밖에 머무릅니다.

Explore를 호출할 때 Claude는 철저도 수준을 지정합니다. 타깃이 명확한 조회에는 quick, 균형 잡힌 탐색에는 medium, 포괄적인 분석에는 very thorough를 사용합니다.

Plan

plan 모드에서 계획을 제시하기 전에 컨텍스트를 수집하는 데 사용되는 리서치 에이전트입니다.

• 모델: 메인 대화에서 상속
• 도구: 읽기 전용 도구. Write와 Edit는 차단됩니다
• 목적: 계획 수립을 위한 코드베이스 리서치

plan 모드에 있을 때 Claude가 코드베이스를 이해해야 하면, 리서치를 Plan 서브에이전트에 위임합니다. 그러면 탐색 출력은 별도의 컨텍스트 윈도에 머물고 메인 대화는 읽기 전용 상태로 유지됩니다.

General-purpose

탐색과 실행 양쪽이 모두 필요한 복잡한 다단계 작업을 처리하는 유능한 에이전트입니다.

• 모델: 메인 대화에서 상속
• 도구: 모든 도구
• 목적: 복잡한 리서치, 다단계 작업, 코드 수정

Claude는 작업에 탐색과 수정이 모두 필요하거나, 결과를 해석하기 위한 복잡한 추론이 필요하거나, 서로 의존하는 여러 단계가 필요할 때 general-purpose에 위임합니다.

그 외

Claude Code에는 특정 작업을 위한 추가 헬퍼 에이전트도 포함되어 있습니다. 보통 자동으로 호출되므로 직접 사용할 필요는 없습니다.

내장 서브에이전트는 대화형 세션에서 항상 등록됩니다. 이를 제한하려면 다음과 같이 하세요.

• 특정 내장 유형을 차단하려면 "특정 서브에이전트 비활성화"에서 설명하듯이 permissions.deny에 추가하세요.
• Claude가 어떤 서브에이전트에도 위임하지 못하게 하려면 permissions.deny로 Agent 도구 자체를 차단하세요.
• 비대화형 모드와 Agent SDK에서는 CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1을 설정해 모든 내장 유형을 제거하고 직접 만든 것만 제공하세요.

이러한 내장 서브에이전트 외에도, 커스텀 프롬프트·도구 제한·권한 모드·훅·스킬을 갖춘 서브에이전트를 직접 만들 수 있습니다. 다음 섹션에서는 시작 방법과 서브에이전트 커스터마이징 방법을 설명합니다.

빠른 시작: 첫 번째 서브에이전트 만들기

서브에이전트는 YAML 프론트매터가 있는 Markdown 파일로 정의됩니다. 수동으로 만들거나 /agents 명령으로 만들 수 있습니다.

이 안내는 /agents 명령으로 사용자 수준 서브에이전트를 만드는 과정을 단계별로 보여줍니다. 이 서브에이전트는 코드를 검토하고 코드베이스 개선안을 제안합니다.

서브에이전트 인터페이스 열기

Claude Code에서 다음을 실행하세요.

/agents

위치 선택

Library 탭으로 전환해 Create new agent를 선택한 다음 Personal을 고르세요. 이렇게 하면 서브에이전트가 ~/.claude/agents/에 저장되어 모든 프로젝트에서 사용할 수 있습니다.

Claude로 생성하기

Generate with Claude를 선택하세요. 프롬프트가 나타나면 서브에이전트를 설명하세요.

A code improvement agent 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.

Claude가 식별자, description, 시스템 프롬프트를 대신 생성해 줍니다.

도구 선택

읽기 전용 리뷰어라면 Read-only tools만 남기고 모두 선택 해제하세요. 모든 도구를 선택한 채로 두면 서브에이전트는 메인 대화에서 사용할 수 있는 모든 도구를 상속합니다.

모델 선택

서브에이전트가 사용할 모델을 선택하세요. 이 예시 에이전트에서는 코드 패턴 분석에 필요한 역량과 속도의 균형이 좋은 Sonnet을 선택합니다.

색상 선택

서브에이전트의 배경 색상을 고르세요. 이렇게 하면 UI에서 어떤 서브에이전트가 실행 중인지 식별하는 데 도움이 됩니다.

메모리 설정

User 범위를 선택해 서브에이전트에 ~/.claude/agent-memory/의 영속적 메모리 디렉터리를 부여하세요. 서브에이전트는 이를 사용해 코드베이스 패턴이나 반복되는 이슈 같은 통찰을 여러 대화에 걸쳐 축적합니다. 학습 내용을 영속화하지 않으려면 None을 선택하세요.

저장하고 사용해 보기

설정 요약을 검토하세요. s 또는 Enter를 눌러 저장하거나, e를 눌러 저장한 뒤 에디터에서 파일을 편집하세요. 서브에이전트는 즉시 사용할 수 있습니다. 이렇게 사용해 보세요.

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

Claude가 새 서브에이전트에 위임하면, 서브에이전트가 코드베이스를 스캔해 개선 제안을 반환합니다.

이제 이 머신의 어떤 프로젝트에서든 코드베이스를 분석하고 개선안을 제안하는 데 사용할 수 있는 서브에이전트가 생겼습니다.

서브에이전트는 Markdown 파일로 수동 생성하거나, CLI 플래그로 정의하거나, 플러그인을 통해 배포할 수도 있습니다. 다음 섹션에서 모든 설정 옵션을 다룹니다.

서브에이전트 설정

/agents 명령 사용하기

/agents 명령은 서브에이전트를 관리하는 탭 형식 인터페이스를 엽니다. Running 탭은 실행 중이거나 최근에 끝난 서브에이전트를 나열하고 열거나 중지할 수 있게 해줍니다. Library 탭에서는 다음을 할 수 있습니다.

• 사용 가능한 모든 서브에이전트(내장, 사용자, 프로젝트, 플러그인) 보기
• 가이드형 설정 또는 Claude 생성으로 새 서브에이전트 만들기
• 기존 서브에이전트 설정 및 도구 접근 편집
• 커스텀 서브에이전트 삭제
• 중복이 있을 때 어떤 서브에이전트가 활성인지 확인

서브에이전트를 만들고 관리하는 데 권장되는 방법입니다. 수동 생성이나 자동화를 위해 서브에이전트 파일을 직접 추가할 수도 있습니다.

서브에이전트 범위 선택

서브에이전트는 YAML 프론트매터가 있는 Markdown 파일입니다. 범위에 따라 다른 위치에 저장합니다. 여러 서브에이전트가 같은 이름을 공유할 때 Claude Code는 우선순위가 더 높은 위치의 것을 사용합니다.

프로젝트 서브에이전트(.claude/agents/)는 특정 코드베이스에 특화된 서브에이전트에 적합합니다. 버전 관리에 체크인해 팀이 함께 사용하고 협업으로 개선할 수 있게 하세요.

프로젝트 서브에이전트는 현재 작업 디렉터리에서 위로 거슬러 올라가며 발견되므로, 작업 디렉터리와 저장소 루트 사이의 모든 .claude/agents/가 스캔됩니다. v2.1.178부터는, 이렇게 중첩된 디렉터리 중 둘 이상이 같은 name을 정의하면 Claude Code는 작업 디렉터리에 가장 가까운 정의를 사용합니다.

--add-dir로 추가한 디렉터리도 스캔됩니다. 추가된 디렉터리 안의 .claude/agents/ 폴더는 프로젝트 서브에이전트와 함께 로드됩니다. --add-dir에서 어떤 다른 설정 유형이 로드되는지는 "추가 디렉터리(Additional directories)"를 참고하세요. --add-dir 없이 여러 프로젝트에서 서브에이전트를 공유하려면 ~/.claude/agents/나 플러그인을 사용하세요.

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

Claude Code는 .claude/agents/와 ~/.claude/agents/를 재귀적으로 스캔하므로, 정의를 agents/review/나 agents/research/ 같은 하위 폴더로 정리할 수 있습니다. 식별은 오직 name 프론트매터 필드에서 비롯되므로, 하위 디렉터리 경로는 서브에이전트가 식별되거나 호출되는 방식에 영향을 주지 않습니다. name 값은 트리 전체에서 고유하게 유지하세요. 한 범위 안의 두 파일이 같은 이름을 선언하면, Claude Code는 경고 없이 하나만 남기고 나머지를 버립니다.

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

CLI로 정의한 서브에이전트는 Claude Code 실행 시 JSON으로 전달됩니다. 해당 세션에만 존재하고 디스크에 저장되지 않으므로, 빠른 테스트나 자동화 스크립트에 유용합니다. 한 번의 --agents 호출에서 여러 서브에이전트를 정의할 수 있습니다.

macOS, Linux, WSL

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 플래그는 파일 기반 서브에이전트와 동일한 프론트매터 필드를 JSON으로 받습니다. description, prompt, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, skills, initialPrompt, memory, effort, background, isolation, color가 그것입니다. 시스템 프롬프트에는 prompt를 사용하며, 이는 파일 기반 서브에이전트의 Markdown 본문에 해당합니다.

관리형 서브에이전트는 조직 관리자가 배포합니다. 프로젝트 및 사용자 서브에이전트와 동일한 프론트매터 형식을 사용해, 관리형 설정 디렉터리 안의 .claude/agents/에 Markdown 파일을 배치하세요. 관리형 정의는 같은 이름의 프로젝트 및 사용자 서브에이전트보다 우선합니다.

플러그인 서브에이전트는 설치한 플러그인에서 옵니다. /agents에서 커스텀 서브에이전트와 함께 표시됩니다. 플러그인 서브에이전트 생성에 대한 자세한 내용은 플러그인 컴포넌트 레퍼런스를 참고하세요.

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

이 모든 범위의 서브에이전트 정의는 에이전트 팀에서도 사용할 수 있습니다. 팀원을 띄울 때 서브에이전트 유형을 참조하면, 팀원은 그 정의의 tools와 model을 사용하며, 정의 본문이 팀원의 시스템 프롬프트에 추가 지침으로 덧붙여집니다. 이 경로에서 어떤 프론트매터 필드가 적용되는지는 에이전트 팀(agent teams) 문서를 참고하세요.

서브에이전트 파일 작성하기

서브에이전트 파일은 설정을 위한 YAML 프론트매터 다음에 Markdown으로 작성한 시스템 프롬프트가 오는 형식입니다.

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

---
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.

프론트매터는 서브에이전트의 메타데이터와 설정을 정의합니다. 본문은 서브에이전트의 동작을 이끄는 시스템 프롬프트가 됩니다. 서브에이전트는 전체 Claude Code 시스템 프롬프트가 아니라, 이 시스템 프롬프트와 작업 디렉터리 같은 기본 환경 정보만 받습니다.

서브에이전트는 메인 대화의 현재 작업 디렉터리에서 시작합니다. 서브에이전트 안에서 cd 명령은 Bash나 PowerShell 도구 호출 사이에 유지되지 않으며, 메인 대화의 작업 디렉터리에도 영향을 주지 않습니다. 대신 서브에이전트에 저장소의 격리된 복사본을 주려면 isolation: worktree를 설정하세요.

지원되는 프론트매터 필드

다음 필드를 YAML 프론트매터에 사용할 수 있습니다. name과 description만 필수입니다.

모델 선택

model 필드는 서브에이전트가 사용하는 AI 모델을 제어합니다.

• 모델 별칭: 사용 가능한 별칭 중 하나(sonnet, opus, haiku, fable)를 사용합니다
• 전체 모델 ID: claude-opus-4-8이나 claude-sonnet-4-6 같은 전체 모델 ID를 사용합니다. --model 플래그와 동일한 값을 받습니다
• inherit: 메인 대화와 동일한 모델을 사용합니다
• 생략: 기본값 inherit가 되어 메인 대화와 동일한 모델을 사용합니다

Claude가 서브에이전트를 호출할 때, 해당 호출에 대해 model 파라미터를 전달할 수도 있습니다. Claude Code는 다음 순서로 서브에이전트의 모델을 결정합니다.

1. CLAUDE_CODE_SUBAGENT_MODEL 환경 변수(설정된 경우)
2. 호출별 model 파라미터
3. 서브에이전트 정의의 model 프론트매터
4. 메인 대화의 모델

환경 변수, 호출별 파라미터, 프론트매터 값은 조직의 availableModels 허용 목록과 대조됩니다. 제외된 모델로 해석되는 값은 사용되지 않으며, 서브에이전트는 상속된 모델로 실행됩니다.

서브에이전트 역량 제어

도구 접근, 권한 모드, 조건부 규칙을 통해 서브에이전트가 할 수 있는 일을 제어할 수 있습니다.

사용 가능한 도구

서브에이전트는 기본적으로 메인 대화에서 사용할 수 있는 내부 도구와 MCP 도구를 상속합니다. 다음 도구들은 메인 대화의 UI나 세션 상태에 의존하므로, tools 필드에 나열하더라도 서브에이전트에서는 사용할 수 없습니다.

• AskUserQuestion
• EnterPlanMode
• ExitPlanMode(서브에이전트의 permissionMode가 plan인 경우는 제외)
• ScheduleWakeup
• WaitForMcpServers

도구를 제한하려면 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를 제외한 메인 대화의 모든 도구를 상속합니다. 이 서브에이전트는 Bash, MCP 도구, 그 외 모든 것을 유지합니다.

---
name: no-writes
description: Inherits every tool except file writes
disallowedTools: Write, Edit
---

둘 다 설정된 경우, disallowedTools가 먼저 적용되고 그다음 남은 풀에 대해 tools가 해석됩니다. 두 곳 모두에 나열된 도구는 제거됩니다.

두 필드는 정확한 도구 이름 외에 MCP 서버 수준 패턴도 받습니다. mcp__<서버이름> 또는 mcp__<서버이름>__*는 해당 서버의 모든 도구를 허용하거나 제거합니다. disallowedTools에서는 mcp__*가 모든 서버의 모든 MCP 도구를 제거하기도 합니다. 다음 예시는 다른 서버의 도구와 모든 내장 도구는 유지하면서 github MCP 서버의 모든 도구를 제거합니다.

---
name: local-only
description: Inherits every tool except those from the github MCP server
disallowedTools: mcp__github
---

어떤 서브에이전트를 띄울 수 있는지 제한하기

에이전트가 claude --agent로 메인 스레드로 실행될 때, Agent 도구를 사용해 서브에이전트를 띄울 수 있습니다. 띄울 수 있는 서브에이전트 유형을 제한하려면 tools 필드에서 Agent(agent_type) 구문을 사용하세요.

버전 2.1.63에서 Task 도구는 Agent로 이름이 바뀌었습니다. 설정과 에이전트 정의에 있는 기존 Task(...) 참조는 여전히 별칭으로 동작합니다.

---
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로 메인 스레드로 실행되는 에이전트에만 적용됩니다. 서브에이전트 정의에서 tools에 Agent를 나열하면 그 서브에이전트가 중첩 서브에이전트를 띄울 수 있지만, 괄호 안의 유형 목록은 무시됩니다.

MCP 서버를 서브에이전트로 범위 한정하기

mcpServers 필드를 사용하면 메인 대화에서 사용할 수 없는 MCP 서버에 서브에이전트가 접근하도록 할 수 있습니다. 여기에 정의한 인라인 서버는 서브에이전트가 시작될 때 연결되고 끝날 때 연결이 해제됩니다. 문자열 참조는 부모 세션의 연결을 공유합니다.

mcpServers 필드는 에이전트 파일이 실행될 수 있는 두 가지 맥락 모두에 적용됩니다.

• 서브에이전트로서, Agent 도구나 @-멘션을 통해 띄워질 때
• 메인 세션으로서, --agent나 agent 설정으로 실행될 때

에이전트가 메인 세션일 때, 인라인 서버 정의는 .mcp.json 및 설정 파일의 서버들과 함께 시작 시 연결됩니다.

목록의 각 항목은 인라인 서버 정의이거나, 세션에 이미 구성된 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이 아니라 여기에 인라인으로 정의하세요. 서브에이전트는 도구를 갖지만 부모 대화는 갖지 않습니다.

v2.1.153부터, 메인 세션에 적용되는 MCP 제한은 서브에이전트 프론트매터에 선언된 서버에도 적용됩니다.

• --strict-mcp-config와 --bare
• 엔터프라이즈 관리형 MCP 구성
• allowedMcpServers 및 deniedMcpServers 정책

이 중 하나가 서버를 차단하면, Claude Code는 해당 서버를 건너뛰고 차단된 서버 이름을 알리는 경고를 표시합니다.

관리형 설정 제한은 서브에이전트가 어떻게 정의되었든 모든 서브에이전트에 적용됩니다. --strict-mcp-config는 --agents나 SDK agents 옵션으로 인라인으로 전달한 서버는 필터링하지 않습니다. 이는 명시적인 호출자 입력이기 때문입니다.

권한 모드

permissionMode 필드는 서브에이전트가 권한 프롬프트를 처리하는 방식을 제어합니다. 서브에이전트는 메인 대화에서 권한 컨텍스트를 상속하며, 아래에서 설명하듯 부모 모드가 우선하는 경우를 제외하고 모드를 재정의할 수 있습니다.

bypassPermissions는 주의해서 사용하세요. 권한 프롬프트를 건너뛰므로 서브에이전트가 승인 없이 작업을 실행할 수 있으며, 여기에는 .git, .config/git, .claude, .vscode, .idea, .husky, .cargo, .devcontainer, .yarn, .mvn에 대한 쓰기도 포함됩니다. 명시적 ask 규칙과 rm -rf / 같은 루트 및 홈 디렉터리 삭제는 여전히 프롬프트를 표시합니다. 자세한 내용은 권한 모드를 참고하세요.

부모가 bypassPermissions나 acceptEdits를 사용하면, 이것이 우선하며 재정의할 수 없습니다. 부모가 auto 모드를 사용하면, 서브에이전트는 auto 모드를 상속하고 프론트매터의 permissionMode는 무시됩니다. 분류기가 부모 세션과 동일한 차단 및 허용 규칙으로 서브에이전트의 도구 호출을 평가합니다.

서브에이전트에 스킬 미리 로드하기

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.

나열된 각 스킬의 전체 내용이 시작 시 서브에이전트의 컨텍스트에 주입됩니다. 이 필드는 어떤 스킬을 미리 로드할지를 제어하는 것이지, 서브에이전트가 어떤 스킬에 접근할 수 있는지를 제어하는 것이 아닙니다. 이 필드가 없어도 서브에이전트는 실행 중에 Skill 도구로 프로젝트·사용자·플러그인 스킬을 발견하고 호출할 수 있습니다. 서브에이전트가 스킬을 아예 호출하지 못하게 하려면, tools 목록에서 Skill을 생략하거나 disallowedTools에 추가하세요.

disable-model-invocation: true로 설정된 스킬은 미리 로드할 수 없습니다. 미리 로드는 Claude가 호출할 수 있는 스킬 집합에서 가져오기 때문입니다. 나열된 스킬이 없거나 비활성화되어 있으면, Claude Code는 해당 스킬을 건너뛰고 디버그 로그에 경고를 기록합니다.

이는 서브에이전트에서 스킬을 실행하는 것의 반대입니다. 서브에이전트의 skills를 사용하면 서브에이전트가 시스템 프롬프트를 제어하고 스킬 내용을 로드합니다. 스킬의 context: fork를 사용하면 스킬 내용이 지정한 에이전트에 주입됩니다. 둘 다 동일한 기반 시스템을 사용합니다.

영속적 메모리 활성화

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.

메모리를 얼마나 넓게 적용할지에 따라 범위를 선택하세요.

메모리가 활성화되면 다음과 같습니다.

• 서브에이전트의 시스템 프롬프트에 메모리 디렉터리를 읽고 쓰는 지침이 포함됩니다.
• 서브에이전트의 시스템 프롬프트에는 메모리 디렉터리에 있는 MEMORY.md의 처음 200줄 또는 25KB(둘 중 먼저 도달하는 쪽)도 포함되며, 그 한도를 초과하면 MEMORY.md를 정리하라는 지침이 함께 포함됩니다.
• 서브에이전트가 메모리 파일을 관리할 수 있도록 Read, Write, Edit 도구가 자동으로 활성화됩니다.

영속적 메모리 팁

• project가 권장 기본 범위입니다. 서브에이전트 지식을 버전 관리로 공유할 수 있게 해줍니다. 서브에이전트의 지식이 여러 프로젝트에 두루 적용될 때는 user를, 버전 관리에 체크인하면 안 될 때는 local을 사용하세요.
• 작업을 시작하기 전에 서브에이전트가 메모리를 확인하도록 요청하세요. "이 PR을 검토하되, 전에 본 적 있는 패턴이 있는지 메모리를 확인해 줘."
• 작업을 마친 뒤 서브에이전트가 메모리를 업데이트하도록 요청하세요. "이제 끝났으니, 배운 것을 메모리에 저장해 줘." 시간이 지나면 이것이 서브에이전트를 더 효과적으로 만드는 지식 기반을 쌓아 갑니다.
• 서브에이전트가 스스로 지식 기반을 능동적으로 관리하도록, 서브에이전트의 Markdown 파일에 메모리 지침을 직접 포함하세요.

Update your agent memory as you discover codepaths, patterns, library
locations, and key architectural decisions. This builds up institutional
knowledge across conversations. Write concise notes about what you found
and where.

훅으로 조건부 규칙 적용하기

도구 사용을 더 동적으로 제어하려면, 작업이 실행되기 전에 검증하는 PreToolUse 훅을 사용하세요. 도구의 일부 작업은 허용하면서 다른 작업은 차단해야 할 때 유용합니다.

다음 예시는 읽기 전용 데이터베이스 쿼리만 허용하는 서브에이전트를 만듭니다. PreToolUse 훅은 각 Bash 명령이 실행되기 전에 command에 지정된 스크립트를 실행합니다.

---
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는 훅 입력을 stdin을 통해 JSON으로 훅 명령에 전달합니다. 검증 스크립트는 이 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

전체 입력 스키마는 "Hook input"을, 종료 코드가 동작에 미치는 영향은 "exit codes"를 참고하세요. Windows에서는 훅 스크립트를 PowerShell로 작성하고, "running hooks in PowerShell"에서 보여주듯 훅 항목에 shell: powershell을 추가하세요.

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

설정의 deny 배열에 추가하면 Claude가 특정 서브에이전트를 사용하지 못하게 할 수 있습니다. Agent(subagent-name) 형식을 사용하며, 여기서 subagent-name은 서브에이전트의 name 필드와 일치합니다.

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

이는 내장 및 커스텀 서브에이전트 모두에 동작합니다. --disallowedTools CLI 플래그를 사용할 수도 있습니다.

claude --disallowedTools "Agent(Explore)"

권한 규칙에 대한 자세한 내용은 권한(Permissions) 문서를 참고하세요.

서브에이전트용 훅 정의하기

서브에이전트는 라이프사이클 동안 실행되는 훅을 정의할 수 있습니다. 훅을 구성하는 방법은 두 가지입니다.

• 서브에이전트의 프론트매터: 해당 서브에이전트가 활성인 동안에만 실행되는 훅을 정의합니다
• settings.json: 서브에이전트가 시작하거나 멈출 때 메인 세션에서 실행되는 훅을 정의합니다

서브에이전트 프론트매터의 훅

서브에이전트의 Markdown 파일에 훅을 직접 정의합니다. 이 훅들은 해당 특정 서브에이전트가 활성인 동안에만 실행되며, 끝나면 정리됩니다.

프론트매터 훅은 에이전트가 Agent 도구나 @-멘션을 통해 서브에이전트로 띄워질 때, 그리고 에이전트가 --agent나 agent 설정을 통해 메인 세션으로 실행될 때 발동합니다. 메인 세션인 경우에는 settings.json에 정의된 훅과 함께 실행됩니다.

모든 훅 이벤트가 지원됩니다. 서브에이전트에 가장 흔한 이벤트는 다음과 같습니다.

다음 예시는 PreToolUse 훅으로 Bash 명령을 검증하고, PostToolUse로 파일 편집 후 린터를 실행합니다.

---
name: code-reviewer
description: Review code changes with automatic linting
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh $TOOL_INPUT"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

에이전트가 서브에이전트로 호출되면, 프론트매터의 Stop 훅은 자동으로 SubagentStop 이벤트로 변환됩니다.

서브에이전트 이벤트용 프로젝트 수준 훅

메인 세션에서 서브에이전트 라이프사이클 이벤트에 응답하는 훅을 settings.json에 구성하세요.

두 이벤트 모두 매처를 지원해 특정 에이전트 유형을 이름으로 타깃할 수 있습니다. 다음 예시는 db-agent 서브에이전트가 시작될 때만 설정 스크립트를 실행하고, 어떤 서브에이전트든 멈출 때 정리 스크립트를 실행합니다.

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
        ]
      }
    ]
  }
}

전체 훅 구성 형식은 Hooks를 참고하세요.

서브에이전트 활용하기

자동 위임 이해하기

Claude는 요청의 작업 설명, 서브에이전트 구성의 description 필드, 현재 컨텍스트를 바탕으로 작업을 자동으로 위임합니다. 능동적인 위임을 유도하려면 서브에이전트의 description 필드에 "use proactively" 같은 문구를 포함하세요.

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

자동 위임만으로 충분하지 않을 때는 직접 서브에이전트를 요청할 수 있습니다. 세 가지 패턴이 일회성 제안에서 세션 전체 기본값까지 점차 강해집니다.

• 자연어: 프롬프트에서 서브에이전트 이름을 언급하면 Claude가 위임 여부를 결정합니다
• @-멘션: 해당 서브에이전트가 한 작업 동안 실행되도록 보장합니다
• 세션 전체: --agent 플래그나 agent 설정을 통해 세션 전체가 그 서브에이전트의 시스템 프롬프트, 도구 제한, 모델을 사용합니다

자연어에는 특별한 구문이 없습니다. 서브에이전트 이름을 언급하면 Claude는 보통 위임합니다.

Use the test-runner subagent to fix failing tests
Have the code-reviewer subagent look at my recent changes

서브에이전트를 @-멘션하세요. 파일을 @-멘션하는 것과 동일하게, @를 입력하고 타이프어헤드에서 서브에이전트를 고르세요. 이렇게 하면 선택을 Claude에 맡기지 않고 특정 서브에이전트가 실행되도록 보장합니다.

@"code-reviewer (agent)" look at the auth changes

전체 메시지는 여전히 Claude에 전달되며, Claude는 요청 내용을 바탕으로 서브에이전트의 작업 프롬프트를 작성합니다. @-멘션은 Claude가 어떤 서브에이전트를 호출할지를 제어하는 것이지, 그 서브에이전트가 어떤 프롬프트를 받을지를 제어하는 것이 아닙니다.

활성화된 플러그인이 제공하는 서브에이전트는 타이프어헤드에 범위 이름으로 표시됩니다. 예를 들어 my-plugin:code-reviewer, 또는 플러그인이 에이전트를 하위 폴더로 정리한 경우 my-plugin:review:security처럼 표시됩니다. 세션에서 현재 실행 중인, 이름이 지정된 백그라운드 서브에이전트도 이름 옆에 상태를 보여주며 타이프어헤드에 나타납니다.

피커를 쓰지 않고 멘션을 직접 입력할 수도 있습니다. 로컬 서브에이전트는 @agent-<이름>, 플러그인 서브에이전트는 @agent- 다음에 범위 이름(예: @agent-my-plugin:code-reviewer)을 입력합니다.

세션 전체를 서브에이전트로 실행하세요. --agent <이름>을 전달하면 메인 스레드 자체가 그 서브에이전트의 시스템 프롬프트, 도구 제한, 모델을 취하는 세션이 시작됩니다.

claude --agent code-reviewer

서브에이전트의 시스템 프롬프트는 --system-prompt와 동일한 방식으로 기본 Claude Code 시스템 프롬프트를 완전히 대체합니다. CLAUDE.md 파일과 프로젝트 메모리는 평소대로 메시지 흐름을 통해 로드됩니다. 활성 여부를 확인할 수 있도록 시작 헤더에 에이전트 이름이 @<이름>으로 표시됩니다.

이는 내장 및 커스텀 서브에이전트 모두에 동작하며, 세션을 재개해도 선택이 유지됩니다.

플러그인이 제공하는 서브에이전트는 에이전트 이름만 전달하면 Claude Code가 찾아냅니다.

claude --agent security-reviewer

여러 플러그인이 같은 이름의 에이전트를 제공하면, 범위 이름을 전달해 구분하세요.

claude --agent my-plugin:security-reviewer

플러그인이 에이전트를 자신의 agents/ 디렉터리 하위 폴더에 두었다면, 범위 이름에 하위 폴더를 포함하세요. 예: claude --agent my-plugin:review:security.

프로젝트의 모든 세션에 대해 기본값으로 만들려면, .claude/settings.json에 agent를 설정하세요.

{
  "agent": "code-reviewer"
}

둘 다 있으면 CLI 플래그가 설정을 재정의합니다.

서브에이전트를 포그라운드 또는 백그라운드에서 실행하기

서브에이전트는 포그라운드나 백그라운드에서 실행할 수 있습니다.

• 포그라운드 서브에이전트는 완료될 때까지 메인 대화를 차단합니다. 권한 프롬프트는 발생하는 대로 사용자에게 전달됩니다.
• 백그라운드 서브에이전트는 사용자가 계속 작업하는 동안 동시에 실행됩니다. v2.1.186부터, 백그라운드 서브에이전트가 권한이 필요한 도구 호출에 도달하면 프롬프트가 메인 세션에 나타나며 요청하는 서브에이전트의 이름을 알려줍니다. 승인하면 서브에이전트가 계속 진행하고, Esc를 누르면 서브에이전트를 멈추지 않고 그 한 번의 도구 호출만 거부합니다. v2.1.186 이전에는 백그라운드 서브에이전트가 프롬프트가 발생할 만한 도구 호출을 자동으로 거부했습니다.

Claude는 작업에 따라 서브에이전트를 포그라운드에서 실행할지 백그라운드에서 실행할지 결정합니다. 다음과 같이 할 수도 있습니다.

• Claude에게 "이걸 백그라운드에서 실행해"라고 요청하기
• Ctrl+B를 눌러 실행 중인 작업을 백그라운드로 보내기

모든 백그라운드 작업 기능을 비활성화하려면 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS 환경 변수를 1로 설정하세요. 환경 변수(Environment variables)를 참고하세요.

CLAUDE_CODE_FORK_SUBAGENT가 1로 설정되면, background 필드와 무관하게 모든 서브에이전트 띄우기가 백그라운드에서 실행됩니다. 이 백그라운드 서브에이전트의 권한 프롬프트는 위에서 설명한 대로 메인 세션에 나타납니다.

흔한 패턴

대량 출력 작업 격리하기

서브에이전트의 가장 효과적인 용도 중 하나는 대량의 출력을 만들어 내는 작업을 격리하는 것입니다. 테스트 실행, 문서 가져오기, 로그 파일 처리는 상당한 컨텍스트를 소비할 수 있습니다. 이런 작업을 서브에이전트에 위임하면 장황한 출력은 서브에이전트의 컨텍스트에 머물고, 관련 요약만 메인 대화로 돌아옵니다.

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가 결과를 종합합니다. 이는 리서치 경로들이 서로 의존하지 않을 때 가장 잘 동작합니다.

서브에이전트가 완료되면 그 결과가 메인 대화로 돌아옵니다. 각각 상세한 결과를 반환하는 서브에이전트를 많이 실행하면 상당한 컨텍스트를 소비할 수 있습니다.

지속적인 병렬 처리가 필요하거나 컨텍스트 윈도를 초과하는 작업에는, 각 작업자에게 독립적인 컨텍스트를 주는 에이전트 팀(agent teams)을 사용하세요.

서브에이전트 연결하기

다단계 워크플로에서는 Claude에게 서브에이전트를 순서대로 사용하도록 요청하세요. 각 서브에이전트가 작업을 완료하고 결과를 Claude에 반환하면, Claude가 관련 컨텍스트를 다음 서브에이전트로 넘깁니다.

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

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

다음과 같은 경우에는 메인 대화를 사용하세요.

• 작업에 잦은 주고받기나 반복적 다듬기가 필요할 때
• 계획, 구현, 테스트처럼 여러 단계가 상당한 컨텍스트를 공유할 때
• 빠르고 타깃이 명확한 변경을 할 때
• 지연이 중요할 때. 서브에이전트는 새로 시작하므로 컨텍스트를 모으는 데 시간이 걸릴 수 있습니다

다음과 같은 경우에는 서브에이전트를 사용하세요.

• 작업이 메인 컨텍스트에 필요 없는 장황한 출력을 만들어 낼 때
• 특정 도구 제한이나 권한을 강제하고 싶을 때
• 작업이 자기 완결적이며 요약을 반환할 수 있을 때

격리된 서브에이전트 컨텍스트가 아니라 메인 대화 컨텍스트에서 실행되는 재사용 가능한 프롬프트나 워크플로를 원한다면 스킬(Skills)을 고려하세요.

이미 대화에 있는 내용에 대한 간단한 질문에는 서브에이전트 대신 /btw를 사용하세요. 전체 컨텍스트를 볼 수 있지만 도구 접근은 없으며, 답변은 히스토리에 추가되지 않고 폐기됩니다.

중첩 서브에이전트 띄우기

Claude Code v2.1.172부터, 서브에이전트는 자신의 서브에이전트를 띄울 수 있습니다. 위임된 작업 자체가 병렬 하위 작업으로 갈라질 때 사용하세요. 예를 들어 발견 사항마다 검증기를 디스패치하는 리뷰어 서브에이전트가 그렇습니다. 이렇게 하면 중간 출력이 메인 대화에 절대 도달하지 않습니다. 최상위 서브에이전트의 요약만 사용자에게 돌아옵니다.

중첩 서브에이전트는 최상위 서브에이전트와 동일하게 구성되며, 동일한 범위에서 해석됩니다. 프롬프트 입력 아래의 서브에이전트 패널은 전체 트리를 보여줍니다. 각 행에는 자손 수를 나타내는 (+N)이 표시되고, 행을 열면 그 서브에이전트의 직계 자식과 main까지의 경로가 표시됩니다. /agents의 Running 탭은 실행 중인 서브에이전트를 평면 목록으로 나열합니다.

깊이는 각 수준이 포그라운드에서 실행되든 백그라운드에서 실행되든 관계없이, 메인 대화 아래의 서브에이전트 수준 수로 계산됩니다. 깊이 5의 서브에이전트는 Agent 도구를 받지 못하므로 더 이상 띄울 수 없습니다. 이 한계는 고정되어 있으며 설정할 수 없습니다.

Claude Code v2.1.187부터, 백그라운드 서브에이전트의 깊이는 처음 띄워질 때 고정되며, 나중에 재개해도 그 깊이가 바뀌지 않습니다. 예를 들어 메인 대화가 서브에이전트 A를 띄우고, A가 깊이 2에서 백그라운드 서브에이전트 B를 띄우면, 메인 대화에서 B를 직접 재개하더라도 B는 여전히 깊이 2입니다. 더 얕은 컨텍스트에서 서브에이전트를 재개하더라도, 깊이 한계가 이미 막은 추가 수준을 띄울 수 있게 되지는 않습니다.

특정 서브에이전트가 다른 서브에이전트를 띄우지 못하게 하려면, 그 서브에이전트의 tools 목록에서 Agent를 생략하거나 disallowedTools에 추가하세요.

포크(fork)는 여전히 또 다른 포크를 띄울 수 없습니다. 다만 다른 서브에이전트 유형은 띄울 수 있으며, 그것들은 깊이 한계에 합산됩니다.

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

시작 시 로드되는 항목

각 서브에이전트는 신선하고 격리된 컨텍스트 윈도에서 시작합니다. 사용자의 대화 히스토리, 이미 호출한 스킬, Claude가 이미 읽은 파일을 보지 못합니다. Claude는 작업을 요약하는 위임 메시지를 구성하고, 서브에이전트는 거기서부터 작업합니다. 예외는 포크로, 포크는 새로 시작하는 대신 부모 대화를 상속합니다.

포크가 아닌 서브에이전트의 초기 컨텍스트에는 다음이 포함됩니다.

• 시스템 프롬프트: 전체 Claude Code 시스템 프롬프트가 아니라, 에이전트 자신의 프롬프트와 Claude Code가 덧붙이는 환경 정보입니다. 커스텀 서브에이전트는 Markdown 본문이나 prompt 필드에 자신의 것을 정의합니다. 내장 에이전트는 미리 정의된 프롬프트를 갖습니다.
• 작업 메시지: Claude가 작업을 넘길 때 작성하는 위임 프롬프트입니다.
• CLAUDE.md와 메모리: ~/.claude/CLAUDE.md, 프로젝트 규칙, CLAUDE.local.md, 관리형 정책 파일을 포함해 메인 대화가 로드하는 메모리 계층의 모든 수준입니다. 내장 Explore와 Plan 에이전트는 이를 건너뜁니다.
• Git 상태: 부모 세션 시작 시점에 찍은 스냅샷입니다. 작업 디렉터리가 Git 저장소가 아니거나 includeGitInstructions가 false이면 없습니다. Explore와 Plan은 어느 경우든 건너뜁니다.
• 미리 로드된 스킬: 에이전트의 skills 필드에 명시된 모든 스킬의 전체 내용입니다. 내장 에이전트는 스킬을 미리 로드하지 않습니다.

Explore와 Plan은 CLAUDE.md와 git 상태를 생략하는 유일한 서브에이전트입니다. 어떤 에이전트가 이를 건너뛸지 바꾸는 프론트매터 필드나 에이전트별 설정은 없습니다.

메인 대화는 Explore와 Plan의 결과를 전체 CLAUDE.md 컨텍스트로 읽으므로, 대부분의 규칙은 서브에이전트 자체에 도달할 필요가 없습니다. "vendor/ 디렉터리는 무시해"처럼 어떤 규칙이 반드시 도달해야 한다면, 위임할 때 Claude에 주는 프롬프트에 그것을 다시 명시하세요.

서브에이전트 재개하기

각 서브에이전트 호출은 신선한 컨텍스트를 가진 새 인스턴스를 만듭니다. 처음부터 다시 시작하는 대신 기존 서브에이전트의 작업을 이어가려면, Claude에게 재개하도록 요청하세요.

재개된 서브에이전트는 이전의 모든 도구 호출, 결과, 추론을 포함한 전체 대화 히스토리를 유지합니다. 서브에이전트는 새로 시작하는 것이 아니라 멈췄던 바로 그 지점부터 이어갑니다.

서브에이전트가 완료되면 Claude는 그 에이전트 ID를 받습니다. 내장 Explore와 Plan 에이전트는 일회성이라 에이전트 ID를 반환하지 않으므로 재개할 수 없습니다. 작업을 이어가야 한다면 general-purpose나 커스텀 서브에이전트를 사용하세요.

Claude는 에이전트 ID를 to 필드로 하여 SendMessage 도구로 서브에이전트를 재개합니다. SendMessage 도구는 에이전트 ID나 이름으로 서브에이전트를 재개하는 데 항상 사용할 수 있습니다. shutdown_request나 plan_approval_response 같은 구조화된 팀 프로토콜 메시지는 에이전트 팀이 활성화되어 있어야 합니다.

서브에이전트를 재개하려면, Claude에게 이전 작업을 이어가도록 요청하세요.

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]

멈춰 있던 서브에이전트가 SendMessage를 받으면, 새 Agent 호출 없이 백그라운드에서 자동으로 재개됩니다.

명시적으로 참조하고 싶다면 Claude에게 에이전트 ID를 물어볼 수도 있고, ~/.claude/projects/{project}/{sessionId}/subagents/의 트랜스크립트 파일에서 ID를 찾을 수도 있습니다. 각 트랜스크립트는 agent-{agentId}.jsonl로 저장됩니다.

서브에이전트 트랜스크립트는 메인 대화와 독립적으로 유지됩니다.

• 메인 대화 컴팩션: 메인 대화가 컴팩션될 때 서브에이전트 트랜스크립트는 영향을 받지 않습니다. 별도 파일에 저장됩니다.
• 세션 영속성: 서브에이전트 트랜스크립트는 자신의 세션 안에서 유지됩니다. Claude Code를 재시작한 뒤 같은 세션을 재개하면 서브에이전트를 재개할 수 있습니다.
• 자동 정리: 트랜스크립트는 cleanupPeriodDays 설정에 따라 정리되며, 기본값은 30일입니다.

자동 컴팩션

서브에이전트는 메인 대화와 동일한 로직으로 자동 컴팩션을 지원합니다. 컴팩션은 동일한 조건에서 발동하며, CLAUDE_AUTOCOMPACT_PCT_OVERRIDE도 서브에이전트에 적용됩니다. 이 재정의가 언제 적용되는지는 환경 변수를 참고하세요.

컴팩션 이벤트는 서브에이전트 트랜스크립트 파일에 기록됩니다.

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

preTokens 값은 컴팩션이 일어나기 전에 사용된 토큰 수를 보여줍니다.

현재 대화 포크하기

포크된 서브에이전트는 Claude Code v2.1.117 이상이 필요합니다. v2.1.161부터 /fork 명령은 기본적으로 활성화되어 있으며, 이전 버전에서는 CLAUDE_CODE_FORK_SUBAGENT 환경 변수를 1로 설정해야 합니다. Claude가 직접 포크를 띄우게 하는 것은 실험적이며 향후 릴리스에서 바뀔 수 있습니다. 이 기능은 단계적 출시의 일부로 대화형 세션에서 활성화되어 있을 수도 있습니다.

포크는 새로 시작하는 대신 지금까지의 전체 대화를 상속하는 서브에이전트입니다. 이는 서브에이전트가 본래 제공하는 입력 격리를 포기하는 것입니다. 포크는 메인 세션과 동일한 시스템 프롬프트, 도구, 모델, 메시지 히스토리를 보므로, 상황을 다시 설명할 필요 없이 곁가지 작업을 넘길 수 있습니다. 포크 자신의 도구 호출은 여전히 대화 밖에 머물고 최종 결과만 돌아오므로, 메인 컨텍스트 윈도는 깨끗하게 유지됩니다. 이름이 지정된 서브에이전트라면 너무 많은 배경이 필요해 쓸모가 없을 때, 또는 동일한 출발점에서 여러 접근을 병렬로 시도하고 싶을 때 포크를 사용하세요.

단계적 출시와 무관하게 포크 모드를 제어하려면, CLAUDE_CODE_FORK_SUBAGENT를 1로 설정해 명시적으로 활성화하거나 0으로 설정해 비활성화하세요. 이 변수는 대화형 모드와 SDK, claude -p에서 적용됩니다.

포크 모드를 활성화하면 Claude Code가 두 가지 방식으로 바뀝니다.

• Claude는 fork 서브에이전트 유형을 명시적으로 요청해 포크를 띄울 수 있습니다. 서브에이전트 유형 없이 띄우면 여전히 general-purpose 서브에이전트를 사용하고, Explore 같은 이름이 지정된 서브에이전트는 이전과 동일하게 띄워집니다.
• 모든 서브에이전트 띄우기가 포크든 이름이 지정된 서브에이전트든 백그라운드에서 실행됩니다. 띄우기를 동기적으로 유지하려면 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS를 1로 설정하세요.

변수 설정 여부와 무관하게 /fork 다음에 지시를 붙여 직접 포크를 시작할 수 있습니다. Claude Code는 지시의 첫 단어들로 포크의 이름을 짓습니다. 다음 예시는 메인 세션에서 구현을 계속하는 동안 대화를 포크해 테스트 케이스를 작성합니다.

/fork draft unit tests for the parser changes so far

포크는 프롬프트 아래의 패널에 나타나며, 사용자가 계속 작업하는 동안 백그라운드에서 실행됩니다. 포크가 끝나면 그 결과가 메인 대화에 메시지로 도착합니다. 다음 섹션에서는 포크가 실행되는 동안 지켜보고 조종하는 패널 컨트롤을 다룹니다.

실행 중인 포크 관찰하고 조종하기

실행 중인 포크는 프롬프트 입력 아래의 패널에 나타나며, 메인 세션에 한 행, 각 포크에 한 행씩 표시됩니다. 패널과 상호작용하려면 다음 키를 사용하세요.

포크와 이름이 지정된 서브에이전트의 차이

포크는 띄워지는 순간 메인 세션이 가진 모든 것을 상속합니다. 이름이 지정된 서브에이전트는 자신의 정의에서 시작합니다.

포크의 시스템 프롬프트와 도구 정의는 부모와 동일하므로, 첫 요청은 부모의 프롬프트 캐시를 재사용합니다. 이로 인해 동일한 컨텍스트가 필요한 작업에서는 새 서브에이전트를 띄우는 것보다 포크가 더 저렴합니다.

Claude가 Agent 도구를 통해 포크를 띄울 때 isolation: "worktree"를 전달하면, 포크의 파일 편집이 사용자의 체크아웃이 아니라 별도의 git worktree에 기록됩니다.

제한 사항

CLAUDE_CODE_FORK_SUBAGENT=1은 대화형 세션, 비대화형 모드, Agent SDK에서 포크 모드를 활성화합니다. 0으로 설정하면 서버 측 출시를 포함해 어디서든 포크 모드를 비활성화합니다. 포크는 더 이상의 포크를 띄울 수 없습니다.

서브에이전트 예시

다음 예시는 서브에이전트를 만드는 효과적인 패턴을 보여줍니다. 출발점으로 사용하거나, Claude로 맞춤형 버전을 생성하세요.

모범 사례:

• 초점이 명확한 서브에이전트를 설계하세요: 각 서브에이전트는 하나의 특정 작업에 능해야 합니다
• 상세한 description을 작성하세요: Claude는 description으로 언제 위임할지 결정합니다
• 도구 접근을 제한하세요: 보안과 집중을 위해 필요한 권한만 부여하세요
• 버전 관리에 체크인하세요: 프로젝트 서브에이전트를 팀과 공유하세요

코드 리뷰어(Code reviewer)

코드를 수정하지 않고 검토하는 읽기 전용 서브에이전트입니다. 이 예시는 제한된 도구 접근(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.

디버거(Debugger)

이슈를 분석하고 고치기까지 할 수 있는 서브에이전트입니다. 코드 리뷰어와 달리, 버그 수정에는 코드 변경이 필요하므로 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.

데이터 사이언티스트(Data scientist)

데이터 분석 작업을 위한 도메인 특화 서브에이전트입니다. 이 예시는 일반적인 코딩 작업 외의 특화 워크플로를 위한 서브에이전트를 만드는 방법을 보여줍니다. 더 역량 있는 분석을 위해 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.

데이터베이스 쿼리 검증기(Database query validator)

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.

Claude Code는 훅 입력을 stdin을 통해 JSON으로 훅 명령에 전달합니다. 검증 스크립트는 이 JSON을 읽어 실행 중인 명령을 추출하고, SQL 쓰기 작업 목록과 대조해 확인합니다. 쓰기 작업이 감지되면 스크립트는 종료 코드 2로 종료해 실행을 차단하고, stderr를 통해 Claude에 오류 메시지를 반환합니다.

검증 스크립트는 프로젝트 어디에나 만들 수 있습니다. 경로는 훅 구성의 command 필드와 일치해야 합니다.

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

# Read JSON input from stdin
INPUT=$(cat)

# Extract the command field from tool_input using jq
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을 추가하세요. "running hooks in PowerShell"을 참고하세요.

훅은 stdin을 통해 JSON을 받으며, Bash 명령은 tool_input.command에 들어 있습니다. 종료 코드 2는 작업을 차단하고 오류 메시지를 Claude에 다시 전달합니다. 종료 코드에 대한 자세한 내용은 Hooks를, 전체 입력 스키마는 "Hook input"을 참고하세요.

다음 단계

이제 서브에이전트를 이해했으니, 다음 관련 기능을 살펴보세요.

• 플러그인으로 서브에이전트를 배포해 팀이나 프로젝트 간에 공유하세요
• Agent SDK로 Claude Code를 프로그래밍 방식으로 실행해 CI/CD와 자동화에 활용하세요
• MCP 서버를 사용해 서브에이전트에 외부 도구와 데이터 접근 권한을 부여하세요