사용자 정의 subagent 만들기

• 컨텍스트 보존 - 탐색 및 구현을 주 대화에서 분리하여 유지
• 제약 조건 적용 - subagent가 사용할 수 있는 도구 제한
• 구성 재사용 - 사용자 수준 subagent를 통해 프로젝트 간 구성 재사용
• 동작 특화 - 특정 도메인을 위한 집중된 시스템 프롬프트
• 비용 제어 - Haiku와 같은 더 빠르고 저렴한 모델로 작업 라우팅

내장 subagent

• 특정 내장 유형을 차단하려면 특정 subagent 비활성화에 표시된 대로 permissions.deny에 추가하십시오.
• Claude가 어떤 subagent에도 위임하는 것을 방지하려면 permissions.deny를 사용하여 Agent 도구 자체를 거부하십시오.
• 내장 Explore 및 Plan subagent만 제거하려면 CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1을 설정하십시오. Claude는 이들에게 위임하는 대신 파일을 직접 읽고 탐색합니다. Claude Code v2.1.198 이상이 필요합니다.
• 비대화형 모드 및 Agent SDK에서는 CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1을 설정하여 모든 내장 유형을 제거하고 자신의 것만 제공하십시오.

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

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.

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

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

서브에이전트 구성

서브에이전트 범위 선택

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."
  }
}'

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."
  }
}
'@

• prompt: 에이전트의 시스템 프롬프트로, 파일 기반 서브에이전트의 markdown 본문에 해당합니다. prompt는 비어 있을 수 있습니다. prompt가 비어 있고 memory 필드가 없는 에이전트를 --agent로 세션의 에이전트로 선택하면 세션의 시스템 프롬프트는 변경되지 않습니다. 빈 prompt를 사용하려면 Claude Code v2.1.281 이상이 필요합니다.
• Frontmatter 필드: description, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, autoCompactWindow, skills, initialPrompt, memory, effort, background, omitClaudeMd, isolation.
• 무시되는 필드: color와 experimental은 여기서 허용되지 않으며, 거부되는 대신 무시됩니다.

서브에이전트 파일 작성

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

• git을 메인 체크아웃으로 리디렉션하는 명령을 차단합니다.
• 예를 들어 명령 이름이 런타임에 계산되는 경우처럼, 명령이 실행하는 git이 워크트리 안에 머무는지를 명령 텍스트로 확인할 수 없으면 해당 명령을 거부합니다.

Frontmatter 참조

• 로드된 서브에이전트에서 철자가 잘못된 필드를 찾으려면 셸에서 claude --debug를 실행하고 ~/.claude/debug/<session-id>.txt의 디버그 로그에서 does not recognize or apply를 검색하세요. 디버그 로그는 서브에이전트 파일에서 Claude Code가 인식하지 못하는 최상위 필드를 최대 5개까지 알려 주며, 지원되는 필드와 비슷한 경우 의도했을 가능성이 높은 이름도 함께 표시합니다. Claude Code v2.1.296 이상이 필요합니다.
• 서브에이전트 파일이 로드되지 않은 이유를 알아보려면 Claude Code가 건너뛰는 서브에이전트 파일을 참조하세요.

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

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

• name 없음: Claude Code는 해당 파일을 에이전트 옆에 보관된 문서로 취급합니다.
• 여는 ---가 파일의 첫 줄이 아님: Claude Code는 해당 파일에 frontmatter가 없는 것으로 읽고 문서로 취급합니다.
• name이 -로 시작하거나, :를 포함하거나, 256자를 초과함: Claude Code는 파일을 건너뛰고 디버그 로그에 오류를 기록합니다.
• name은 있지만 description이 없음: Claude Code는 파일을 건너뛰고 디버그 로그에 이유를 기록합니다.
• YAML을 파싱할 수 없음: Claude Code는 파일에서 어떤 필드도 읽지 않고 건너뛰며 디버그 로그에 파싱 오류를 기록합니다.

세션 전에 agents 디렉터리 확인

모델 선택

