Claude에게 전문 팀원을 만들어주는 방법,
내장 에이전트부터 나만의 커스텀 에이전트까지How to create specialist team members for Claude,
from built-in agents to your own custom agents
한 줄 요약: Claude가 특정 작업을 처리하는 전문 AI 어시스턴트에게 일을 위임하는 것입니다.One-line summary: Claude delegates work to a specialized AI assistant that handles specific tasks.
서브에이전트는 자체 컨텍스트 윈도우에서 실행됩니다. 사용자 정의 시스템 프롬프트, 특정 도구 접근 권한, 독립적인 권한을 가집니다.
👨💼 메인 Claude = 팀장 → 작업 파악 및 적절한 에이전트에게 위임 결정
🧑💻 서브에이전트 = 전문 팀원 → 자체 컨텍스트에서 독립적으로 처리 후 결과 반환
Claude는 서브에이전트의 description 필드를 기반으로 어떤 에이전트에게 위임할지 자동으로 결정합니다.
Sub-agents run in their own context window. They have custom system prompts, specific tool access permissions, and independent permissions.
👨💼 Main Claude = Team Leader → Understands tasks and decides delegation to appropriate agents
🧑💻 Sub-agent = Specialist team member → Processes independently in its own context and returns results
Claude automatically decides which agent to delegate to based on the sub-agent's description field.
탐색·구현을 주 대화에서 분리합니다. 각 에이전트는 독립적인 컨텍스트 윈도우를 가져 메인 Claude의 컨텍스트를 아낄 수 있습니다.Separates exploration and implementation from the main conversation. Each agent has its own independent context window, conserving main Claude's context.
에이전트가 사용할 수 있는 도구를 제한합니다. 리뷰 에이전트에게 Write 도구를 빼면 코드를 읽기만 하고 수정하지 않습니다.Restricts the tools available to an agent. Removing the Write tool from a review agent makes it read-only, preventing modifications.
Haiku 같은 빠르고 저렴한 모델로 간단한 작업을 라우팅합니다. 탐색 작업에 Haiku를 쓰고 복잡한 작업에 Opus를 쓰는 전략이 가능합니다.Routes simple tasks to fast, cheap models like Haiku. Enables strategies like using Haiku for exploration and Opus for complex tasks.
Claude Code에는 Claude가 적절할 때 자동으로 사용하는 내장 서브에이전트가 포함되어 있습니다. 각각은 부모 대화의 권한을 상속하며 추가 도구 제한이 있습니다.Claude Code includes built-in sub-agents that Claude automatically uses when appropriate. Each inherits permissions from the parent conversation and has additional tool restrictions.
코드베이스 검색 및 분석에 최적화된 빠른 읽기 전용 에이전트입니다. Claude는 변경 없이 코드베이스를 검색하거나 이해해야 할 때 Explore에 위임합니다. 탐색 결과가 주 대화 컨텍스트에서 분리됩니다.A fast, read-only agent optimized for searching and analyzing codebases. Claude delegates to Explore when it needs to search or understand a codebase without making changes. Exploration results are separated from the main conversation context.
Explore를 호출할 때 Claude는 철저함 수준을 지정합니다: 대상 조회의 경우 quick, 균형 잡힌 탐색의 경우 medium, 포괄적인 분석의 경우 very thorough.When invoking Explore, Claude specifies a thoroughness level: quick for targeted lookups, medium for balanced exploration, very thorough for comprehensive analysis.
계획을 제시하기 전에 컨텍스트를 수집하기 위해 Plan Mode 중에 사용되는 연구 에이전트입니다. Plan mode에 있고 Claude가 코드베이스를 이해해야 할 때 연구를 Plan 서브에이전트에 위임합니다.A research agent used during Plan Mode to gather context before presenting a plan. When in Plan mode and Claude needs to understand the codebase, it delegates research to the Plan sub-agent.
무한 중첩을 방지하면서(서브에이전트는 다른 서브에이전트를 생성할 수 없음) 필요한 컨텍스트를 수집합니다.Gathers necessary context while preventing infinite nesting (sub-agents cannot create other sub-agents).
탐색과 작업 모두를 필요로 하는 복잡한 다단계 작업을 위한 유능한 에이전트입니다. Claude는 작업이 탐색과 수정 모두를 필요로 하거나, 결과를 해석하기 위한 복잡한 추론이 필요하거나, 여러 종속 단계가 필요할 때 이 에이전트에 위임합니다.A capable agent for complex multi-step tasks that require both exploration and action. Claude delegates to this agent when the task requires both exploration and modification, needs complex reasoning to interpret results, or involves multiple dependent steps.
Claude Code에는 특정 작업을 위한 추가 도우미 에이전트가 포함되어 있습니다. 이들은 일반적으로 자동으로 호출되므로 직접 사용할 필요가 없습니다.Claude Code includes additional helper agents for specific tasks. They are generally invoked automatically, so you don't need to use them directly.
| 에이전트Agent | 모델Model | Claude가 사용하는 경우When Claude uses it |
|---|---|---|
| Bash | 상속Inherited | 별도의 컨텍스트에서 터미널 명령 실행Running terminal commands in a separate context |
| statusline-setup | Sonnet | /statusline을 실행하여 상태 표시줄을 구성할 때When running /statusline to configure the status bar |
| Claude Code Guide | Haiku | Claude Code 기능에 대한 질문을 할 때When asking questions about Claude Code features |
permissions.deny에 추가하면 됩니다.
예: {"permissions": {"deny": ["Agent(Explore)", "Agent(my-agent)"]}}Disable a specific built-in agent: Add it to permissions.deny.
Example: {"permissions": {"deny": ["Agent(Explore)", "Agent(my-agent)"]}}
서브에이전트는 YAML frontmatter가 있는 마크다운 파일입니다. /agents 명령으로 대화형 생성하거나, 직접 파일을 작성할 수 있습니다.Sub-agents are markdown files with YAML frontmatter. You can create them interactively with the /agents command, or write the file directly.
Claude Code 세션에서 /agents를 실행하면 대화형 에이전트 관리 인터페이스가 열립니다. Create new agent를 선택한 후 User-level 또는 Project-level을 선택합니다.Running /agents in a Claude Code session opens an interactive agent management interface. Select Create new agent, then choose User-level or Project-level.
에이전트 파일의 위치에 따라 적용 범위가 달라집니다. 팀과 공유할 프로젝트 에이전트는 버전 제어에 체크인하세요.The scope varies depending on where the agent file is located. Check project agents to share with your team into version control.
| 위치Location | 범위Scope | 우선순위Priority |
|---|---|---|
--agents CLI 플래그flag |
현재 세션만Current session only | 1 (최고)1 (Highest) |
.claude/agents/ |
현재 프로젝트Current project | 2 |
~/.claude/agents/ |
모든 프로젝트 (개인)All projects (personal) | 3 |
플러그인 agents/ 디렉토리Plugin agents/ directory |
플러그인이 활성화된 위치Where the plugin is active | 4 (최저)4 (Lowest) |
서브에이전트 파일은 YAML frontmatter + 마크다운 시스템 프롬프트로 구성됩니다. 파일명 = 에이전트 이름이 됩니다.A sub-agent file consists of YAML frontmatter + markdown system prompt. The filename becomes the agent name.
저장 즉시 사용 가능합니다 (재시작 불필요). Claude가 description을 기반으로 자동 위임하거나, 직접 요청할 수 있습니다.Available immediately after saving (no restart required). Claude can auto-delegate based on the description, or you can request directly.
서브에이전트의 모든 frontmatter 필드와 고급 기능을 알아봅니다.Learn about all frontmatter fields and advanced features of sub-agents.
| 필드Field | 필수Required | 설명Description |
|---|---|---|
| name | 필수Required | 소문자 문자와 하이픈을 사용하는 고유 식별자Unique identifier using lowercase letters and hyphens |
| description | 필수Required | Claude가 이 에이전트에 위임해야 할 때 (위임 판단 기준)When Claude should delegate to this agent (basis for delegation decisions) |
| tools | 선택Optional | 허용할 도구 목록. 생략하면 모든 도구 상속. Agent(name) 구문으로 생성 가능한 서브에이전트 제한 가능List of allowed tools. If omitted, inherits all tools. Can restrict spawnable sub-agents with Agent(name) syntax |
| disallowedTools | 선택Optional | 차단할 도구 목록 (허용 목록에서 제거)List of tools to block (removed from allowlist) |
| model | 선택Optional | sonnet, opus, haiku, inherit 중 선택. 기본값: inheritChoose from sonnet, opus, haiku, inherit. Default: inherit |
| permissionMode | 선택Optional | default, acceptEdits, dontAsk, bypassPermissions, plan |
| maxTurns | 선택Optional | 에이전트가 중지되기 전의 최대 에이전트 턴 수Maximum agent turns before the agent stops |
| skills | 선택Optional | 시작 시 에이전트 컨텍스트에 로드할 Skills. 에이전트는 부모 대화에서 skill을 상속하지 않으므로 명시적으로 나열 필요Skills to load into the agent context at startup. Agents don't inherit skills from the parent conversation, so must be listed explicitly |
| mcpServers | 선택Optional | 이 에이전트에서 사용 가능한 MCP 서버 이름 목록 또는 인라인 정의List of MCP server names or inline definitions available in this agent |
| hooks | 선택Optional | 이 에이전트로 범위가 지정된 라이프사이클 hooks (PreToolUse, PostToolUse, Stop 등)Lifecycle hooks scoped to this agent (PreToolUse, PostToolUse, Stop, etc.) |
| memory | 선택Optional | 지속적 메모리 범위: user, project, local. 세션 간 학습 활성화Persistent memory scope: user, project, local. Enables learning across sessions |
| background | 선택Optional | true로 설정하면 항상 백그라운드 태스크로 실행. 기본값: falseWhen set to true, always runs as a background task. Default: false |
| isolation | 선택Optional | worktree로 설정하면 임시 git worktree에서 실행 (격리된 저장소 복사본 제공)When set to worktree, runs in a temporary git worktree (provides an isolated repo copy) |
memory 필드는 서브에이전트에 대화 간에 유지되는 지속적 디렉토리를 제공합니다. 코드베이스 패턴, 디버깅 통찰력, 아키텍처 결정 등의 지식을 시간에 따라 축적합니다.The memory field provides a persistent directory maintained between conversations for the sub-agent. Accumulates knowledge like codebase patterns, debugging insights, and architecture decisions over time.
| 범위Scope | 저장 위치Storage Location | 사용 시기When to Use |
|---|---|---|
| user | ~/.claude/agent-memory/<name>/ |
모든 프로젝트에서 학습 기억 (권장 기본값)Learned memory across all projects (recommended default) |
| project | .claude/agent-memory/<name>/ |
프로젝트별 지식, 버전 제어로 팀 공유 가능Project-specific knowledge, shareable with team via version control |
| local | .claude/agent-memory-local/<name>/ |
프로젝트별이지만 버전 제어에 포함하지 않을 때Project-specific but not to be included in version control |
| 모드Mode | 동작Behavior |
|---|---|
| default | 프롬프트를 사용한 표준 권한 확인Standard permission confirmation using prompts |
| acceptEdits | 파일 편집 자동 수락Auto-accept file edits |
| dontAsk | 권한 프롬프트 자동 거부 (명시적으로 허용된 도구는 여전히 작동)Auto-reject permission prompts (explicitly allowed tools still work) |
| bypassPermissions | 모든 권한 확인 건너뛰기 (주의해서 사용)Skip all permission confirmations (use with caution) |
| plan | Plan mode (읽기 전용 탐색)Plan mode (read-only exploration) |
bypassPermissions는 모든 권한 확인을 건너뛰어 서브에이전트가 승인 없이 모든 작업을 실행할 수 있게 합니다. 신중하게 사용하세요. 부모가 bypassPermissions를 사용하면 이것이 우선하며 재정의할 수 없습니다.Warning: bypassPermissions skips all permission checks, allowing the sub-agent to execute any action without approval. Use with caution. If the parent uses bypassPermissions, it takes precedence and cannot be overridden.
세션 중에만 사용할 에이전트를 JSON으로 전달합니다. 디스크에 저장되지 않아 빠른 테스트나 자동화 스크립트에 유용합니다.Pass agents as JSON to use only during the session. Not saved to disk, so useful for quick tests or automation scripts.
바로 활용할 수 있는 실전 에이전트 아이디어 모음입니다.A collection of practical agent ideas you can use right away.
코드를 수정하지 않고 검토하는 읽기 전용 에이전트. 보안, 성능, 가독성 관점 피드백.Read-only agent that reviews code without modifying it. Feedback from security, performance, and readability perspectives.
오류, 테스트 실패, 예상치 못한 동작 디버깅 전문가. 근본 원인 분석 후 수정.Expert debugger for errors, test failures, and unexpected behavior. Analyzes root cause then fixes.
SQL, BigQuery 분석 전문가. 데이터 분석 작업과 쿼리에 proactively 사용.SQL, BigQuery analysis expert. Use proactively for data analysis tasks and queries.
읽기 전용 DB 쿼리만 허용. PreToolUse hook으로 SQL 쓰기 작업 차단.Only allows read-only DB queries. Blocks SQL write operations with PreToolUse hook.
테스트 작성 전문가. 기존 코드를 분석하여 유닛·통합 테스트를 자동 생성합니다.Test writing specialist. Analyzes existing code and auto-generates unit and integration tests.
문서 작성 전문가. 코드를 분석하여 README, API 문서, 주석을 자동으로 생성합니다.Documentation specialist. Analyzes code and auto-generates README, API docs, and comments.
서브에이전트는 포어그라운드(차단) 또는 백그라운드(동시)에서 실행할 수 있습니다.Sub-agents can run in the foreground (blocking) or background (concurrent).
완료될 때까지 주 대화를 차단합니다. 권한 프롬프트 및 명확한 질문이 사용자에게 전달됩니다. 결과를 즉시 확인해야 할 때 사용합니다.Blocks the main conversation until complete. Permission prompts and clarifying questions are passed to the user. Use when you need to see results immediately.
동시에 실행되는 동안 다른 작업을 계속할 수 있습니다. Ctrl+B로 실행 중인 작업을 백그라운드로 전환할 수 있습니다.Allows you to continue other work while it runs simultaneously. Use Ctrl+B to send a running task to the background.
테스트 실행, 로그 분석처럼 많은 출력을 생성하는 작업을 서브에이전트에 위임합니다. 상세 출력은 에이전트 컨텍스트에 유지되고, 관련 요약만 주 대화로 반환됩니다.Delegate tasks that generate lots of output, like running tests or analyzing logs, to sub-agents. Detailed output stays in the agent context; only relevant summaries return to the main conversation.
독립적인 조사를 여러 서브에이전트가 동시에 수행합니다. 각 에이전트가 자신의 영역을 탐색한 후 결과를 종합합니다.Multiple sub-agents perform independent investigations simultaneously. Each agent explores its own area, then results are synthesized.
다단계 워크플로우를 위해 에이전트를 순차적으로 연결합니다.
예시:
1. code-reviewer 에이전트로 성능 문제 발견
2. 결과를 받아서 optimizer 에이전트로 수정
"code-reviewer 에이전트로 성능 문제를 찾고, 그 다음 optimizer 에이전트로 수정해줘"
주의: 서브에이전트는 다른 서브에이전트를 생성할 수 없습니다. 중첩 위임이 필요하면 Skills를 사용하거나 주 대화에서 에이전트를 체인하세요.
Connect agents sequentially for multi-step workflows.
Example:
1. Find performance issues with the code-reviewer agent
2. Take those results and fix them with the optimizer agent
"Find performance issues with the code-reviewer agent, then fix them with the optimizer agent"
Note: Sub-agents cannot create other sub-agents. If nested delegation is needed, use Skills or chain agents from the main conversation.
에이전트에 대해 가장 많이 궁금해하는 것들The most common questions about agents
/agents 명령을 실행하면 새 에이전트가 즉시 로드됩니다. (2) 세션을 재시작합니다. /agents로 생성한 에이전트는 저장 즉시 사용 가능합니다.Sub-agents are loaded when a session starts. If you manually added a file, there are two ways to load it immediately: (1) Run the /agents command to load new agents immediately. (2) Restart the session. Agents created with /agents are available immediately after saving.
claude agents 명령으로 소스별로 그룹화된 에이전트 목록과 재정의 현황을 확인할 수 있습니다.The agent from the higher-priority location takes precedence. Priority order: CLI --agents (1st) > .claude/agents/ (2nd) > ~/.claude/agents/ (3rd) > Plugin (4th). Use the claude agents command to see agents grouped by source and current override status.
tools 필드(허용 목록): 허용할 도구만 나열합니다. disallowedTools 필드(거부 목록): 제외할 도구를 나열합니다. 예를 들어 리뷰 에이전트에 tools: Read, Grep, Glob, Bash만 허용하면 Write나 Edit은 사용할 수 없습니다. Agent(name) 구문으로 생성 가능한 서브에이전트 유형도 제한할 수 있습니다.Yes, there are two ways to restrict. tools field (allowlist): list only the tools you allow. disallowedTools field (denylist): list tools to exclude. For example, allowing only tools: Read, Grep, Glob, Bash for a review agent means Write and Edit cannot be used. You can also restrict the types of sub-agents that can be spawned using the Agent(name) syntax.
~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl에 저장됩니다. 동일한 세션을 재개하면 Claude Code 재시작 후에도 서브에이전트를 재개할 수 있습니다.Yes, you can resume the agent. When a sub-agent completes, Claude receives the agent ID. Asking Claude to "continue the previous work" resumes exactly where it left off, maintaining the full conversation history (all tool calls, results, and reasoning). Sub-agent transcripts are stored at ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl. Resuming the same session allows sub-agent resumption even after restarting Claude Code.
Agent(agent_type) 구문은 서브에이전트 정의에서는 효과가 없습니다. 중첩된 위임이 필요한 경우 Skills를 사용하거나 주 대화에서 에이전트를 체인하세요. 단, claude --agent로 주 스레드로 실행되는 에이전트는 서브에이전트를 생성할 수 있습니다.No, sub-agents cannot create other sub-agents. This is by design to prevent infinite nesting. The Agent(agent_type) syntax has no effect in sub-agent definitions. If nested delegation is needed, use Skills or chain agents from the main conversation. However, agents run as the main thread with claude --agent can create sub-agents.
내장 에이전트 = Explore, Plan, general-purpose 기본 제공
커스텀 에이전트 = .claude/agents/에 마크다운 하나
핵심 가치 = 병렬 처리 + 전문 분야 특화 + 컨텍스트 분리
지속 학습 = memory 필드로 세션 간 지식 축적
Built-in Agents = Explore, Plan, general-purpose provided by default
Custom Agents = One markdown file in .claude/agents/
Core Value = Parallel processing + Domain specialization + Context separation
Continuous Learning = Accumulate knowledge across sessions with the memory field
시작이 어려우면, Claude에게 이렇게 말해보세요:
"/agents 명령으로 코드 리뷰 에이전트를 만들어줘"
If you're not sure where to start, try saying this to Claude:
"Create a code review agent with the /agents command"