가이드

Claude Code subagents: 만들고, 설정하고, 사용하는 방법

게시일 2026년 10월 30일 · 최종 확인 2026년 10월 30일

subagent는 한 가지 유형의 작업을 자신만의 컨텍스트 윈도우에서 처리하고 요약만 메인 대화로 돌려주는 전문 AI 어시스턴트입니다. 이 글은 Anthropic의 Create custom subagents 문서를 따라가며, subagent란 무엇인지, 내장 subagent, 직접 만드는 방법, 파일 위치, frontmatter 작성법, 모델 선택, 호출 방법, 찾을 수 없을 때 확인할 것을 설명하는 사용법 가이드입니다. 문서는 2026년 10월 30일에 확인했습니다.

subagent란 무엇이고 언제 쓰는가

문서의 기준은 이렇습니다. 곁가지 작업이 다시 참조하지 않을 검색 결과, 로그, 파일 내용으로 메인 대화를 가득 채울 것 같을 때 subagent를 사용하세요. subagent가 그 작업을 자신의 컨텍스트에서 처리하고 요약만 돌려줍니다. 같은 지침으로 같은 종류의 작업자를 계속 만들어 낸다면 커스텀 subagent를 정의하세요.

각 subagent는 커스텀 시스템 프롬프트, 특정 도구 접근, 독립적인 권한을 갖고 자신만의 컨텍스트 윈도우에서 실행됩니다. 자체 요청도 보내며, 이는 메인 대화와 같은 사용 한도에 포함됩니다. Claude가 subagent의 description과 일치하는 작업을 만나면 그 subagent에 위임하고, subagent는 독립적으로 작업해 결과를 돌려줍니다. 문서는 다음과 같은 이점을 나열합니다.

• 탐색과 구현을 메인 대화 밖에 두어 컨텍스트를 보존합니다
• subagent가 쓸 수 있는 도구를 제한해 제약을 강제합니다
• 사용자 수준 subagent로 여러 프로젝트에서 설정을 재사용합니다
• 특정 영역에 초점을 둔 시스템 프롬프트로 동작을 전문화합니다
• Haiku처럼 더 빠르고 저렴한 모델로 작업을 보내 비용을 통제합니다

문서의 참고 사항이 하나 더 있습니다. subagent는 단일 세션 안에서 동작합니다. 독립적인 세션을 여러 개 병렬로 실행하고 한곳에서 모니터링하려면 백그라운드 에이전트를, Claude가 만들고 감독하는 협업 세션 팀에는 agent teams를 안내합니다.

내장 subagent

Claude Code에는 Claude가 적절할 때 자동으로 사용하는 내장 subagent가 포함되어 있습니다. 각각 부모 대화의 권한 규칙을 상속하며, 대부분은 제한된 도구 집합으로 실행됩니다.

Explore와 Plan은 조사를 빠르고 저렴하게 유지하려고 CLAUDE.md 파일과 git status 스냅샷 없이 시작합니다. 다른 내장 subagent와 커스텀 subagent는 둘 다 로드합니다. Explore를 호출할 때 Claude는 철저함 수준을 지정합니다. 특정 조회에는 quick, 균형 잡힌 탐색에는 medium, 종합 분석에는 very thorough입니다.

문서에는 보통 자동으로 호출되는 보조 에이전트도 나열되어 있습니다.

특정 내장 유형을 막으려면 아래 FAQ처럼 permissions.deny에 추가하세요. 내장 Explore와 Plan subagent만 제거하려면 CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1을 설정하세요. 그러면 Claude가 파일을 직접 읽고 탐색합니다. Claude Code v2.1.198 이상이 필요합니다.

첫 subagent 만들기

subagent는 YAML frontmatter가 있는 Markdown 파일입니다. Claude에게 대신 작성해 달라고 하거나 직접 파일을 쓸 수 있습니다. 이 안내는 문서에서 가져온 것으로, 코드를 리뷰하고 개선을 제안하는 사용자 수준 subagent를 만듭니다.

먼저 Claude Code에서 원하는 subagent와 저장 위치를 설명합니다.

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.

