서브에이전트 정의 파일 레퍼런스

Claude Code 서브에이전트 정의 파일을 찾아보는 페이지다. 모든 내용은 공식 문서 Claude Code 서브에이전트(원본 날짜 미상, 수집 2026-10-18) 기준이고, 필드 이름·값·경로·환경 변수는 원본 그대로 적었다. 서브에이전트가 무엇이고 언제 쓰는지는 서브에이전트, 따라 할 절차와 예시 정의는 Claude Code 서브에이전트 만들기·운영, 안 될 때는 Claude Code 서브에이전트 문제 해결.

파일 형식#

정의 파일은 YAML frontmatter(--- 사이, 용어 사전) 뒤에 시스템 프롬프트를 마크다운으로 쓴 파일이다. 필수 필드는 name과 description뿐이다. Claude Code 서브에이전트

원본 예(.claude/agents/code-reviewer.md):

---
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 시스템 프롬프트는 받지 않는다. Claude Code 서브에이전트
• 여러 단어 필드는 camelCase(maxTurns, disallowedTools)이고 표와 정확히 같아야 한다. 알아보지 못한 필드는 오류 없이 무시된다. Claude Code 서브에이전트

위치와 우선순위#

같은 이름이 여럿이면 우선순위가 높은 위치의 것을 쓴다. Claude Code 서브에이전트

• 프로젝트: 현재 작업 디렉터리에서 저장소 루트까지 올라가며 모든 .claude/agents/를 훑는다. 중첩된 디렉터리끼리 같은 name이면 작업 디렉터리에 가장 가까운 것이 이긴다. --add-dir·/add-dir로 더한 디렉터리의 .claude/agents/도 로드된다. 원본은 프로젝트 서브에이전트를 버전 관리에 넣어 팀이 함께 쓰고 고치라고 한다. Claude Code 서브에이전트
• 하위 폴더: .claude/agents/와 ~/.claude/agents/는 재귀로 훑으므로 agents/review/ 같은 하위 폴더로 정리해도 된다. 정체는 frontmatter name으로만 정해지고 경로는 상관없다. 같은 디렉터리 트리 안에 같은 name이 둘이면 문서화된 우선순위가 아니라 파일 시스템 읽기 순서로 하나만 로드된다. /doctor가 같은 디렉터리의 이름 중복을 보고하고 이름 바꾸기·지우기를 제안한다. Claude Code 서브에이전트
• 플러그인: 플러그인 agents/도 재귀로 훑지만, 하위 폴더가 범위 이름에 들어간다. 플러그인 my-plugin의 agents/review/security.md는 my-plugin:review:security로 등록된다. Claude Code 서브에이전트
• Managed: managed settings 디렉터리 안 .claude/agents/에 같은 frontmatter 형식의 마크다운 파일을 둔다. 같은 이름의 프로젝트·사용자 서브에이전트보다 우선한다. Claude Code 서브에이전트
• 에이전트 팀: 팀원을 띄울 때 서브에이전트 종류를 이름으로 대면 그 정의의 일부가 팀원에 적용된다. 어떤 범위·어떤 부분이 적용되는지는 원본이 Agent teams 문서로 넘긴다. Claude Code 서브에이전트

--agents CLI 플래그 (JSON)#

