Claude Code 서브에이전트 만들기·운영

준비물(필요한 것)#

0단계: 서브에이전트가 맞는 일인지 확인#

원본의 기준표다. Claude Code 서브에이전트

• 메인 대화 맥락에서 도는 재사용 프롬프트·워크플로가 필요하면 스킬을 고려한다. Claude Code 서브에이전트
• 이미 대화에 있는 것에 대한 질문은 /btw를 쓴다. 전체 맥락을 보지만 도구가 없고, 답이 기록에 더해지지 않는다. Claude Code 서브에이전트
• 커스텀 서브에이전트를 정의할 때는 같은 지시로 같은 종류의 작업자를 계속 띄우게 될 때다(원본 첫 문단: "Define a custom subagent when you keep spawning the same kind of worker with the same instructions"). Claude Code 서브에이전트
• 서브에이전트는 자기 요청을 보내고 그 요청도 메인 대화와 같은 사용량 한도에 잡힌다. 많은 서브에이전트가 각자 자세한 결과를 돌려주면 메인 컨텍스트도 많이 쓴다. Claude Code 서브에이전트 → 컨텍스트 비용

1단계: 범위(위치) 고르기#

같은 이름이면 managed > --agents > 프로젝트 > 사용자 > 플러그인 순으로 이긴다. 플러그인 서브에이전트는 hooks·mcpServers·permissionMode를 무시하므로, 이 셋이 필요하면 프로젝트나 사용자 위치에 둔다. Claude Code 서브에이전트 → 서브에이전트 정의 파일 레퍼런스

2단계: 만들기#

Claude에게 부탁하기(원본 빠른 시작). 원하는 서브에이전트와 저장 위치를 말한다. Claude Code 서브에이전트

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(파일 맨 앞 머리말, 용어 사전)가 요청과 맞는지 확인한다. 원본이 보여 주는 결과: Claude Code 서브에이전트

---
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/나 ~/.claude/agents/에 만든다. 필수는 name과 description, 여러 단어 필드는 camelCase로 정확히 쓴다(틀리면 오류 없이 무시). 하위 폴더(agents/review/)로 정리해도 되고, 정체는 name으로만 정해진다. Claude Code 서브에이전트

• 지금 버전의 /agents는 Claude에게 부탁하거나 디렉터리를 직접 고치라는 안내만 출력한다(v2.1.197 이하는 대화형 마법사). Claude Code 서브에이전트
• 실행 중 추가·수정은 몇 초 안에 감지돼 다음 위임부터 반영된다. 세션 시작 때 ~/.claude/agents/가 없었다면 처음 만든 뒤 재시작한다. Claude Code 서브에이전트

설명(description) 쓰기. Claude는 요청의 작업 설명, 각 서브에이전트의 description, 현재 맥락으로 자동 위임을 정한다. 적극적으로 위임하게 하려면 설명에 "use proactively" 같은 문구를 넣는다. 설명은 하나의 서브에이전트로 라우팅될 만큼 구체적으로, 그러나 짧게 쓴다. 내장을 뺀 설명 합이 15,000토큰을 넘으면 시작 때 경고가 뜨니, 세부는 실행할 때만 로드되는 본문(시스템 프롬프트)으로 옮긴다. Claude Code 서브에이전트

3단계: 시험하기#

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

트랜스크립트에 code-improver(Suggest code improvements)처럼 서브에이전트 이름과 짧은 작업 설명을 담은 도구 호출 행이 보이면 위임된 것이다. Claude가 새 서브에이전트를 못 찾으면 재시작한다. Claude Code 서브에이전트 플러그인으로 배포하는 서브에이전트는 claude plugin eval로 실제 같은 프롬프트에서 위임이 얼마나 안정적인지 켠 채/끈 채 비교해 잴 수 있다. Claude Code 서브에이전트 → 업무 절차를 스킬로 만들기

4단계: 능력 좁히기#

원본 모범 사례는 "필요한 권한만 준다(보안과 집중을 위해)"다. Claude Code 서브에이전트 도구·권한 제한에는 아래 조건이 붙는다.

허용 목록(tools) — Read, Grep, Glob, Bash만. 파일 편집·쓰기와 MCP 도구가 없다:

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

거부 목록(disallowedTools) — Write·Edit만 빼고 Bash·MCP 도구·나머지 풀은 유지:

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

