Claude Code 서브에이전트

위치와 우선순위

정의 파일의 형태

---
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의 일반 시스템 프롬프트를 받지 않고, 여기에 적은 내용과 환경 정보만으로 동작합니다. "리뷰해 주세요"라고만 적힌 서브에이전트가 기대에 못 미치는 것은 모델 탓이 아니라 지시가 비어 있기 때문입니다.

주요 프런트매터 항목

• `name`: 식별자. 소문자와 하이픈만 쓰며 콜론은 사용할 수 없습니다.
• `description`: 어떤 상황에서 위임해야 하는지 적습니다. 자동 위임의 판단 재료가 되는 것이 이 항목입니다.
• `tools`: 허용할 도구(Read, Glob, Grep, Bash 등). 읽기 전용으로 만들고 싶으면 여기서 좁힙니다.
• `model`: `sonnet` / `opus` / `haiku` / `fable`, 또는 전체 모델 ID.
• `memory`: `user` / `project` / `local`. 서브에이전트 자체의 지속 메모리를 둘 때 지정합니다.
• `permissionMode`: `default` / `acceptEdits` / `auto` / `dontAsk` / `bypassPermissions` / `plan`.

만드는 법: v2.1.198에서 바뀐 점

예전에는 `/agents`가 대화형 마법사를 열었지만 v2.1.198부터는 열리지 않습니다. 대신 Claude에게 직접 부탁합니다 — "~/.claude/agents/ 에 가독성과 성능 개선을 제안하는 읽기 전용 code-improver 서브에이전트를 Sonnet으로 만들어 줘"처럼요. Claude가 파일을 쓰고, 파일 감시가 동작하므로 몇 초 안에 반영됩니다(새 agents/ 디렉터리에 첫 번째를 만들 때만 재시작이 필요합니다).

호출하는 세 가지 방법

# 1. 자연어(자동 위임)
Use the code-reviewer subagent to look at my recent changes

# 2. @멘션(확실하게 위임됨)
@"code-reviewer (agent)" look at the auth changes

# 3. 세션 전체 고정
claude --agent code-reviewer

메모리 취급에 주의

메인 대화의 자동 메모리는 서브에이전트에 로드되지 않습니다(예외는 fork로, 부모 대화와 시스템 프롬프트를 상속합니다). 서브에이전트에 `memory`를 지정한 경우에도 그것은 별도 디렉터리의 독립된 메모리입니다. "메인에서 설명했는데 서브에이전트가 모른다"는 현상은 버그가 아니라 사양입니다. 필요한 전제는 description이나 본문에 적어야 합니다.