Claude는 name, description, tools 목록, model, 시스템 프롬프트를 담아 파일을 작성합니다. 둘째, ~/.claude/agents/code-improver.md를 열어 frontmatter가 요청한 내용과 일치하는지 확인합니다. 결과는 다음과 같습니다.

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

파일이 ~/.claude/agents/에 있으므로 subagent는 이 머신의 모든 프로젝트에서 사용할 수 있습니다. 한 프로젝트로 범위를 좁히려면 그 프로젝트의 .claude/agents/ 디렉터리로 옮기세요. 셋째, Claude에게 위임하라고 요청합니다.

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

Claude가 새 subagent에 위임하면 subagent가 코드베이스를 스캔해 개선 제안을 돌려줍니다. 트랜스크립트에서 위임은 subagent 이름 뒤에 짧은 작업 설명이 붙은 도구 호출 행으로 나타납니다. 예: code-improver(Suggest code improvements).

/agents에 대해: 문서에 따르면 /agents를 실행하면 Claude에게 요청하거나 .claude/agents/와 ~/.claude/agents/를 직접 편집하라는 안내가 출력됩니다. Claude Code v2.1.197 이하에서는 /agents가 실행 중인 subagent를 나열하는 Running 탭과 subagent를 만들고, 편집하고, 삭제하는 Library 탭이 있는 대화형 마법사를 엽니다.

변경 후 재시작할 필요는 없습니다. 문서에 따르면 Claude Code는 ~/.claude/agents/와 .claude/agents/를 감시합니다. 디스크에서 subagent 파일을 추가하거나 편집하거나 Claude에게 작성을 요청하면 몇 초 안에 변경을 감지하고, 다음 위임부터 갱신된 정의를 사용합니다. 그래도 재시작이 필요한 경우가 세 가지 있으며, 문제 해결 섹션에 있습니다.

subagent 파일의 위치

subagent 파일의 위치가 누가 사용할 수 있는지를 정하고, frontmatter가 무엇을 할 수 있는지를 정합니다. 같은 이름의 subagent가 여러 개면 Claude Code는 우선순위가 높은 위치의 것을 사용합니다.

• 프로젝트 subagent(.claude/agents/)는 특정 코드베이스에 맞는 subagent에 이상적입니다. 문서는 팀이 함께 사용하고 개선할 수 있도록 버전 관리에 체크인하라고 권합니다.
• 사용자 subagent(~/.claude/agents/)는 모든 프로젝트에서 사용할 수 있는 개인 subagent입니다.
• Claude Code는 .claude/agents/와 ~/.claude/agents/를 재귀적으로 스캔하므로 정의를 agents/review/나 agents/research/ 같은 하위 폴더로 정리할 수 있습니다. subagent의 식별은 오직 name frontmatter 필드에서 오므로 하위 디렉터리 경로는 식별이나 호출 방식에 영향을 주지 않습니다.
• name 값은 트리 전체에서 고유하게 유지하세요. 같은 .claude/agents/ 디렉터리 아래(하위 폴더 포함)의 두 파일이 같은 이름을 선언하면 Claude Code는 그중 하나만 로드하며, 문서화된 우선순위가 아니라 파일 시스템 읽기 순서로 정해집니다.

프로젝트 subagent는 현재 작업 디렉터리에서 위로 올라가며 탐색하므로, 그곳과 저장소 루트 사이의 모든 .claude/agents/가 스캔됩니다. 이렇게 중첩된 디렉터리 여러 곳이 같은 name을 정의하면 Claude Code는 작업 디렉터리에 가장 가까운 정의를 사용합니다.

가장 중요한 frontmatter 필드

subagent는 파일 맨 위 --- 표시 사이의 YAML frontmatter로 설정하고, 시스템 프롬프트는 닫는 --- 뒤에 Markdown으로 씁니다. 필수 필드는 name과 description뿐입니다. 여러 단어로 된 필드 이름은 maxTurns, disallowedTools처럼 camelCase를 쓰며 표와 정확히 일치해야 합니다. Claude Code는 인식하지 못하는 필드를 오류 없이 무시합니다.