MCP 서버 하나 빼기:

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

근거: Claude Code 서브에이전트. 조건과 한계:

• disallowedTools: Bash(git push *)처럼 써도 Bash 도구 전체가 빠진다. Bash는 두고 특정 명령만 막으려면 설정의 permissions.deny에 Bash(git push *)를 둔다(메인 대화와 서브에이전트 모두에 적용). Claude Code 서브에이전트
• 편집자 해석: 원본은 safe-researcher가 "파일을 편집하거나 쓸 수 없다"고 하지만 같은 예가 Bash를 남기므로, 이 문장은 Edit·Write 도구가 없다는 뜻으로 읽는 편이 안전하다고 볼 수 있다. Bash 명령으로 하는 일까지 이 필드가 막는다고 원본이 말하지는 않는다. 근거 문장: "The subagent can't edit files, write files, or use any MCP tools". Claude Code 서브에이전트
• permissionMode는 메인 대화가 bypassPermissions·acceptEdits·auto 모드면 무시되고 메인 모드를 따른다. 서브에이전트에 bypassPermissions를 줘도 메인이 그 모드가 아니면 메인 모드로 돈다(v2.1.267 이상). Claude Code 서브에이전트 → 권한 모드
• 백그라운드 서브에이전트(기본값)는 정해진 내장 도구만 남아, 같은 정의가 포그라운드와 다른 도구로 풀릴 수 있다. Claude Code 서브에이전트

띄울 수 있는 서브에이전트 제한 (claude --agent 메인 스레드 전용): Claude Code 서브에이전트

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

서브에이전트 정의에서는 괄호 안 목록이 무시된다. 서브에이전트가 자기 서브에이전트를 띄우지 못하게 하려면 tools에서 Agent를 빼거나 disallowedTools에 넣는다. Claude Code 서브에이전트

MCP 서버를 이 서브에이전트에만 — 메인 대화에 서버 도구 설명이 들어가지 않는다: Claude Code 서브에이전트

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

프로젝트 .claude/agents/의 인라인 서버는 그 폴더를 신뢰한 뒤에만 연결된다(상위 폴더 신뢰·-p 자동 신뢰는 치지 않음). managed MCP 정책도 적용된다. Claude Code 서브에이전트 → MCP

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

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

앞쪽 32개 이름까지 전체 내용이 주입된다. 미리 로드는 접근 제한이 아니어서 다른 스킬도 Skill 도구로 부를 수 있다. disable-model-invocation: true 스킬은 미리 로드되지 않는다. Claude Code 서브에이전트 → 스킬

조건부 규칙(훅) — 도구는 두되 일부 동작만 막을 때. 아래 "원본 예시 정의"의 db-reader가 전체 예다. 프로젝트 서브에이전트의 frontmatter 훅은 그 폴더의 작업 공간 신뢰를 수락하기 전에는 건너뛰고(서브에이전트는 훅 없이 그대로 돈다), -p 세션은 신뢰로 치지 않는다. 훅 스크립트는 macOS·Linux에서 실행 권한이 없으면 막지 못하고 실패한다. Claude Code 서브에이전트 → Claude Code 차단 훅 단단하게 만들기

세션 전체 훅으로 서브에이전트 시작·종료에 반응 — settings.json에 둔다. 원본 예: db-agent가 시작할 때만 준비 스크립트, 어떤 서브에이전트든 끝나면 정리 스크립트. Claude Code 서브에이전트

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

matcher는 프로젝트·사용자 서브에이전트면 frontmatter name, 플러그인 서브에이전트면 ^my-plugin:db-agent$처럼 고정한 범위 이름이다. settings 파일·managed 정책·플러그인의 훅은 서브에이전트 안에서도 돌아, settings.json의 PreToolUse 훅은 서브에이전트의 모든 도구 앞에서도 돈다. Claude Code 서브에이전트 → 훅 이벤트 레퍼런스

frontmatter 훅 — 그 서브에이전트가 도는 동안만. 원본 예: Bash 명령 검증과 편집 뒤 린터. Stop 훅은 서브에이전트로 불릴 때 SubagentStop으로 바뀐다. Claude Code 서브에이전트

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

5단계: 지속 메모리 붙이기 (선택)#

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

원본 팁: Claude Code 서브에이전트