세션 동안만 있고 디스크에 저장되지 않아 빠른 시험이나 자동화 스크립트에 쓴다. 한 번에 여러 개를 정의한다. 원본 예(macOS·Linux·WSL): Claude Code 서브에이전트

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은 같은 JSON을 @' … '@ 사이에 넣는다. Claude Code 서브에이전트
• 최상위 키가 에이전트 이름이다(-로 시작하지 않는다). prompt는 파일형의 본문에 해당하고 비워도 된다(v2.1.281 이상). prompt가 비고 memory가 없는 에이전트를 --agent로 세션 에이전트로 고르면 세션 시스템 프롬프트가 바뀌지 않는다. Claude Code 서브에이전트
• 받는 frontmatter 필드: description, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, autoCompactWindow, skills, initialPrompt, memory, effort, background, omitClaudeMd, isolation. color와 experimental은 거부되지 않고 무시된다. Claude Code 서브에이전트
• 비대화형 모드에서는 같은 객체를 담은 JSON 파일 경로도 받는다(예: claude -p --agents ./agents.json "Review my changes", v2.1.281 이상). 대화형 세션에서는 파일 경로를 거부한다. Claude Code 서브에이전트
• 조직은 managed disableSideloadFlags로 시작 때 --agents 플래그를 거부할 수 있다(v2.1.193 이상). Claude Code managed settings 배포
• (2026-10-21 기준) 공식 CLI 문서: Claude Code는 시작 때 --agents 값을 검증하고 잘못된 값이면 끝낸다(검증은 v2.1.242 이상). 검증을 건너뛰는 플래그·환경 변수는 원본이 오류 문서로 넘긴다. 파일 경로 형태는 --print와 함께일 때 받는다(v2.1.281 이상). 비대화형에서 모든 서브에이전트(중첩 포함, 포크 제외)의 시스템 프롬프트 끝에 공통 지시를 붙이려면 -p --append-subagent-system-prompt "..."(v2.1.205 이상) 또는 파일형 --append-subagent-system-prompt-file(v2.1.261 이상, 둘은 함께 못 씀). Claude Code CLI 레퍼런스 → Claude Code CLI 플래그

frontmatter 필드 (원본 표)#

근거: Claude Code 서브에이전트. cacheTtl은 frontmatter 최상위가 아니라 experimental 맵 안에 쓴다. 원본 예:

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

건너뛰는 파일#

프로젝트·사용자·managed agents 디렉터리(또는 --add-dir 디렉터리 아래)의 파일은 frontmatter에 다음 문제가 있으면 세션에 알리지 않고 건너뛴다. Claude Code 서브에이전트

플러그인 서브에이전트는 name이 없거나 파싱이 안 돼도 파일 이름으로 로드된다. 점검 방법은 Claude Code 서브에이전트 문제 해결. Claude Code 서브에이전트

모델 결정 순서#

1. 호출별 model 인자(Claude가 서브에이전트를 부를 때 넘김)
2. 정의의 model frontmatter(inherit는 메인 대화 모델)
3. CLAUDE_CODE_SUBAGENT_MODEL 환경 변수(모델 별칭이나 ID일 때)
4. 메인 대화 모델

근거: Claude Code 서브에이전트. 세부:

• 설치한 mod가 agent.spawn 훅에서 모델을 정하면 호출별 인자 대신 그 모델을 쓴다. Claude Code 서브에이전트

• opus 같은 계열 별칭이 메인 모델로 풀리는 두 경우: 메인 모델이 그 계열이면 [1m] 접미사까지 포함한 메인의 정확한 모델(같은 extended context 창). Anthropic API가 아닌 제공자에서 메인 모델 계열을 알 수 없으면(예: Bedrock의 해석되지 않은 application inference profile ARN) opus 별칭만 해당하고, ANTHROPIC_DEFAULT_OPUS_MODEL을 두면 해당하지 않는다. CLAUDE_CODE_SUBAGENT_MODEL의 별칭은 늘 별칭이 가리키는 버전으로 풀리고, inherit로 두면 설정하지 않은 것과 같다. Claude Code 서브에이전트

• CLAUDE_CODE_SUBAGENT_MODEL만으로는 내장 Explore·Plan의 모델이 바뀌지 않는다. v2.1.251 이전에는 이 변수가 순서 맨 앞이었다. Claude Code 서브에이전트

• 한 모델 강제: CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1(v2.1.257 이상)이면 정의의 model을 무시하고 Claude가 모델을 넘기지 못한다. 두 변수를 함께 두면 CLAUDE_CODE_SUBAGENT_MODEL의 모델, FORCE만 두면 메인 모델(내장 Explore는 내장 표의 모델). 포크와 model: inherit 스킬 서브에이전트는 여전히 메인 모델. 원본 예(모두 Haiku): Claude Code 서브에이전트

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