문서에는 autoCompactWindow, omitClaudeMd, color, initialPrompt, experimental을 포함해 더 많은 필드가 나열되어 있으며, 여기서는 다루지 않습니다. 하나 더 있습니다. 파일의 본문이 시스템 프롬프트가 됩니다. subagent는 이 시스템 프롬프트와 작업 디렉터리 같은 기본 환경 정보만 받으며, Claude Code 시스템 프롬프트는 받지 않습니다.

도구 제한하기

도구를 제한하려면 tools 필드를 허용 목록으로, disallowedTools 필드를 거부 목록으로 사용하세요. 둘 다 설정하면 disallowedTools가 먼저 적용되고, 남은 풀에 대해 tools가 해석됩니다. 양쪽에 모두 나열된 도구는 제거됩니다. 문서의 이 예시는 tools로 Read, Grep, Glob, Bash만 허용합니다. subagent는 파일을 편집하거나 쓸 수 없고 어떤 MCP 도구도 쓸 수 없습니다.

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

다음 예시는 disallowedTools로 Write와 Edit를 제외한 subagent의 도구 풀을 상속합니다. subagent는 Bash, MCP 도구, 풀의 나머지를 유지합니다.

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

모델 선택하기

model 필드는 subagent가 어떤 모델을 쓸지 정합니다. 별칭(sonnet, opus, haiku, fable), claude-opus-5-5나 claude-sonnet-5 같은 전체 모델 ID(--model 플래그와 같은 값을 받습니다), 또는 메인 대화와 같은 모델을 쓰는 inherit일 수 있습니다. Claude가 subagent를 호출할 때 그 호출에 한해 model 파라미터를 전달할 수도 있습니다. Claude Code는 subagent의 모델을 다음 순서로 결정합니다.

1. 호출별 model 파라미터
2. subagent 정의의 model frontmatter. inherit는 메인 대화의 모델을 선택합니다
3. 모델 별칭이나 모델 ID로 설정한 경우의 CLAUDE_CODE_SUBAGENT_MODEL 환경 변수
4. 메인 대화의 모델

subagent가 어떤 모델에서 실행되는지 확인하려면 /tasks를 실행하세요. Claude Code가 subagent의 행에 모델을 표시합니다(Claude Code v2.1.242 이상 필요). 모든 subagent를 Haiku에서 실행하는 문서의 예시는 설정 파일의 env 블록에 두 변수를 모두 설정합니다.

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

CLAUDE_CODE_SUBAGENT_MODEL_FORCE는 Claude Code v2.1.257 이상이 필요합니다. 켜져 있는 동안 Claude Code는 subagent 정의의 model 필드를 무시합니다.

subagent는 메인 대화와 다른 모델에서 실행될 수 있고 자체 요청을 보냅니다. 그래서 토큰 단위로 과금된다면 그 요청은 메인 세션이 아니라 subagent 자신의 모델 아래에 나타납니다. 이에 대해서는 관련 설명에서 다룹니다. 모델 선택은 모델과 effort 수준 선택을 참고하세요.

자동 위임과 명시적 호출

자동 위임. Claude는 요청에 담긴 작업 설명, subagent 설정의 description 필드, 현재 컨텍스트를 바탕으로 작업을 자동으로 위임합니다. 적극적인 위임을 유도하려면 subagent의 description 필드에 "use proactively" 같은 문구를 넣으세요. description은 짧게 유지하세요. subagent들의 description 합계(내장 제외)가 15,000 토큰을 넘으면 Claude Code는 시작할 때 경고를 표시하며, 그래도 모든 subagent를 로드합니다.

명시적 호출. 자동 위임으로 충분하지 않으면 직접 subagent를 요청할 수 있습니다. 일회성 제안부터 세션 전체의 기본값까지 단계적으로 강해지는 세 가지 패턴이 있습니다.

• 자연어: 프롬프트에서 subagent를 지목합니다. 위임할지는 Claude가 결정합니다
• @-멘션: 한 작업에 대해 subagent의 실행을 보장합니다
• 세션 전체: --agent 플래그나 agent 설정으로 세션 전체가 그 subagent로 실행됩니다

