커스텀 서브에이전트 생성

Claude Code에서 특화된 AI 서브에이전트를 생성하고 사용하여 작업별 워크플로우와 향상된 컨텍스트 관리를 구현합니다.

서브에이전트는 특정 유형의 작업을 처리하는 특화된 AI 어시스턴트입니다. 각 서브에이전트는 커스텀 시스템 프롬프트, 특정 도구 접근 권한, 독립적인 권한을 가진 자체 컨텍스트 윈도우에서 실행됩니다. Claude가 서브에이전트의 설명과 일치하는 작업을 만나면 해당 서브에이전트에 위임하고, 서브에이전트는 독립적으로 작업한 후 결과를 반환합니다.

참고:

여러 에이전트가 병렬로 작업하고 서로 통신해야 하는 경우, 에이전트 팀을 참조하세요. 서브에이전트는 단일 세션 내에서 작동하고, 에이전트 팀은 별도의 세션 간에 조율됩니다.

서브에이전트가 도움이 되는 경우:

컨텍스트 보존 — 탐색 및 구현 작업을 메인 대화 밖에서 수행
제약 조건 적용 — 서브에이전트가 사용할 수 있는 도구를 제한
설정 재사용 — 사용자 수준 서브에이전트로 프로젝트 간 재사용
동작 특화 — 특정 도메인에 집중된 시스템 프롬프트로 동작 특화
비용 제어 — Haiku와 같은 빠르고 저렴한 모델로 작업 라우팅

Claude는 각 서브에이전트의 설명을 사용하여 작업 위임 시점을 결정합니다. 서브에이전트를 생성할 때 Claude가 언제 사용해야 하는지 알 수 있도록 명확한 설명을 작성하세요.

Claude Code에는 Explore, Plan, general-purpose와 같은 내장 서브에이전트가 포함되어 있습니다. 특정 작업을 처리하기 위한 커스텀 서브에이전트도 생성할 수 있습니다. 이 페이지에서는 내장 서브에이전트, 직접 만드는 방법, 전체 설정 옵션, 서브에이전트 활용 패턴, 예제 서브에이전트를 다룹니다.

내장 서브에이전트

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

Explore

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

모델: Haiku (빠르고 낮은 지연 시간)
도구: 읽기 전용 도구 (Write 및 Edit 도구 접근 거부)
용도: 파일 검색, 코드 검색, 코드베이스 탐색

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

Explore를 호출할 때 Claude는 철저함 수준을 지정합니다: 대상 조회에는 quick, 균형 잡힌 탐색에는 medium, 포괄적인 분석에는 very thorough를 사용합니다.

Plan

플랜 모드에서 계획을 제시하기 전에 컨텍스트를 수집하는 리서치 에이전트입니다.

모델: 메인 대화에서 상속
도구: 읽기 전용 도구 (Write 및 Edit 도구 접근 거부)
용도: 계획 수립을 위한 코드베이스 리서치

플랜 모드에서 Claude가 코드베이스를 이해해야 할 때 Plan 서브에이전트에 리서치를 위임합니다. 이는 무한 중첩(서브에이전트는 다른 서브에이전트를 생성할 수 없음)을 방지하면서도 필요한 컨텍스트를 수집합니다.

General-purpose

탐색과 실행 모두 필요한 복잡한 다단계 작업을 위한 범용 에이전트입니다.

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

Claude는 탐색과 수정 모두 필요하거나, 결과 해석에 복잡한 추론이 필요하거나, 여러 의존적 단계가 있는 작업에 general-purpose를 사용합니다.

Other

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

에이전트	모델	Claude가 사용하는 시점
Bash	상속	별도 컨텍스트에서 터미널 명령 실행
statusline-setup	Sonnet	`/statusline`을 실행하여 상태 표시줄을 구성할 때
Claude Code Guide	Haiku	Claude Code 기능에 대해 질문할 때

이러한 내장 서브에이전트 외에도 커스텀 프롬프트, 도구 제한, 권한 모드, 훅, 스킬을 가진 자체 서브에이전트를 생성할 수 있습니다. 다음 섹션에서 시작 방법과 서브에이전트 커스터마이징을 다룹니다.

빠른 시작: 첫 번째 서브에이전트 생성

서브에이전트는 YAML 프론트매터가 포함된 Markdown 파일로 정의됩니다. 수동으로 생성하거나 /agents 명령을 사용할 수 있습니다.

이 안내에서는 /agent 명령을 사용하여 사용자 수준 서브에이전트를 생성하는 과정을 설명합니다. 이 서브에이전트는 코드를 검토하고 코드베이스 개선 사항을 제안합니다.

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

Claude Code에서 다음을 실행합니다:

/agents

Step 2: 새 사용자 수준 에이전트 생성

Create new agent를 선택한 후 User-level을 선택합니다. 이렇게 하면 서브에이전트가 ~/.claude/agents/에 저장되어 모든 프로젝트에서 사용할 수 있습니다.