• 허용 목록: 호출별 인자·frontmatter·환경 변수 값을 조직의 availableModels와 대조한다. 막힌 계열 별칭은 허용 목록이 허락하는 그 계열의 최신 버전으로(v2.1.222 이전에는 상속 모델로), 그 밖의 막힌 값이나 대체가 안 되는 경우는 상속 모델로 돈다. 대화형 세션은 요청 모델과 실제 모델을 경고로 알린다. Claude Code 서브에이전트

• 확인: /tasks에서 서브에이전트 행에 모델(설정된 effort 포함)이 보인다(v2.1.242 이상). 호출별 model은 재개·후속 메시지에도 유지된다(v2.1.211 이전에는 재개 때 빠짐). Claude Code 서브에이전트

• extended thinking은 v2.1.198부터 메인 설정을 그대로 물려받고 서브에이전트별 설정은 없다(이전에는 늘 꺼짐). Claude Code 서브에이전트

• effort: 우선순위가 높은 것부터 CLAUDE_CODE_EFFORT_LEVEL 환경 변수, 호출별 effort 인자(포크가 아닌 서브에이전트, 재개 때 유지, v2.1.292 이상), 정의의 effort 필드 순이다. Claude Code 서브에이전트

도구#

물려받는 도구와 두 필터#

서브에이전트는 메인 대화의 내장 도구와 MCP 도구를 물려받되 두 필터로 좁혀진다. macOS·Linux·WSL에서는 메인에 없어도 Glob·Grep을 받을 수 있다. 포크는 두 필터를 건너뛰고 메인과 정확히 같은 도구 풀을 받는다. Claude Code 서브에이전트

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)만 남는다. 물려받았든 tools에 적었든 나머지 내장 도구는 빠지고, tools가 아무것도 남지 않게 되지 않는 한 오류를 내지 않는다. 그래서 같은 정의가 포그라운드와 백그라운드에서 다른 도구로 풀릴 수 있다. v2.1.280 이전에는 백그라운드에서 LSP를 못 썼다. (2026-10-26 기준) 목록의 TodoWrite를 포함한 할 일 도구는 메인 세션에 있을 때만 서브에이전트도 갖는다(서브에이전트 모델과 무관). 메인 세션의 할 일 도구는 지금 Opus 4.7·Sonnet 4.6·Haiku 4.5 이하 모델에서만 기본이고 TodoWrite는 TaskCreate·TaskGet·TaskList·TaskUpdate 네 도구에 밀려 기본으로 꺼져 있다. Claude Code 도구 레퍼런스 → Claude Code 내장 도구

• ListAgents는 cross-session messaging이 켜진 세션에서 포그라운드 서브에이전트만 물려받는다. 에이전트 팀의 팀원은 작업·cron 도구(TaskCreate, TaskGet, TaskList, TaskUpdate, CronCreate, CronDelete, CronList)를 더 가진다. Task 도구가 없는 세션에서는 서브에이전트에도 작업 도구가 없다. Claude Code 서브에이전트
• v2.1.63에서 Task 도구가 Agent로 이름이 바뀌었고, 설정·정의의 Task(...)는 별칭으로 계속 동작한다. Claude Code 서브에이전트

tools와 disallowedTools#

둘 다 두면 disallowedTools를 먼저 적용하고 남은 풀에서 tools를 푼다. 둘 다에 있는 도구는 빠진다. Claude Code 서브에이전트

원본 예 세 가지: tools: Read, Grep, Glob, Bash(파일 편집·쓰기·MCP 도구 없음), disallowedTools: Write, Edit(Bash·MCP·나머지 풀 유지), disallowedTools: mcp__github(github 서버만 빼고 나머지 유지). 원문은 Claude Code 서브에이전트 만들기·운영. Claude Code 서브에이전트

띄울 수 있는 서브에이전트 제한: Agent(agent_type)#

claude --agent로 메인 스레드로 도는 에이전트는 tools에 Agent(worker, researcher)처럼 쓰면 그 종류만 띄울 수 있다(허용 목록, 다른 종류는 요청이 실패하고 프롬프트에 허용 종류만 보임). 괄호 없는 Agent는 제한 없음, Agent를 아예 빼면 띄우지 못한다. 특정 에이전트만 막고 나머지를 허용하려면 permissions.deny를 쓴다. Claude Code 서브에이전트