자연어에는 특별한 문법이 없습니다. subagent를 지목하면 Claude가 보통 위임합니다.

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

@-멘션하려면 @를 입력하고 파일을 @-멘션할 때처럼 자동 완성에서 subagent를 고르세요. 선택을 Claude에게 맡기지 않고 그 subagent가 실행되도록 보장합니다.

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

사용자의 전체 메시지는 여전히 Claude에게 전달되며, Claude는 요청한 내용을 바탕으로 subagent의 작업 프롬프트를 작성합니다. @-멘션은 Claude가 어떤 subagent를 호출할지를 제어하며, 어떤 프롬프트를 받을지는 제어하지 않습니다. 선택기를 쓰지 않고 @agent-<name>으로 직접 입력해도 됩니다.

세션 전체를 subagent로 실행하려면 --agent <name>을 전달하세요. 메인 스레드 자체가 그 subagent의 도구 제한과 모델을 갖는 세션이 시작됩니다.

claude --agent code-reviewer

시작 헤더에 에이전트 이름이 @<name>으로 표시되어 활성 여부를 확인할 수 있습니다. 프로젝트의 모든 세션에서 기본값으로 만들려면 .claude/settings.json에 agent를 설정하세요. 둘 다 있으면 CLI 플래그가 설정을 덮어씁니다.

{
  "agent": "code-reviewer"
}

포그라운드와 백그라운드: 포그라운드 subagent는 완료될 때까지 메인 대화를 막고, 권한 프롬프트는 사용자에게 전달됩니다. 백그라운드 subagent는 사용자가 작업을 계속하는 동안 동시에 실행됩니다. 문서에 따르면 아무것도 설정하지 않았을 때 Claude가 메인 대화에서 만드는 subagent는 백그라운드에서 시작합니다.

전체 예시: 코드 리뷰어

이 예시는 문서의 Example subagents에서 가져온 것으로, 코드를 수정하지 않고 리뷰하는 읽기 전용 subagent입니다. Edit와 Write를 제외한 제한된 도구 접근과, 무엇을 찾고 출력을 어떻게 구성할지 정확히 지정하는 상세한 프롬프트로 초점이 분명한 subagent를 설계하는 방법을 보여 줍니다. .claude/agents/code-reviewer.md로 저장하세요.

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

이 파일에서 model: inherit는 메인 대화와 같은 모델을 쓴다는 뜻이고, description의 "Proactively"와 "Use immediately after writing or modifying code" 표현은 Claude에게 언제 위임할지 알려 줍니다.

문서의 팁

문서의 모범 사례입니다.

• 초점이 분명한 subagent를 설계하세요: 각 subagent는 하나의 특정 작업에서 뛰어나야 합니다.
• 하나의 subagent를 특정하는 description을 쓰세요: Claude는 description으로 언제 위임할지 판단합니다. 각 description을 올바른 subagent로 라우팅할 만큼 구체적으로 쓰고, 전체 집합은 15,000 토큰 description 예산 안에 두세요.
• 도구 접근을 제한하세요: 보안과 집중을 위해 필요한 권한만 부여하세요.
• 버전 관리에 체크인하세요: 프로젝트 subagent를 팀과 공유하세요.

문서의 일반적인 패턴입니다.

• 대량 출력 작업을 격리하세요. 테스트 실행, 문서 가져오기, 로그 파일 처리는 컨텍스트를 많이 소모할 수 있습니다. 이를 위임하면 장황한 출력은 subagent의 컨텍스트에 남고 관련 요약만 메인 대화로 돌아옵니다. 예: Use a subagent to run the test suite and report only the failing tests with their error messages
• 병렬 조사를 실행하세요. 서로 독립적인 조사에는 여러 subagent를 만들어 동시에 작업하게 하세요. 예: Research the authentication, database, and API modules in parallel using separate subagents. 조사 경로가 서로 의존하지 않을 때 가장 잘 동작합니다.
• subagent를 연결하세요. 여러 단계의 워크플로에서는 Claude에게 subagent를 순서대로 쓰라고 요청하세요. 예: Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