Step 3: 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가 시스템 프롬프트와 설정을 생성합니다. 커스터마이징하려면 e를 눌러 에디터에서 엽니다.

Step 4: 도구 선택

읽기 전용 리뷰어의 경우 Read-only tools만 선택합니다. 모든 도구를 선택한 상태로 유지하면 서브에이전트는 메인 대화에서 사용 가능한 모든 도구를 상속받습니다.

Step 5: 모델 선택

서브에이전트가 사용할 모델을 선택합니다. 이 예제 에이전트의 경우 코드 패턴 분석에 성능과 속도의 균형이 잡힌 Sonnet을 선택합니다.

Step 6: 색상 선택

서브에이전트의 배경색을 선택합니다. 이를 통해 UI에서 어떤 서브에이전트가 실행 중인지 식별할 수 있습니다.

Step 7: 저장 및 사용해보기

서브에이전트를 저장합니다. 즉시 사용 가능합니다(재시작 불필요). 사용해 보세요:

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

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

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

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

서브에이전트 설정

/agents 명령 사용

/agents 명령은 서브에이전트를 관리하기 위한 대화형 인터페이스를 제공합니다. /agents를 실행하면 다음을 수행할 수 있습니다:

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

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

대화형 세션을 시작하지 않고 명령줄에서 설정된 모든 서브에이전트를 나열하려면 claude agents를 실행합니다. 이 명령은 소스별로 그룹화된 에이전트를 표시하고 우선순위가 높은 정의에 의해 오버라이드된 항목을 표시합니다.

서브에이전트 범위 선택

서브에이전트는 YAML 프론트매터가 포함된 Markdown 파일입니다. 범위에 따라 다른 위치에 저장합니다. 동일한 이름을 가진 서브에이전트가 여러 개 있으면 우선순위가 높은 위치가 우선합니다.

위치	범위	우선순위	생성 방법
`--agents` CLI 플래그	현재 세션	1 (최고)	Claude Code 실행 시 JSON 전달
`.claude/agents/`	현재 프로젝트	2	대화형 또는 수동
`~/.claude/agents/`	모든 프로젝트	3	대화형 또는 수동
플러그인의 `agents/` 디렉토리	플러그인이 활성화된 곳	4 (최저)	플러그인과 함께 설치

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

사용자 서브에이전트 (~/.claude/agents/)는 모든 프로젝트에서 사용 가능한 개인 서브에이전트입니다.

CLI 정의 서브에이전트는 Claude Code 실행 시 JSON으로 전달됩니다. 해당 세션에서만 존재하며 디스크에 저장되지 않으므로 빠른 테스트나 자동화 스크립트에 유용합니다:

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

--agents 플래그는 파일 기반 서브에이전트와 동일한 프론트매터 필드를 가진 JSON을 받습니다: description, prompt, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, skills, memory. 시스템 프롬프트에는 prompt를 사용하며, 이는 파일 기반 서브에이전트의 마크다운 본문에 해당합니다. 전체 JSON 형식은 CLI 레퍼런스를 참조하세요.

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

서브에이전트 파일 작성

서브에이전트 파일은 설정을 위한 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 시스템 프롬프트는 받지 않습니다.

지원되는 프론트매터 필드

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