• 권장 기본 범위는 project(.claude/agent-memory/<name-of-agent>/, 버전 관리로 공유).

• 시작 전에 참고하게: "Review this PR, and check your memory for patterns you've seen before."

• 끝난 뒤 저장하게: "Now that you're done, save what you learned to your memory."

• 정의 파일에 직접 넣기:

  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.

조건: 자동 메모리를 끄면(autoMemoryEnabled, CLAUDE_CODE_DISABLE_AUTO_MEMORY) 이 필드는 효과가 없다. 켜면 Read·Write·Edit 도구가 자동으로 켜진다. Claude Code 서브에이전트 → 자동 메모리(Auto memory)

6단계: 부르기#

자동 위임만으로 부족하면 직접 부른다. 세 방식은 한 번 제안 → 한 작업 보장 → 세션 전체 순으로 강해진다. Claude Code 서브에이전트

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

{
  "agent": "code-reviewer"
}

• @-mention은 어떤 서브에이전트를 부를지만 정한다. 메시지 전체는 Claude에게 가고, Claude가 그 서브에이전트의 작업 프롬프트를 쓴다. Claude Code 서브에이전트
• --agent로 돌면 커스텀 서브에이전트의 시스템 프롬프트가 기본 Claude Code 시스템 프롬프트를 통째로 대체한다(--system-prompt와 같은 방식, 프롬프트가 빈 경우 제외). CLAUDE.md와 프로젝트 메모리는 omitClaudeMd가 있어도 일반 메시지 흐름으로 로드된다. 시작 헤더에 @<name>이 보이고, 세션을 재개해도 도구 제한·모델이 복원된다. CLI 플래그가 설정보다 우선한다. 플러그인 이름이 겹치면 claude --agent my-plugin:security-reviewer처럼 범위 이름을 쓴다. Claude Code 서브에이전트

7단계: 백그라운드·재개·포크 다루기#

포그라운드·백그라운드. 대화형 세션은 기본으로 포크 모드가 켜져 있어 Claude가 띄우는 서브에이전트가 모두 백그라운드에서 돈다(인프로세스 에이전트 팀 팀원이 띄운 서브에이전트와 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1일 때는 포그라운드). context: fork 스킬은 스킬 쪽 규칙을 따른다. 포크 모드가 꺼진 -p·Agent SDK에서는 기본 백그라운드, 결과가 있어야 계속할 때만 포그라운드다. Ctrl+B로 실행 중 작업을 백그라운드로 보낸다. Claude Code 서브에이전트

• 백그라운드 서브에이전트의 권한 확인은 메인 세션에 서브에이전트 이름과 함께 뜬다. 승인하면 계속하고, Esc는 그 도구 호출 하나만 거부한다. 세션 끝까지 지속되는 승인처럼 그 한 번을 넘는 답을 주면 메인 대화를 포함한 세션 전체에 적용된다. Claude Code 서브에이전트
• 결과는 다음 턴에 완료 알림으로 온다. Claude는 알림 전에는 결과를 보고하지 않고 "아직 도는 중"이라고 답한다(v2.1.211 이전에는 끝나기 전 결과를 말하기도 했다). Claude Code 서브에이전트
• /tasks로 도는 서브에이전트와 모델을 본다. 성공한 서브에이전트 행은 바로 지워지고 30초 동안 /tasks에서 트랜스크립트를 열 수 있다. 실패·중지한 행은 30초 남고 x로 지운다. Claude Code 서브에이전트

재개. 부를 때마다 새 인스턴스다. 이어 하려면 Claude에게 이전 작업을 계속하라고 한다. 재개된 서브에이전트는 이전 도구 호출·결과·추론을 모두 갖는다. Claude Code 서브에이전트

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]

• 내장 Explore·Plan은 일회용이라 재개할 수 없다. 이어 할 일이면 general-purpose나 커스텀 서브에이전트를 쓴다. maxTurns에서 멈춘 출력은 부분으로 표시되고 재개해 이어 간다. 사용자가 x나 SDK stop_task로 멈춘 서브에이전트는 자동 재개되지 않는다. Claude Code 서브에이전트
• 트랜스크립트: ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl. 메인 대화 컴팩션의 영향을 받지 않고, 같은 세션을 재개하면 재시작 뒤에도 서브에이전트를 재개할 수 있으며, cleanupPeriodDays(기본 30일) 뒤 지워진다. Claude Code 서브에이전트