• 모델 별칭: sonnet, opus, haiku 또는 fable
• 전체 모델 ID: claude-opus-5-5 또는 claude-sonnet-5처럼 --model 플래그가 허용하는 값
• inherit: 메인 대화의 모델, 또는 중첩된 서브에이전트의 경우 해당 서브에이전트를 생성한 서브에이전트의 모델

1. Claude가 서브에이전트를 시작할 때 전달할 수 있는 호출별 model 매개변수. Agent 도구 호출에서 이 매개변수는 전체 모델 ID나 inherit가 아니라 모델 별칭을 받습니다.
2. inherit를 포함한 서브에이전트 정의의 model 필드
3. CLAUDE_CODE_SUBAGENT_MODEL 환경 변수
4. 메인 대화의 모델, 또는 중첩된 서브에이전트의 경우 해당 서브에이전트를 생성한 서브에이전트의 모델

중첩된 서브에이전트가 실행되는 모델

• model: inherit가 설정되었거나 model 필드가 없는 서브에이전트
• 기본 제공 Explore, Plan, general-purpose 서브에이전트
• 포크

서브에이전트의 모델 확인

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

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

• 포크
• model: inherit가 설정된 서브에이전트에서 실행되는 스킬

모델 별칭이 선택하는 버전

• 같은 계열: 예를 들어 메인 대화가 claude-opus-4-7에서 실행되면 model: opus가 설정된 서브에이전트도 해당 버전에서 실행됩니다. 다른 버전을 실행하려면 model 필드에 전체 모델 ID를 설정하세요.
• 알 수 없는 계열: Claude Code가 조회할 수 없는 Amazon Bedrock ARN처럼 부모 모델의 계열을 알 수 없는 경우입니다. 이 경우는 Anthropic API 이외의 제공자에서 opus 별칭에만 적용됩니다. Opus 버전을 선택하려면 ANTHROPIC_DEFAULT_OPUS_MODEL을 설정하세요.

허용 목록이 서브에이전트 모델을 차단하는 경우

1. 차단된 계열 별칭의 경우, 이 대체를 지원하는 제공자에서 해당 계열의 허용된 최신 버전
2. CLAUDE_CODE_SUBAGENT_MODEL을 설정한 경우, 동일한 규칙에 따른 해당 모델
3. 메인 대화의 모델, 또는 중첩된 서브에이전트의 경우 해당 서브에이전트를 생성한 서브에이전트의 모델

서브에이전트의 확장 사고

effort 수준 선택

서브에이전트에 effort 필드나 매개변수가 없는 경우

서브에이전트 기능 제어

사용 가능한 도구

• 서브에이전트가 깊이 제한에 도달한 경우의 Agent. 포크에서는 도구가 목록에 남아 있지만 생성하는 대신 오류를 반환합니다
• AskUserQuestion
• 메인 대화만 종료할 수 있는 EndConversation. EndConversation 도구 동작을 참조하세요
• EnterPlanMode
• 서브에이전트의 permissionMode가 plan이 아닌 경우의 ExitPlanMode
• ScheduleWakeup
• WaitForMcpServers
• Workflow

서브에이전트가 사용할 수 있는 도구 제한

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

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

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

이중 밑줄이 포함된 MCP 서버 이름

• tools의 경우: mcp__reports__v2__*처럼 mcp__ 뒤에 서버의 전체 이름과 __*를 작성합니다. 끝의 __*가 없으면 mcp__reports__v2는 해당 서버의 어떤 도구와도 일치하지 않습니다.
• disallowedTools의 경우: reports라는 이름의 서버를 제외하는 항목인 mcp__reports 또는 mcp__reports__*가 있는지 확인합니다. 두 항목 중 하나라도 있으면 reports__v2 도구 이름도 mcp__reports__로 시작하기 때문에 서브에이전트는 모든 reports__v2 도구도 잃게 됩니다. reports 서버의 도구만 제외하려면 대신 mcp__reports__run_query처럼 하나씩 나열하세요.

생성할 수 있는 서브에이전트 제한

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

tools: Agent, Read, Bash

서브에이전트로 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.

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

인라인 MCP 서버에 필요한 신뢰