필드	필수	설명
`name`	예	소문자와 하이픈을 사용한 고유 식별자
`description`	예	Claude가 이 서브에이전트에 위임해야 하는 시점
`tools`	아니오	서브에이전트가 사용할 수 있는 도구. 생략 시 모든 도구 상속
`disallowedTools`	아니오	거부할 도구, 상속 또는 지정된 목록에서 제거
`model`	아니오	사용할 모델: `sonnet`, `opus`, `haiku`, 또는 `inherit`. 기본값은 `inherit`
`permissionMode`	아니오	권한 모드: `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, 또는 `plan`
`maxTurns`	아니오	서브에이전트가 중지되기 전 최대 에이전틱 턴 수
`skills`	아니오	시작 시 서브에이전트의 컨텍스트에 로드할 스킬. 전체 스킬 내용이 주입되며, 호출 가능하게만 만드는 것이 아닙니다. 서브에이전트는 부모 대화의 스킬을 상속하지 않습니다
`mcpServers`	아니오	이 서브에이전트에서 사용 가능한 MCP 서버. 각 항목은 이미 설정된 서버를 참조하는 서버 이름(예: `"slack"`) 또는 서버 이름을 키로 하고 전체 MCP 서버 설정을 값으로 하는 인라인 정의입니다
`hooks`	아니오	이 서브에이전트에 범위가 지정된 라이프사이클 훅
`memory`	아니오	영구 메모리 범위: `user`, `project`, 또는 `local`. 세션 간 학습 활성화
`background`	아니오	`true`로 설정하면 이 서브에이전트를 항상 백그라운드 작업으로 실행. 기본값: `false`
`isolation`	아니오	`worktree`로 설정하면 서브에이전트를 임시 git worktree에서 실행하여 리포지토리의 격리된 복사본을 제공. 서브에이전트가 변경하지 않으면 worktree는 자동으로 정리됩니다

모델 선택

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

모델 별칭: 사용 가능한 별칭 중 하나를 사용: sonnet, opus, 또는 haiku
inherit: 메인 대화와 동일한 모델 사용
생략 시: 지정하지 않으면 기본값은 inherit (메인 대화와 동일한 모델 사용)

서브에이전트 기능 제어

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

사용 가능한 도구

서브에이전트는 Claude Code의 내부 도구 중 어떤 것이든 사용할 수 있습니다. 기본적으로 서브에이전트는 MCP 도구를 포함하여 메인 대화의 모든 도구를 상속받습니다.

도구를 제한하려면 tools 필드(허용 목록) 또는 disallowedTools 필드(거부 목록)를 사용합니다:

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

생성 가능한 서브에이전트 제한

에이전트가 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가 완전히 생략되면 에이전트는 서브에이전트를 생성할 수 없습니다. 이 제한은 claude --agent로 메인 스레드로 실행되는 에이전트에만 적용됩니다. 서브에이전트는 다른 서브에이전트를 생성할 수 없으므로 서브에이전트 정의에서 Agent(agent_type)는 효과가 없습니다.

권한 모드

permissionMode 필드는 서브에이전트가 권한 프롬프트를 처리하는 방법을 제어합니다. 서브에이전트는 메인 대화의 권한 컨텍스트를 상속받지만 모드를 오버라이드할 수 있습니다.

모드	동작
`default`	프롬프트를 통한 표준 권한 확인
`acceptEdits`	파일 편집 자동 승인
`dontAsk`	권한 프롬프트 자동 거부 (명시적으로 허용된 도구는 계속 작동)
`bypassPermissions`	모든 권한 검사 건너뛰기
`plan`	플랜 모드 (읽기 전용 탐색)

주의:

bypassPermissions는 주의해서 사용하세요. 모든 권한 검사를 건너뛰어 서브에이전트가 승인 없이 모든 작업을 실행할 수 있습니다.

부모가 bypassPermissions를 사용하면 이것이 우선하며 오버라이드할 수 없습니다.

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

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.

각 스킬의 전체 내용이 서브에이전트의 컨텍스트에 주입되며, 단순히 호출 가능하게만 만드는 것이 아닙니다. 서브에이전트는 부모 대화의 스킬을 상속하지 않으므로 명시적으로 나열해야 합니다.

참고:

이것은 서브에이전트에서 스킬 실행의 반대 개념입니다. 서브에이전트의 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.

메모리가 적용되어야 하는 범위에 따라 스코프를 선택합니다:

스코프	위치	사용 시기
`user`	`~/.claude/agent-memory/<name-of-agent>/`	서브에이전트가 모든 프로젝트에서 학습 내용을 기억해야 할 때
`project`	`.claude/agent-memory/<name-of-agent>/`	서브에이전트의 지식이 프로젝트 특화이고 버전 관리를 통해 공유 가능할 때
`local`	`.claude/agent-memory-local/<name-of-agent>/`	서브에이전트의 지식이 프로젝트 특화이지만 버전 관리에 체크인하지 않아야 할 때

메모리가 활성화되면:

서브에이전트의 시스템 프롬프트에 메모리 디렉토리 읽기 및 쓰기 지침이 포함됩니다.
서브에이전트의 시스템 프롬프트에 메모리 디렉토리의 MEMORY.md 첫 200줄도 포함되며, 200줄을 초과하면 MEMORY.md를 정리하라는 지침이 포함됩니다.
Read, Write, Edit 도구가 자동으로 활성화되어 서브에이전트가 메모리 파일을 관리할 수 있습니다.

영구 메모리 팁

user가 권장 기본 스코프입니다. 서브에이전트의 지식이 특정 코드베이스에만 관련될 때 project 또는 local을 사용하세요.
작업 시작 전에 서브에이전트에게 메모리를 확인하도록 요청하세요: "이 PR을 검토하고, 이전에 본 패턴이 있는지 메모리를 확인해."
작업 완료 후 서브에이전트에게 메모리를 업데이트하도록 요청하세요: "완료했으니, 학습한 내용을 메모리에 저장해." 시간이 지남에 따라 서브에이전트를 더 효과적으로 만드는 지식 베이스가 구축됩니다.

서브에이전트의 마크다운 파일에 메모리 지침을 직접 포함하여 자체적으로 지식 베이스를 유지하도록 합니다:

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

전체 입력 스키마는 훅 입력을, 종료 코드가 동작에 미치는 영향은 종료 코드를 참조하세요.

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

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

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

이 방법은 내장 및 커스텀 서브에이전트 모두에 적용됩니다. --disallowedTools CLI 플래그도 사용할 수 있습니다:

claude --disallowedTools "Agent(Explore)"

권한 규칙에 대한 자세한 내용은 권한 문서를 참조하세요.

서브에이전트 훅 정의

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

서브에이전트의 프론트매터에서: 해당 서브에이전트가 활성 상태일 때만 실행되는 훅 정의
settings.json에서: 서브에이전트 시작 또는 중지 시 메인 세션에서 실행되는 훅 정의

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

서브에이전트의 마크다운 파일에 훅을 직접 정의합니다. 이 훅은 해당 특정 서브에이전트가 활성 상태일 때만 실행되며 완료 시 정리됩니다.

모든 훅 이벤트가 지원됩니다. 서브에이전트에서 가장 일반적인 이벤트는 다음과 같습니다:

이벤트	매처 입력	발생 시점
`PreToolUse`	도구 이름	서브에이전트가 도구를 사용하기 전
`PostToolUse`	도구 이름	서브에이전트가 도구를 사용한 후
`Stop`	(없음)	서브에이전트 완료 시 (런타임에 `SubagentStop`으로 변환)

이 예제는 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에 설정합니다.

이벤트	매처 입력	발생 시점
`SubagentStart`	에이전트 타입명	서브에이전트가 실행을 시작할 때
`SubagentStop`	에이전트 타입명	서브에이전트가 완료될 때

두 이벤트 모두 이름으로 특정 에이전트 유형을 대상으로 하는 매처를 지원합니다. 이 예제는 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" }
        ]
      }
    ]
  }
}

전체 훅 설정 형식은 훅을 참조하세요.

서브에이전트 활용

자동 위임 이해

Claude는 요청의 작업 설명, 서브에이전트 설정의 description 필드, 현재 컨텍스트를 기반으로 자동으로 작업을 위임합니다. 사전 위임을 장려하려면 서브에이전트의 description 필드에 "use proactively"와 같은 문구를 포함하세요.

특정 서브에이전트를 명시적으로 요청할 수도 있습니다:

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

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

서브에이전트는 포그라운드(블로킹) 또는 백그라운드(동시)로 실행할 수 있습니다:

포그라운드 서브에이전트는 완료될 때까지 메인 대화를 블로킹합니다. 권한 프롬프트와 명확화 질문(AskUserQuestion 등)은 사용자에게 전달됩니다.
백그라운드 서브에이전트는 사용자가 계속 작업하는 동안 동시에 실행됩니다. 실행 전에 Claude Code는 서브에이전트에 필요한 도구 권한을 미리 요청하여 필요한 승인을 사전에 확보합니다. 실행 중에는 서브에이전트가 이러한 권한을 상속받고 사전 승인되지 않은 것은 자동 거부합니다. 백그라운드 서브에이전트가 명확화 질문을 해야 하는 경우 해당 도구 호출은 실패하지만 서브에이전트는 계속 진행합니다.

백그라운드 서브에이전트가 권한 부족으로 실패하면 포그라운드에서 재개하여 대화형 프롬프트로 재시도할 수 있습니다.

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

Claude에게 "run this in the background"라고 요청
Ctrl+B를 눌러 실행 중인 작업을 백그라운드로 전환

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

일반적인 패턴

대량 출력 작업 격리

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

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가 결과를 종합합니다. 리서치 경로가 서로 의존하지 않을 때 가장 효과적입니다.

주의:

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

지속적인 병렬 처리가 필요하거나 컨텍스트 윈도우를 초과하는 작업에는 에이전트 팀이 각 워커에게 독립적인 컨텍스트를 제공합니다.

서브에이전트 체이닝

다단계 워크플로우에서는 Claude에게 서브에이전트를 순차적으로 사용하도록 요청합니다. 각 서브에이전트는 작업을 완료하고 결과를 Claude에 반환하며, Claude는 관련 컨텍스트를 다음 서브에이전트에 전달합니다.

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

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

메인 대화를 사용해야 하는 경우:

작업에 빈번한 왕복이나 반복적인 개선이 필요한 경우
여러 단계가 상당한 컨텍스트를 공유하는 경우 (계획 → 구현 → 테스트)
빠르고 대상이 명확한 변경을 하는 경우
지연 시간이 중요한 경우. 서브에이전트는 새로 시작하며 컨텍스트 수집에 시간이 필요할 수 있음

서브에이전트를 사용해야 하는 경우:

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

메인 대화 컨텍스트에서 실행되는 재사용 가능한 프롬프트나 워크플로우가 필요한 경우 격리된 서브에이전트 컨텍스트 대신 스킬을 고려하세요.

참고:

서브에이전트는 다른 서브에이전트를 생성할 수 없습니다. 워크플로우에 중첩된 위임이 필요한 경우 스킬을 사용하거나 메인 대화에서 서브에이전트를 체이닝하세요.

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

서브에이전트 재개

각 서브에이전트 호출은 새로운 컨텍스트로 새 인스턴스를 생성합니다. 처음부터 다시 시작하는 대신 기존 서브에이전트의 작업을 계속하려면 Claude에게 재개를 요청하세요.

재개된 서브에이전트는 이전 도구 호출, 결과, 추론을 포함한 전체 대화 기록을 유지합니다. 서브에이전트는 새로 시작하는 대신 중단된 곳에서 정확히 다시 시작합니다.

서브에이전트가 완료되면 Claude는 해당 에이전트 ID를 받습니다. 서브에이전트를 재개하려면 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]

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

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

메인 대화 압축: 메인 대화가 압축될 때 서브에이전트 트랜스크립트는 영향받지 않습니다. 별도 파일에 저장됩니다.
세션 지속성: 서브에이전트 트랜스크립트는 세션 내에서 유지됩니다. 동일한 세션을 재개하여 Claude Code 재시작 후에도 서브에이전트를 재개할 수 있습니다.
자동 정리: 트랜스크립트는 cleanupPeriodDays 설정(기본값: 30일)에 따라 정리됩니다.

자동 압축

서브에이전트는 메인 대화와 동일한 로직으로 자동 압축을 지원합니다. 기본적으로 자동 압축은 약 95% 용량에서 트리거됩니다. 더 일찍 압축을 트리거하려면 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE를 더 낮은 퍼센트(예: 50)로 설정하세요. 자세한 내용은 환경 변수를 참조하세요.

압축 이벤트는 서브에이전트 트랜스크립트 파일에 기록됩니다:

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

preTokens 값은 압축이 발생하기 전에 사용된 토큰 수를 나타냅니다.

예제 서브에이전트

이 예제들은 서브에이전트를 구축하기 위한 효과적인 패턴을 보여줍니다. 시작점으로 사용하거나 Claude로 커스터마이즈된 버전을 생성하세요.

팁:

모범 사례:

집중된 서브에이전트 설계: 각 서브에이전트는 하나의 특정 작업에 특화되어야 합니다

상세한 설명 작성: Claude가 설명을 사용하여 위임 시점을 결정합니다

도구 접근 제한: 보안과 집중을 위해 필요한 권한만 부여하세요

버전 관리에 체크인: 프로젝트 서브에이전트를 팀과 공유하세요

코드 리뷰어

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

디버거

분석과 수정 모두 가능한 서브에이전트입니다. 코드 리뷰어와 달리 버그 수정에는 코드 수정이 필요하므로 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.

데이터 사이언티스트

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

데이터베이스 쿼리 유효성 검사기

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

스크립트를 실행 가능하게 만듭니다:

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

훅은 stdin을 통해 tool_input.command에 Bash 명령이 포함된 JSON을 받습니다. 종료 코드 2는 작업을 차단하고 오류 메시지를 Claude에 피드백합니다. 종료 코드에 대한 자세한 내용은 훅을, 전체 입력 스키마는 훅 입력을 참조하세요.

다음 단계

서브에이전트를 이해했으므로 다음 관련 기능을 살펴보세요:

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

커스텀 서브에이전트 생성

Claude Code에서 특화된 AI 서브에이전트를 생성하고 사용하여 작업별 워크플로우와 향상된 컨텍스트 관리를 구현합니다.

참고:

여러 에이전트가 병렬로 작업하고 서로 통신해야 하는 경우, 에이전트 팀을 참조하세요. 서브에이전트는 단일 세션 내에서 작동하고, 에이전트 팀은 별도의 세션 간에 조율됩니다.

서브에이전트가 도움이 되는 경우:

컨텍스트 보존 — 탐색 및 구현 작업을 메인 대화 밖에서 수행
제약 조건 적용 — 서브에이전트가 사용할 수 있는 도구를 제한
설정 재사용 — 사용자 수준 서브에이전트로 프로젝트 간 재사용
동작 특화 — 특정 도메인에 집중된 시스템 프롬프트로 동작 특화
비용 제어 — Haiku와 같은 빠르고 저렴한 모델로 작업 라우팅

내장 서브에이전트

Explore

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

모델: Haiku (빠르고 낮은 지연 시간)
도구: 읽기 전용 도구 (Write 및 Edit 도구 접근 거부)
용도: 파일 검색, 코드 검색, 코드베이스 탐색

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

Plan

플랜 모드에서 계획을 제시하기 전에 컨텍스트를 수집하는 리서치 에이전트입니다.

모델: 메인 대화에서 상속
도구: 읽기 전용 도구 (Write 및 Edit 도구 접근 거부)
용도: 계획 수립을 위한 코드베이스 리서치

General-purpose

탐색과 실행 모두 필요한 복잡한 다단계 작업을 위한 범용 에이전트입니다.

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

Claude는 탐색과 수정 모두 필요하거나, 결과 해석에 복잡한 추론이 필요하거나, 여러 의존적 단계가 있는 작업에 general-purpose를 사용합니다.

Other

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

에이전트	모델	Claude가 사용하는 시점
Bash	상속	별도 컨텍스트에서 터미널 명령 실행
statusline-setup	Sonnet	`/statusline`을 실행하여 상태 표시줄을 구성할 때
Claude Code Guide	Haiku	Claude Code 기능에 대해 질문할 때

빠른 시작: 첫 번째 서브에이전트 생성

서브에이전트는 YAML 프론트매터가 포함된 Markdown 파일로 정의됩니다. 수동으로 생성하거나 /agents 명령을 사용할 수 있습니다.

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

Claude Code에서 다음을 실행합니다:

/agents

Step 2: 새 사용자 수준 에이전트 생성

Step 3: 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가 시스템 프롬프트와 설정을 생성합니다. 커스터마이징하려면 e를 눌러 에디터에서 엽니다.

Step 4: 도구 선택

Step 5: 모델 선택

서브에이전트가 사용할 모델을 선택합니다. 이 예제 에이전트의 경우 코드 패턴 분석에 성능과 속도의 균형이 잡힌 Sonnet을 선택합니다.

Step 6: 색상 선택

서브에이전트의 배경색을 선택합니다. 이를 통해 UI에서 어떤 서브에이전트가 실행 중인지 식별할 수 있습니다.

Step 7: 저장 및 사용해보기

서브에이전트를 저장합니다. 즉시 사용 가능합니다(재시작 불필요). 사용해 보세요:

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

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

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

서브에이전트 설정

/agents 명령 사용

/agents 명령은 서브에이전트를 관리하기 위한 대화형 인터페이스를 제공합니다. /agents를 실행하면 다음을 수행할 수 있습니다:

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

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

서브에이전트 범위 선택

위치	범위	우선순위	생성 방법
`--agents` CLI 플래그	현재 세션	1 (최고)	Claude Code 실행 시 JSON 전달
`.claude/agents/`	현재 프로젝트	2	대화형 또는 수동
`~/.claude/agents/`	모든 프로젝트	3	대화형 또는 수동
플러그인의 `agents/` 디렉토리	플러그인이 활성화된 곳	4 (최저)	플러그인과 함께 설치

사용자 서브에이전트 (~/.claude/agents/)는 모든 프로젝트에서 사용 가능한 개인 서브에이전트입니다.

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

서브에이전트 파일 작성

서브에이전트 파일은 설정을 위한 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.

지원되는 프론트매터 필드

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

필드	필수	설명
`name`	예	소문자와 하이픈을 사용한 고유 식별자
`description`	예	Claude가 이 서브에이전트에 위임해야 하는 시점
`tools`	아니오	서브에이전트가 사용할 수 있는 도구. 생략 시 모든 도구 상속
`disallowedTools`	아니오	거부할 도구, 상속 또는 지정된 목록에서 제거
`model`	아니오	사용할 모델: `sonnet`, `opus`, `haiku`, 또는 `inherit`. 기본값은 `inherit`
`permissionMode`	아니오	권한 모드: `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, 또는 `plan`
`maxTurns`	아니오	서브에이전트가 중지되기 전 최대 에이전틱 턴 수
`skills`	아니오	시작 시 서브에이전트의 컨텍스트에 로드할 스킬. 전체 스킬 내용이 주입되며, 호출 가능하게만 만드는 것이 아닙니다. 서브에이전트는 부모 대화의 스킬을 상속하지 않습니다
`mcpServers`	아니오	이 서브에이전트에서 사용 가능한 MCP 서버. 각 항목은 이미 설정된 서버를 참조하는 서버 이름(예: `"slack"`) 또는 서버 이름을 키로 하고 전체 MCP 서버 설정을 값으로 하는 인라인 정의입니다
`hooks`	아니오	이 서브에이전트에 범위가 지정된 라이프사이클 훅
`memory`	아니오	영구 메모리 범위: `user`, `project`, 또는 `local`. 세션 간 학습 활성화
`background`	아니오	`true`로 설정하면 이 서브에이전트를 항상 백그라운드 작업으로 실행. 기본값: `false`
`isolation`	아니오	`worktree`로 설정하면 서브에이전트를 임시 git worktree에서 실행하여 리포지토리의 격리된 복사본을 제공. 서브에이전트가 변경하지 않으면 worktree는 자동으로 정리됩니다