포크. 지금까지 대화를 물려받는 서브에이전트로, 다시 설명하지 않고 곁가지 작업을 맡긴다. 직접 띄우는 명령은 /subtask다(v2.1.212 이상, v2.1.161~v2.1.211은 /fork. agent view를 끄면 /fork가 포크를 띄우고, 켜져 있으면 /fork는 세션 전체를 새 백그라운드 세션으로 복사). 원본 예: Claude Code 서브에이전트

/subtask draft unit tests for the parser changes so far

• 트랜스크립트를 연 상태에서 후속 메시지와 스킬은 그 에이전트로, 내장 명령은 메인 대화로 간다. /compact·/clear·/rewind는 확인을 묻고, /model·/fast는 이 화면에서 돌지 않는다. Ctrl+Enter나 Ctrl+X Ctrl+S로 보내면 에이전트가 기다리던 일이 끝나기 전에 메시지를 읽게 한다(v2.1.286 이상). Claude Code 서브에이전트
• 포크는 부모의 프롬프트 캐시를 재사용해 같은 맥락이 필요한 일에서 새 서브에이전트보다 싸다. 포크는 다시 포크를 띄우지 못한다. Claude는 Agent 도구로 포크를 띄울 때 isolation: "worktree"로 편집을 별도 worktree에 쓰게 할 수 있다. Claude Code 서브에이전트
• 포크 모드 끄기: CLAUDE_CODE_FORK_SUBAGENT=0(모든 세션). 1은 비대화형·SDK에서도 켠다. 포크 모드는 두되 Claude가 포크를 못 띄우게 하려면 permissions.deny에 Agent(fork). Claude Code 서브에이전트

원본의 공통 패턴 (프롬프트 원문)#

양이 많은 작업 격리: Claude Code 서브에이전트

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가 필요한 맥락을 다음 서브에이전트에 넘긴다:

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

계속 병렬로 돌아야 하거나 컨텍스트 창 하나에 안 들어가는 일은 별도 세션으로 돌리고 세션 간 메시지로 결과를 넘기라고 원본은 말한다. 같은 모양의 일반 패턴은 에이전트 시스템 패턴 고르기의 병렬화·체이닝·오케스트레이터-워커다(편집자 연결: 원본은 이 패턴 이름을 쓰지 않는다). Claude Code 서브에이전트

한도 조정#

근거: Claude Code 서브에이전트. 원본 예(2층으로 제한):

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

세션 전체 총수에는 한도가 없다. ultracode가 켜진 세션은 동시 실행 한도를 적용받지 않는다. /subtask 포크와 끝난 서브에이전트 재개는 한도 확인 없이 자리를 차지해 실행 수가 한도를 넘을 수 있다. 워크플로 에이전트와 팀원은 자기 한도를 따른다. Claude Code 서브에이전트

원본 예시 정의 (글자 그대로)#

원본 모범 사례: 한 가지 일에 뛰어난 집중된 서브에이전트, 하나로 라우팅되는 구체적 설명, 필요한 도구만, 프로젝트 서브에이전트는 버전 관리로 팀과 공유. Claude Code 서브에이전트

Code reviewer — 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.

Debugger — 고쳐야 하므로 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.

Data scientist — 코딩 밖 도메인 작업, 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.

Database query validator — Bash는 주되 읽기 전용 SQL만#

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

• 훅은 stdin JSON의 tool_input.command에서 Bash 명령을 받고, 종료 코드 2로 막으면서 stderr 메시지를 Claude에게 돌려준다. Windows는 PowerShell로 스크립트를 쓰고 훅 항목에 shell: powershell을 더한다. Claude Code 서브에이전트 → 훅 입출력 규칙
• 원본은 시스템 프롬프트가 쓰기 요청을 거절하게 하고 훅은 "backstop"(그래도 쓰기를 시도하면 막는 안전망)이라고 말한다. Claude Code 서브에이전트
• 한계: 스크립트는 나열한 SQL 키워드(INSERT·UPDATE·DELETE·DROP·CREATE·ALTER·TRUNCATE·REPLACE·MERGE)가 명령 텍스트에 단어로 나오는지만 본다. 편집자 해석: 목록에 없는 쓰기 방식이나 명령 텍스트에 키워드가 드러나지 않는 실행은 이 스크립트가 잡지 못할 수 있고, jq가 없으면 COMMAND가 비어 통과(exit 0)할 수 있다고 볼 수 있다. 근거는 위 스크립트의 grep -iE 줄과 빈 명령 처리 줄이다. 데이터베이스 계정 자체를 읽기 전용으로 두는 것 같은 다른 통제는 원본에 없다. 차단 훅 일반의 점검은 Claude Code 차단 훅 단단하게 만들기.
• 프로젝트 .claude/agents/에 두면 그 폴더의 작업 공간 신뢰를 수락하기 전에는 이 훅이 건너뛰어지고 서브에이전트는 훅 없이 돈다. -p 세션은 신뢰로 치지 않는다. Claude Code 서브에이전트