• 이 괄호 문법은 claude --agent 메인 스레드에만 적용된다. 서브에이전트 정의의 tools에 Agent를 쓰면 깊이 한도 안에서 자기 서브에이전트를 띄울 수 있지만, 괄호 안 종류 목록은 무시된다. Claude Code 서브에이전트

특정 서브에이전트 끄기#

설정의 permissions.deny에 Agent(서브에이전트 이름)을 둔다(내장·커스텀 모두). CLI로는 claude --disallowedTools "Agent(Explore)". Claude Code 서브에이전트

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

MCP 서버 범위 지정 (mcpServers)#

• 메인 대화에 없는 MCP 서버를 서브에이전트에 준다. 인라인 서버는 서브에이전트가 시작할 때 연결되고 끝나면 끊긴다. 이름 참조는 부모 세션의 연결을 공유한다. 인라인 정의는 .mcp.json 항목과 같은 스키마(서버 이름이 키)이고 stdio, http, sse, ws를 지원한다. Claude Code 서브에이전트
• 이 필드는 서브에이전트로 돌 때(Agent 도구·@-mention)와 메인 세션으로 돌 때(--agent·agent 설정) 모두 적용된다. 메인 세션이면 인라인 서버가 .mcp.json·설정 파일 서버와 함께 시작 때 연결된다. Claude Code 서브에이전트
• 원본 팁: 서버 도구 설명이 메인 대화 컨텍스트를 쓰지 않게 하려면 .mcp.json이 아니라 여기 인라인으로 정의한다. 서브에이전트는 도구를 받고 부모 대화는 받지 않는다. Claude Code 서브에이전트 → 컨텍스트 비용
• 메인 세션의 MCP 제한(--strict-mcp-config, --bare, Enterprise managed MCP, allowedMcpServers·deniedMcpServers)이 frontmatter 서버에도 적용되고, 막힌 서버는 건너뛰며 경고를 보인다. managed 제한은 정의 방식과 상관없이 모든 서브에이전트에 적용된다. 예외: --strict-mcp-config는 --agents나 SDK agents 옵션으로 넘긴 인라인 서버를 거르지 않는다(호출자의 명시 입력이라서). Claude Code 서브에이전트

인라인 서버의 신뢰 규칙 (v2.1.238 이상, 이전에는 신뢰 확인 없이 로드): 프로젝트 .claude/agents/나 --add-dir 디렉터리의 .claude/agents/에 있는 에이전트 파일의 인라인 서버는 그 파일이 온 폴더를 신뢰한 뒤에만 로드된다. Claude Code 서브에이전트

• 신뢰로 치지 않는 것: 상위 폴더의 신뢰, -p·SDK 세션이 settings 파일 훅에 받는 자동 신뢰.
• 그 전에는: 그 파일의 인라인 서버를 모두 건너뛰고, ~/.claude.json에 둘 정확한 projects["<path>"].hasTrustDialogAccepted 키를 디버그 로그에 쓴다.
• 신뢰 작업 공간 저장소 밖의 --add-dir 디렉터리는 따로 신뢰해야 한다.
• 신뢰 확인 없이 로드되는 것: 이미 설정한 서버의 이름 참조, ~/.claude/agents/·--agents·SDK agents·managed 설정이 준 파일의 인라인 서버.

권한 모드 (permissionMode)#

설정 값을 쓴다(Manual 모드는 default). 두지 않으면 메인 대화의 권한 모드를 물려받는다. 메인 대화의 모드가 이 값을 쓸지 정한다. Claude Code 서브에이전트

근거: Claude Code 서브에이전트. 플러그인 서브에이전트는 이 필드를 무시한다.

스킬 미리 로드 (skills)#