모델 선택

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

모델 별칭: 사용 가능한 별칭 중 하나를 사용: sonnet, opus, 또는 haiku
inherit: 메인 대화와 동일한 모델 사용
생략 시: 지정하지 않으면 기본값은 inherit (메인 대화와 동일한 모델 사용)

서브에이전트 기능 제어

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

사용 가능한 도구

도구를 제한하려면 tools 필드(허용 목록) 또는 disallowedTools 필드(거부 목록)를 사용합니다:

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

생성 가능한 서브에이전트 제한

참고:

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

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

괄호 없이 Agent를 사용하면 제한 없이 모든 서브에이전트를 생성할 수 있습니다:

tools: Agent, Read, Bash

권한 모드

모드	동작
`default`	프롬프트를 통한 표준 권한 확인
`acceptEdits`	파일 편집 자동 승인
`dontAsk`	권한 프롬프트 자동 거부 (명시적으로 허용된 도구는 계속 작동)
`bypassPermissions`	모든 권한 검사 건너뛰기
`plan`	플랜 모드 (읽기 전용 탐색)

주의:

bypassPermissions는 주의해서 사용하세요. 모든 권한 검사를 건너뛰어 서브에이전트가 승인 없이 모든 작업을 실행할 수 있습니다.

부모가 bypassPermissions를 사용하면 이것이 우선하며 오버라이드할 수 없습니다.

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

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