됐는지 확인하는 법#

모두 본문 각 단계에 나온 방법을 모은 것이다.

• 정의 파일이 요청대로 만들어졌는지: 만든 파일(예: ~/.claude/agents/code-improver.md)을 열어 frontmatter의 name·description·tools·model이 요청과 맞는지 본다(2단계). 필드 이름이 틀리면 오류 없이 무시되므로 camelCase 철자까지 확인한다. Claude Code 서브에이전트
• 위임됐는지: 트랜스크립트에 code-improver(Suggest code improvements)처럼 서브에이전트 이름과 짧은 작업 설명을 담은 도구 호출 행이 보이면 위임된 것이다. Claude가 새 서브에이전트를 못 찾으면 재시작한다(3단계). Claude Code 서브에이전트
• 설명이 너무 길지 않은지: 내장을 뺀 설명 합이 15,000토큰을 넘으면 시작 때 경고가 뜬다(2단계). Claude Code 서브에이전트
• 세션 전체로 돌릴 때(--agent): 시작 헤더에 @<name>이 보인다(6단계). Claude Code 서브에이전트
• 백그라운드에서 도는 것: /tasks로 도는 서브에이전트와 모델(모델 표시는 v2.1.242 이상)을 본다. 결과는 다음 턴에 완료 알림으로 온다(7단계). Claude Code 서브에이전트
• 도구 제한(4단계)이 실제로 걸렸는지: 원본에는 따로 확인 방법이 없다. 위 방법으로 위임을 확인한 뒤에도 기대대로 안 되면 Claude Code 서브에이전트 문제 해결을 본다.

언제 쓰고 언제 쓰지 않는가#

• 쓴다: 테스트 실행·문서 가져오기·로그 처리처럼 출력이 많은 일, 서로 의존하지 않는 병렬 조사, 같은 지시의 작업자를 반복해 띄울 때(커스텀 정의), 도구·권한을 좁혀 맡기고 싶을 때, 대화 맥락을 다시 설명하기 번거로운 곁가지 일(포크). Claude Code 서브에이전트
• 쓰지 않는다: 주고받기가 잦은 다듬기, 여러 단계가 맥락을 많이 공유하는 일, 빠르고 좁은 변경, 지연이 중요한 일(메인 대화), 메인 맥락에서 도는 재사용 절차(스킬), 이미 대화에 있는 것에 대한 질문(/btw). Claude Code 서브에이전트
• 편집자 해석: 원본은 서브에이전트 출력 검사가 "서브에이전트가 닿는 범위를 제한하는 것을 대신하지 않는다"고 하므로, 웹·외부 파일을 읽는 서브에이전트일수록 4단계의 도구 제한을 먼저 두는 편이 맞다고 볼 수 있다. 근거 문장: "It isn't a substitute for restricting what a subagent can reach." Claude Code 서브에이전트 → 서브에이전트

관련#

• 활용 메모(편집자 연결): 원본 예시 4개는 "읽기 전용 검토자 → 고치는 작업자 → 코딩 밖 도메인 → 훅으로 조건부 허용" 순으로 권한을 다르게 준 사례라, 비개발 직군에게 "에이전트에게 권한을 얼마나 줄까"를 설명하는 예로 쓸 수 있다. 근거는 원본이 각 예시에 붙인 설명(Edit·Write 제외, Edit 포함, 코딩 밖 워크플로, tools보다 세밀한 통제)이다.
• 서브에이전트 정의 파일 레퍼런스, 서브에이전트, Claude Code 서브에이전트 문제 해결, Claude Code 확장 기능 고르기, 장기 작업 컨텍스트 관리