• 인정되지 않는 신뢰: 부모 폴더의 신뢰, 그리고 -p 또는 SDK 세션이 설정 파일의 훅에 대해 받는 자동 신뢰
• 신뢰하기 전까지: Claude Code는 해당 에이전트 파일의 모든 인라인 서버를 건너뛰고, ~/.claude.json에 대한 정확한 projects["<path>"].hasTrustDialogAccepted 키를 디버그 로그에 기록합니다
• --add-dir 디렉터리: 신뢰된 워크스페이스의 저장소 외부에 있는 디렉터리는 해당 .claude/agents/ 파일이 워크스페이스의 신뢰를 상속하지 않으므로 자체 신뢰 항목이 필요합니다

• 이미 구성한 서버를 참조하는 이름
• ~/.claude/agents/의 에이전트 파일, --agents 또는 SDK agents 옵션으로 전달한 에이전트 파일, 또는 관리형 설정이 제공하는 에이전트 파일에 있는 인라인 서버

권한 모드

• 메인 대화가 bypassPermissions, acceptEdits 또는 자동 모드인 경우, 서브에이전트는 동일한 모드로 실행되며 Claude Code는 사용자가 설정한 permissionMode를 무시합니다. 자동 모드에서는 분류기가 메인 대화의 차단 및 허용 규칙으로 서브에이전트의 도구 호출을 평가합니다. 서브에이전트가 완료되면 자동 모드가 서브에이전트를 처리하는 방식에 설명된 대로 분류기는 보고서가 전달되기 전에 서브에이전트의 작업과 최종 보고서도 검토합니다. 메인 대화가 bypassPermissions인 상태에서 서브에이전트가 권한을 요청한다면, 해당 도구 호출이 어떤 모드도 자동 승인하지 않는 작업 중 하나인지 확인하세요.
• 메인 대화가 plan 모드인 경우, 서브에이전트가 에이전트 팀 규칙에 따라 에이전트 팀 팀원으로 실행되지 않는 한, 사용자가 설정한 permissionMode와 관계없이 서브에이전트는 플랜 모드를 유지합니다. dontAsk를 설정하면 서브에이전트는 사용자에게 확인도 요청하지 않으며, 플랜 모드에서 승인을 요청하게 될 작업은 대신 거부됩니다.
• 메인 대화가 default 또는 dontAsk 모드인 경우, 서브에이전트는 사용자가 설정한 권한 모드로 실행됩니다. 다만 다음 경우에는 대신 메인 대화의 권한 모드를 유지합니다.
  • 사용자가 bypassPermissions를 설정한 경우. bypassPermissions 예외는 Claude Code v2.1.267 이상이 필요합니다.
  • 사용자가 auto를 설정했지만, 설정 파일이 disableAutoMode를 설정했거나 서브에이전트의 모델이 자동 모드를 지원하지 않는 경우처럼 서브에이전트가 자동 모드를 사용할 수 없는 경우.

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

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

영구 메모리 활성화

---
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가 권장되는 기본 범위입니다. 서브에이전트의 지식을 버전 관리를 통해 공유할 수 있게 합니다.
• 작업을 시작하기 전에 메모리를 참조하도록 서브에이전트에게 요청하세요: “이 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.
  

훅을 사용한 조건부 규칙

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

#!/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

chmod +x ./scripts/validate-readonly-query.sh

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

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

claude --disallowedTools "Agent(Explore)"

서브에이전트용 훅 정의

• 서브에이전트의 frontmatter에서: 해당 서브에이전트가 활성화되어 있는 동안에만 실행되는 훅을 정의합니다
• settings.json에서: 서브에이전트 내부에서도 실행되는 세션 전체 훅을 정의합니다. PreToolUse 및 PostToolUse와 같은 도구 이벤트는 메인 대화에서와 같은 방식으로 서브에이전트의 도구 호출에 대해 실행되며, SubagentStart 및 SubagentStop은 서브에이전트가 시작하거나 완료될 때 실행됩니다

서브에이전트 frontmatter의 훅

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

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

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

서브에이전트 사용하기

자동 위임 이해하기

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

• 자연어: 프롬프트에서 서브에이전트 이름을 언급하면 Claude가 위임 여부를 결정합니다
• @-멘션: 하나의 작업에 대해 해당 서브에이전트가 실행되도록 보장합니다
• 세션 전체: --agent 플래그 또는 agent 설정을 통해 세션 전체가 해당 서브에이전트로 실행됩니다

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

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