참고:

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

영구 메모리 활성화

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

메모리가 적용되어야 하는 범위에 따라 스코프를 선택합니다:

스코프	위치	사용 시기
`user`	`~/.claude/agent-memory/<name-of-agent>/`	서브에이전트가 모든 프로젝트에서 학습 내용을 기억해야 할 때
`project`	`.claude/agent-memory/<name-of-agent>/`	서브에이전트의 지식이 프로젝트 특화이고 버전 관리를 통해 공유 가능할 때
`local`	`.claude/agent-memory-local/<name-of-agent>/`	서브에이전트의 지식이 프로젝트 특화이지만 버전 관리에 체크인하지 않아야 할 때

메모리가 활성화되면:

서브에이전트의 시스템 프롬프트에 메모리 디렉토리 읽기 및 쓰기 지침이 포함됩니다.
서브에이전트의 시스템 프롬프트에 메모리 디렉토리의 MEMORY.md 첫 200줄도 포함되며, 200줄을 초과하면 MEMORY.md를 정리하라는 지침이 포함됩니다.
Read, Write, Edit 도구가 자동으로 활성화되어 서브에이전트가 메모리 파일을 관리할 수 있습니다.

영구 메모리 팁

user가 권장 기본 스코프입니다. 서브에이전트의 지식이 특정 코드베이스에만 관련될 때 project 또는 local을 사용하세요.
작업 시작 전에 서브에이전트에게 메모리를 확인하도록 요청하세요: "이 PR을 검토하고, 이전에 본 패턴이 있는지 메모리를 확인해."
작업 완료 후 서브에이전트에게 메모리를 업데이트하도록 요청하세요: "완료했으니, 학습한 내용을 메모리에 저장해." 시간이 지남에 따라 서브에이전트를 더 효과적으로 만드는 지식 베이스가 구축됩니다.