문서의 경고입니다. subagent가 완료되면 그 결과가 메인 대화로 돌아옵니다. 상세한 결과를 각각 돌려주는 subagent를 많이 실행하면 컨텍스트를 많이 소모할 수 있고, 각 subagent는 실행되는 동안 자신의 토큰도 소비합니다.

쓰지 말아야 할 때: 작업이 잦은 주고받기나 반복적인 다듬기를 필요로 하거나, 여러 단계가 상당한 컨텍스트를 공유하거나, 빠르고 국소적인 변경을 하거나, 지연 시간이 중요하다면(포크가 아닌 subagent는 새로 시작하므로 컨텍스트를 모으는 데 시간이 걸릴 수 있습니다) 메인 대화를 사용하세요. 격리된 subagent 컨텍스트가 아니라 메인 대화 컨텍스트에서 실행되는 재사용 가능한 프롬프트나 워크플로에는 문서가 대신 skills를 고려하라고 제안합니다.

문제 해결

Claude가 새 subagent를 찾지 못할 때

Claude Code를 재시작하고 다시 시도하세요. 문서에 따르면 이는 세션을 시작하기 전에 ~/.claude/agents/가 없었을 때만 발생합니다. 실행 중인 세션은 새로 만든 agents 디렉터리를 감지하지 못하기 때문입니다. 재시작이 필요한 경우는 세 가지입니다. 새 agents 디렉터리에 어떤 범위의 첫 에이전트 파일을 만든 뒤, --add-dir이나 /add-dir로 추가한 디렉터리에서 subagent를 추가하거나 편집한 뒤, 그리고 이 디렉터리들을 아예 감시하지 않는 --disable-slash-commands로 시작한 세션입니다.

파일이 조용히 건너뛰어질 때

문서에 따르면 frontmatter에 다음 문제 중 하나라도 있으면 Claude Code는 세션에 보고하지 않고 파일을 건너뜁니다.

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

디버그 로그를 보려면 --debug로 Claude Code를 실행하세요. frontmatter가 파싱되지 않는 파일을 찾으려면 .claude/agents나 ~/.claude/agents 같은 디렉터리에 claude plugin validate를 실행하세요(Claude Code v2.1.233 이상 필요). frontmatter는 파싱되지만 name이 없는 파일은 표시하지 않습니다.

필드 철자가 틀렸는데 아무 보고도 없을 때

Claude Code는 인식하지 못하는 필드를 오류 없이 무시합니다. 로드된 subagent라면 셸에서 claude --debug를 실행하고 ~/.claude/debug/<session-id>.txt의 디버그 로그에서 does not recognize or apply를 검색하세요. 로그에는 subagent 파일에서 Claude Code가 인식하지 못하는 최상위 필드가 최대 다섯 개까지 나오고, 지원되는 필드와 가까우면 의도했을 법한 이름도 함께 나옵니다(Claude Code v2.1.296 이상 필요).

subagent가 시작되지 않을 때

tools 목록의 어떤 항목도 도구로 해석되지 않을 때, 예를 들어 모든 항목의 철자가 틀렸거나 subagent가 쓸 수 없는 도구를 지정했을 때, Claude Code는 보통 subagent의 시작을 거부하고 Agent 도구가 해석되지 않은 항목을 명시한 오류를 반환합니다.

subagent가 사용자의 규칙이나 대화를 모를 때

각 subagent는 새롭고 격리된 컨텍스트 윈도우로 시작합니다. 대화 기록, 이미 호출한 skills, Claude가 이미 읽은 파일을 보지 못합니다. Claude가 작업을 요약한 위임 메시지를 작성하고, subagent는 거기서부터 작업합니다. "vendor/ 디렉터리는 무시하라"처럼 subagent에 반드시 전달되어야 하는 규칙이 있다면, 위임할 때 Claude에게 주는 프롬프트에서 다시 말하세요.

FAQ

출처

• Claude Code: Create custom subagents (내장 subagent, 생성 안내, 파일 위치와 우선순위, frontmatter 필드, 모델 결정 순서, 호출, 일반 패턴, 예시, 문제 해결)