claude --agent code-reviewer

claude --agent security-reviewer

claude --agent my-plugin:security-reviewer

{
  "agent": "code-reviewer"
}

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

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

백그라운드에서 실행되는 서브에이전트

• claude -p 및 Agent SDK: Claude는 자체 판단에 따라 또는 사용자가 요청할 때 대기할 수 있습니다.
• 로컬 머신의 대화형 터미널 세션, VS Code 및 데스크톱 앱 세션: Claude가 서브에이전트를 기다리도록 하려면 기본적으로 켜져 있는 포크 모드를 끕니다.

Claude가 서브에이전트를 기다리게 하기

1. CLAUDE_CODE_FORK_SUBAGENT를 0으로 설정해 포크 모드를 끕니다. 예를 들어 settings.json에서 다음과 같이 설정합니다.
   {
     "env": {
       "CLAUDE_CODE_FORK_SUBAGENT": "0"
     }
   }
   
2. 셸에서 claude를 다시 실행하거나 새 VS Code 대화를 엽니다.
3. 결과가 먼저 필요할 때 Claude에게 기다리라고 요청합니다. 예: “run the reviewer subagent and wait for its report”.

백그라운드 서브에이전트의 도구, 권한 및 결과

패널과 작업 목록의 완료된 서브에이전트

• 서브에이전트가 성공적으로 완료되면 Claude Code는 해당 행을 즉시 제거하고, 스크린 리더 모드를 제외하면 푸터에 30초 동안 /tasks to see subagents를 표시합니다. 이 30초 동안 /tasks를 실행하고 서브에이전트에서 Enter를 누르면 트랜스크립트를 열 수 있습니다. v2.1.232 이전에는 Claude Code가 실패한 서브에이전트와 마찬가지로 완료 후 30초 동안 행을 유지했으며 푸터 힌트를 표시하지 않았습니다.
• 서브에이전트가 실패하거나 사용자가 중지하면 Claude Code는 해당 행을 30초 동안 유지합니다. 행을 더 빨리 지우려면 행을 선택하고 x를 누릅니다.

서브에이전트 이름

서브에이전트의 API 오류

• 포그라운드: 속도 제한, 과부하 또는 서버 오류로 이미 텍스트 출력을 생성한 서브에이전트가 중단되면, Agent 도구는 서브에이전트가 중단되어 작업을 완료하지 못했다는 메모와 함께 해당 부분 출력을 반환합니다. 아무것도 생성하지 않았거나 출력이 도구 호출뿐인 서브에이전트는 Agent terminated early due to an API error와 그 뒤의 오류 세부 정보와 함께 실패합니다.
• 백그라운드: 서브에이전트는 실패로 표시되며, 종료 시 Claude가 받는 메시지에는 API 오류 이름과 서브에이전트의 마지막 출력이 포함되므로 부분 작업이 손실되지 않습니다.

⚠ This agent switched to <model> because its earlier model could not be used.

서브에이전트 출력 검사