서브에이전트의 마크다운 파일에 메모리 지침을 직접 포함하여 자체적으로 지식 베이스를 유지하도록 합니다:

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

전체 입력 스키마는 훅 입력을, 종료 코드가 동작에 미치는 영향은 종료 코드를 참조하세요.

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

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

이 방법은 내장 및 커스텀 서브에이전트 모두에 적용됩니다. --disallowedTools CLI 플래그도 사용할 수 있습니다:

claude --disallowedTools "Agent(Explore)"

권한 규칙에 대한 자세한 내용은 권한 문서를 참조하세요.

서브에이전트 훅 정의

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

서브에이전트의 프론트매터에서: 해당 서브에이전트가 활성 상태일 때만 실행되는 훅 정의
settings.json에서: 서브에이전트 시작 또는 중지 시 메인 세션에서 실행되는 훅 정의

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

서브에이전트의 마크다운 파일에 훅을 직접 정의합니다. 이 훅은 해당 특정 서브에이전트가 활성 상태일 때만 실행되며 완료 시 정리됩니다.

모든 훅 이벤트가 지원됩니다. 서브에이전트에서 가장 일반적인 이벤트는 다음과 같습니다:

이벤트	매처 입력	발생 시점
`PreToolUse`	도구 이름	서브에이전트가 도구를 사용하기 전
`PostToolUse`	도구 이름	서브에이전트가 도구를 사용한 후
`Stop`	(없음)	서브에이전트 완료 시 (런타임에 `SubagentStop`으로 변환)