• 나열한 각 스킬의 전체 내용이 시작 때 주입된다. 목록의 앞쪽 서로 다른 이름 32개까지. Claude Code 서브에이전트
• 미리 로드할 스킬을 정할 뿐 접근을 정하지 않는다. 필드가 없어도 실행 중 Skill 도구로 프로젝트·사용자·플러그인 스킬을 찾아 부른다. 스킬 호출 자체를 막으려면 tools에서 Skill을 빼거나 disallowedTools에 넣는다. Claude Code 서브에이전트
• disable-model-invocation: true 스킬은 미리 로드할 수 없다(Claude가 부를 수 있는 스킬 집합에서 가져오므로). 번들 /verify 스킬도 해당한다. 없거나 꺼진(조직 정책 등) 스킬은 건너뛰고 디버그 로그에 경고. Claude Code 서브에이전트
• context: fork 스킬과는 반대 방향이다. skills 필드는 서브에이전트가 시스템 프롬프트를 쥐고 스킬 내용을 싣고, context: fork는 스킬 내용을 지정한 에이전트에 넣는다. 어느 쪽이든 대화 기록 없이 시작한다. Claude Code 서브에이전트 → 스킬

지속 메모리 (memory)#

근거: Claude Code 서브에이전트

• 켜면: 시스템 프롬프트에 메모리 디렉터리 읽기·쓰기 지시와, 그 디렉터리 MEMORY.md의 앞 200줄 또는 25KB(먼저 닿는 쪽)가 들어가고 넘으면 정리하라는 지시가 붙는다. Read·Write·Edit 도구가 자동으로 켜진다. Claude Code 서브에이전트
• 자동 메모리(Auto memory)의 일부다. autoMemoryEnabled 설정이나 CLAUDE_CODE_DISABLE_AUTO_MEMORY로 자동 메모리를 끄면 memory 필드는 효과가 없다. Claude Code 서브에이전트
• 원본 권고: project가 권장 기본 범위. 시작 전에 메모리를 참고하고 끝난 뒤 배운 것을 저장하라고 부탁하고, 정의 파일에 메모리 관리 지시를 넣는다(원문은 Claude Code 서브에이전트 만들기·운영). Claude Code 서브에이전트

훅 (hooks)#

• frontmatter 훅은 그 서브에이전트가 활성인 동안만 돌고 끝나면 정리된다. 모든 훅 이벤트를 지원하고, 흔한 것은 PreToolUse(도구 이름 matcher), PostToolUse(도구 이름), Stop(matcher 없음, 런타임에 SubagentStop으로 바뀜). Claude Code 서브에이전트
• Agent 도구·@-mention으로 띄울 때와 --agent·agent 설정으로 메인 세션으로 돌 때 모두 돈다. 메인 세션이면 settings.json 훅과 함께 돈다. Claude Code 서브에이전트
• 신뢰 규칙 (v2.1.218 이상, 이전에는 신뢰하지 않은 폴더·비대화형 세션에서도 돌 수 있었다): 프로젝트 서브에이전트의 frontmatter 훅은 그 파일이 든 폴더의 작업 공간 신뢰 창을 수락한 뒤에만 돈다. 그 전에는 서브에이전트는 그대로 돌되 frontmatter 훅만 건너뛰고 디버그 로그에 신뢰 방법을 적는다. settings 파일 훅보다 엄격해서 상위 폴더 신뢰로는 부족하고 -p 세션은 신뢰로 치지 않는다. ~/.claude/agents/와 --agents의 훅은 이 단계 없이 돈다. 신뢰 작업 공간 저장소 밖의 --add-dir 폴더는 따로 신뢰한다. Claude Code 서브에이전트
• 세션 전체 훅(settings 파일·managed 정책·플러그인)도 서브에이전트 안에서 돈다. settings.json의 PreToolUse 훅은 서브에이전트의 모든 도구 앞에서도 돈다. SubagentStart·SubagentStop은 메인 세션에서 서브에이전트 시작·종료에 반응한다. Claude Code 서브에이전트 → 훅 이벤트 레퍼런스

관련 페이지#

• 서브에이전트 — 정의, 시작 때 로드되는 것, 중첩·동시 실행 한도, 포크, 다른 기능과의 관계
• Claude Code 서브에이전트 만들기·운영 — 만들기·부르기·재개·포크 절차와 원본 예시 정의
• Claude Code 서브에이전트 문제 해결 — 안 보임, 필드 무시, 도구 0개, 훅·MCP가 안 돎