• 백슬래시 삽입: <system-reminder> 태그나 Human: 또는 Assistant:로 시작하는 줄처럼 Claude Code 자체 출력을 모방하는 텍스트에 백슬래시를 삽입하여, 모방된 텍스트가 대화의 일부로 오인되지 않고 일반 텍스트로 읽히게 합니다.
• 마커 줄: 보고서가 <system-reminder> 같은 태그를 모방하거나 bypassPermissions 또는 --dangerously-skip-permissions와 같은 권한 설정을 언급하면 [harness: subagent output matched instruction-shaped pattern(s):로 시작하는 줄을 앞에 추가합니다. 권한 설정 언급에는 마커 줄이 추가되지만 텍스트 자체는 작성된 그대로 유지됩니다.

일반적인 패턴

대량 출력 작업 격리하기

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

서브에이전트 연결하기

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

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

• 작업에 잦은 주고받기나 반복적인 개선이 필요한 경우
• 계획, 구현, 테스트처럼 여러 단계가 상당한 컨텍스트를 공유하는 경우
• 빠르고 목표가 명확한 변경을 하는 경우
• 지연 시간이 중요한 경우. 포크가 아닌 서브에이전트는 새로 시작하므로 컨텍스트를 수집하는 데 시간이 필요할 수 있습니다

• 작업이 메인 컨텍스트에 필요하지 않은 장황한 출력을 생성하는 경우
• 특정 도구 제한이나 권한을 강제하려는 경우
• 작업이 독립적이며 요약을 반환할 수 있는 경우

서브에이전트가 자체 서브에이전트를 생성하게 하기

• 대화형 터미널 세션: 백그라운드 서브에이전트를 시작한 서브에이전트는 완료되기 전에 그 결과를 기다리므로, 최상위 서브에이전트의 요약만 사용자에게 돌아옵니다.
• claude -p 및 Agent SDK: 포크 모드가 켜져 있는 동안에는 생성하는 서브에이전트가 기다립니다. 포크 모드를 끄면 중첩된 서브에이전트는 대신 백그라운드에서 시작됩니다. 생성하는 서브에이전트는 백그라운드 중첩 서브에이전트를 기다리지 않으며, 중첩 서브에이전트가 생성한 서브에이전트보다 오래 실행되면 메인 대화에 보고합니다.

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

동시 서브에이전트 한도

• /subtask로 시작하는 세션 내 포크는 실행되는 동안 슬롯을 차지하며, 한도에 의해 차단되지 않습니다.
• 이미 완료된 서브에이전트를 재개하면 한도를 확인하지 않고 새 슬롯을 차지하므로, 재개로 인해 실행 중인 수가 한도를 넘을 수 있습니다.

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

시작 시 로드되는 항목

• 시스템 프롬프트: Claude Code 시스템 프롬프트가 아닌, 에이전트 자체 프롬프트와 Claude Code가 덧붙이는 환경 세부 정보입니다. 사용자 지정 서브에이전트는 markdown 본문 또는 prompt 필드에 정의합니다. 기본 제공 에이전트에는 미리 정의된 프롬프트가 있습니다.
• 작업 메시지: Claude가 작업을 넘길 때 작성하는 위임 프롬프트입니다.
• CLAUDE.md 파일: ~/.claude/CLAUDE.md, 프로젝트 규칙, CLAUDE.local.md, 관리형 정책 파일, 프로젝트 지침으로 로드되는 모든 AGENTS.md 파일을 포함해, 메인 대화가 로드하는 CLAUDE.md 계층의 모든 수준입니다. 기본 제공 Explore 및 Plan 에이전트는 이를 건너뜁니다. 정의에서 omitClaudeMd를 설정한 서브에이전트는 관리형 정책 파일만 로드하며, 정의가 관리형 설정에서 온 경우에는 아무것도 로드하지 않습니다.
• Git 상태: 서브에이전트가 시작될 때 Claude Code가 저장소에서 읽는 스냅샷입니다. 해당 저장소의 자체 worktree에 있는 서브에이전트의 경우 스냅샷에는 워크트리의 브랜치, 상태, 최근 커밋이 표시됩니다. Git 저장소 밖에 있거나 스냅샷이 꺼져 있으면 포함되지 않습니다. includeGitInstructions를 참조하세요. Explore와 Plan은 어떤 경우에도 이를 건너뜁니다.
• 미리 로드된 스킬: 에이전트의 skills 필드에 지정된 모든 스킬의 전체 내용입니다. 기본 제공 에이전트는 스킬을 미리 로드하지 않습니다.
• 형제 목록: main과 세션의 다른 모든 이름이 지정된 에이전트를 나열하는 시스템 리마인더로, 각각 SendMessage의 유효한 to 값입니다. 이 목록은 서브에이전트의 도구에 SendMessage가 포함되어 있고, Claude가 생성할 때 이름을 지정했든 에이전트 팀 팀원으로 실행되든 다른 에이전트 중 하나 이상에 이름이 있을 때만 표시됩니다. 서브에이전트가 시작될 때 찍은 스냅샷이므로 이후에 이름이 지정된 에이전트는 표시되지 않습니다.

• 출력 스타일: 서브에이전트는 자체 시스템 프롬프트로 실행되므로, 포크를 제외하면 출력 스타일이 서브에이전트의 응답에 영향을 주지 않습니다.
• 자동 메모리: 메인 대화의 자동 메모리는 로드되지 않습니다. 서브에이전트에 자체 영구 메모리를 제공하려면 memory 필드를 사용합니다.
• 컨텍스트 윈도우 크기: 서브에이전트의 컨텍스트 윈도우 크기는 부모가 아닌 자체 모델에 따라 결정됩니다. 더 작은 윈도우를 가진 모델에 위임하면 해당 서브에이전트는 더 작은 윈도우를 갖게 됩니다.

서브에이전트 재개하기

• 서브에이전트가 완료되면 Claude는 해당 에이전트 ID를 받습니다.
• 기본 제공 Explore 및 Plan 에이전트는 일회성이며 에이전트 ID를 반환하지 않으므로 Claude가 재개할 수 없습니다. 작업을 이어가야 하는 경우 general-purpose 또는 사용자 지정 서브에이전트를 사용합니다.
• 서브에이전트가 maxTurns 한도에서 중지되면 Claude Code는 반환된 출력을 부분 출력으로 표시하며, 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]