이 예제는 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에 설정합니다.

이벤트	매처 입력	발생 시점
`SubagentStart`	에이전트 타입명	서브에이전트가 실행을 시작할 때
`SubagentStop`	에이전트 타입명	서브에이전트가 완료될 때

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

전체 훅 설정 형식은 훅을 참조하세요.

서브에이전트 활용

자동 위임 이해

특정 서브에이전트를 명시적으로 요청할 수도 있습니다:

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

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

서브에이전트는 포그라운드(블로킹) 또는 백그라운드(동시)로 실행할 수 있습니다:

포그라운드 서브에이전트는 완료될 때까지 메인 대화를 블로킹합니다. 권한 프롬프트와 명확화 질문(AskUserQuestion 등)은 사용자에게 전달됩니다.
백그라운드 서브에이전트는 사용자가 계속 작업하는 동안 동시에 실행됩니다. 실행 전에 Claude Code는 서브에이전트에 필요한 도구 권한을 미리 요청하여 필요한 승인을 사전에 확보합니다. 실행 중에는 서브에이전트가 이러한 권한을 상속받고 사전 승인되지 않은 것은 자동 거부합니다. 백그라운드 서브에이전트가 명확화 질문을 해야 하는 경우 해당 도구 호출은 실패하지만 서브에이전트는 계속 진행합니다.

백그라운드 서브에이전트가 권한 부족으로 실패하면 포그라운드에서 재개하여 대화형 프롬프트로 재시도할 수 있습니다.

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