• 메인 대화 압축: 메인 대화가 압축되어도 서브에이전트 트랜스크립트는 영향을 받지 않습니다. 별도의 파일에 저장되기 때문입니다.
• 세션 지속성: 서브에이전트 트랜스크립트는 해당 세션 내에서 유지됩니다. Claude Code를 다시 시작한 후 같은 세션을 재개하면 서브에이전트를 재개할 수 있습니다.
• 자동 정리: Claude Code는 보존 정리 규칙에 따라 cleanupPeriodDays 보존 기간(기본값 30일)이 지나면 서브에이전트 트랜스크립트를 삭제합니다.

다시 시작한 후 이름으로 서브에이전트에 메시지 보내기

자동 압축

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

하나의 서브에이전트에 대한 자동 압축 윈도우 설정하기

---
name: log-reader
description: Reads long log files and reports the errors it finds
autoCompactWindow: 200000
---

• 값이 서브에이전트가 원래 상속할 자동 압축 윈도우보다 작지 않은 경우: 더 일찍 압축하려면 해당 윈도우보다 작은 값을 설정합니다.
• --agent 또는 agent 설정으로 세션 전체를 이 서브에이전트로 실행하는 경우: 이때는 필드가 효과가 없습니다. 세션의 윈도우를 설정하려면 자동 압축 윈도우 설정하기를 참조하세요.

현재 대화 포크

• 입력: 포크는 부모 대화와 동일한 시스템 프롬프트, 도구, 모델 및 메시지 기록을 봅니다
• 출력: 포크의 자체 도구 호출은 부모 대화에 포함되지 않으며 최종 결과만 돌아옵니다

/subtask draft unit tests for the parser changes so far

실행 중인 포크 관찰 및 조종

• /compact, /clear, /rewind는 주 대화에 작용하므로, 이 보기에서 이 중 하나를 실행하기 전에 Claude Code가 확인을 요청합니다.
• /model과 /fast는 보고 있는 에이전트가 아닌 주 대화의 모델과 빠른 모드를 설정하므로 이 보기에서는 실행되지 않습니다. 그 이유를 알려 주는 알림이 표시됩니다.

포크와 다른 subagent의 차이점

포크 모드 끄기

• 포크만 중지: 설정의 permissions.deny에 "Agent(fork)"를 추가합니다.
• 포크 모드 끄기: Claude가 서브에이전트를 기다리도록 하기의 단계에 따라 CLAUDE_CODE_FORK_SUBAGENT를 0으로 설정합니다.

예제 subagent

코드 검토자

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

디버거

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

데이터 과학자

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

데이터베이스 쿼리 검증자

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

# 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

chmod +x ./scripts/validate-readonly-query.sh

다음 단계

• 플러그인으로 subagent 배포 - 팀 또는 프로젝트 간에 subagent 공유
• Claude Code를 프로그래밍 방식으로 실행 - CI/CD 및 자동화를 위한 Agent SDK
• MCP 서버 사용 - Subagent에 외부 도구 및 데이터에 대한 액세스 제공