Claude에게 "run this in the background"라고 요청
Ctrl+B를 눌러 실행 중인 작업을 백그라운드로 전환

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

일반적인 패턴

대량 출력 작업 격리

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가 결과를 종합합니다. 리서치 경로가 서로 의존하지 않을 때 가장 효과적입니다.

주의:

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

지속적인 병렬 처리가 필요하거나 컨텍스트 윈도우를 초과하는 작업에는 에이전트 팀이 각 워커에게 독립적인 컨텍스트를 제공합니다.

서브에이전트 체이닝

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

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

메인 대화를 사용해야 하는 경우:

작업에 빈번한 왕복이나 반복적인 개선이 필요한 경우
여러 단계가 상당한 컨텍스트를 공유하는 경우 (계획 → 구현 → 테스트)
빠르고 대상이 명확한 변경을 하는 경우
지연 시간이 중요한 경우. 서브에이전트는 새로 시작하며 컨텍스트 수집에 시간이 필요할 수 있음

서브에이전트를 사용해야 하는 경우:

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

메인 대화 컨텍스트에서 실행되는 재사용 가능한 프롬프트나 워크플로우가 필요한 경우 격리된 서브에이전트 컨텍스트 대신 스킬을 고려하세요.

참고:

서브에이전트는 다른 서브에이전트를 생성할 수 없습니다. 워크플로우에 중첩된 위임이 필요한 경우 스킬을 사용하거나 메인 대화에서 서브에이전트를 체이닝하세요.

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

서브에이전트 재개

서브에이전트가 완료되면 Claude는 해당 에이전트 ID를 받습니다. 서브에이전트를 재개하려면 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 재시작 후에도 서브에이전트를 재개할 수 있습니다.
자동 정리: 트랜스크립트는 cleanupPeriodDays 설정(기본값: 30일)에 따라 정리됩니다.

자동 압축

압축 이벤트는 서브에이전트 트랜스크립트 파일에 기록됩니다:

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

preTokens 값은 압축이 발생하기 전에 사용된 토큰 수를 나타냅니다.

예제 서브에이전트

이 예제들은 서브에이전트를 구축하기 위한 효과적인 패턴을 보여줍니다. 시작점으로 사용하거나 Claude로 커스터마이즈된 버전을 생성하세요.

팁:

모범 사례:

집중된 서브에이전트 설계: 각 서브에이전트는 하나의 특정 작업에 특화되어야 합니다

상세한 설명 작성: Claude가 설명을 사용하여 위임 시점을 결정합니다

도구 접근 제한: 보안과 집중을 위해 필요한 권한만 부여하세요

버전 관리에 체크인: 프로젝트 서브에이전트를 팀과 공유하세요

코드 리뷰어

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

프로젝트 어디에나 유효성 검사 스크립트를 생성합니다. 경로는 훅 설정의 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

스크립트를 실행 가능하게 만듭니다:

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

다음 단계

서브에이전트를 이해했으므로 다음 관련 기능을 살펴보세요:

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

6. 커스텀 서브에이전트 생성

커스텀 서브에이전트 생성

내장 서브에이전트

Explore

Plan

General-purpose

Other

빠른 시작: 첫 번째 서브에이전트 생성

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

Step 2: 새 사용자 수준 에이전트 생성

Step 3: Claude로 생성

Step 4: 도구 선택

Step 5: 모델 선택

Step 6: 색상 선택

Step 7: 저장 및 사용해보기

서브에이전트 설정

/agents 명령 사용

서브에이전트 범위 선택

서브에이전트 파일 작성

지원되는 프론트매터 필드

모델 선택

서브에이전트 기능 제어

사용 가능한 도구

생성 가능한 서브에이전트 제한

권한 모드

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

영구 메모리 활성화

영구 메모리 팁

훅을 통한 조건부 규칙

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

서브에이전트 훅 정의

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

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

서브에이전트 활용

자동 위임 이해

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

일반적인 패턴

대량 출력 작업 격리

병렬 리서치 실행

서브에이전트 체이닝

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

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

서브에이전트 재개

자동 압축

예제 서브에이전트

코드 리뷰어

디버거

데이터 사이언티스트

데이터베이스 쿼리 유효성 검사기

다음 단계

6. 커스텀 서브에이전트 생성

커스텀 서브에이전트 생성

내장 서브에이전트

Explore

Plan

General-purpose

Other

빠른 시작: 첫 번째 서브에이전트 생성

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

Step 2: 새 사용자 수준 에이전트 생성

Step 3: Claude로 생성

Step 4: 도구 선택

Step 5: 모델 선택

Step 6: 색상 선택

Step 7: 저장 및 사용해보기

서브에이전트 설정

/agents 명령 사용

서브에이전트 범위 선택

서브에이전트 파일 작성

지원되는 프론트매터 필드

모델 선택

서브에이전트 기능 제어

사용 가능한 도구

생성 가능한 서브에이전트 제한

권한 모드

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

영구 메모리 활성화

영구 메모리 팁

훅을 통한 조건부 규칙

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