커스텀 서브에이전트

커스텀 서브에이전트는 특정 역할과 도메인에 최적화된 전문 에이전트입니다. .claude/agents/ 디렉토리에 마크다운 파일로 정의하며, YAML frontmatter로 도구, 모델, 권한을 세밀하게 제어합니다.

파일 형식

YAML frontmatter + 마크다운 본문으로 구성합니다. frontmatter는 설정, 본문은 시스템 프롬프트입니다:

---
name: code-reviewer
description: 코드 품질과 보안 모범 사례를 검토합니다
tools: Read, Glob, Grep
model: sonnet
---

당신은 코드 리뷰어입니다. 호출되면 코드를 분석하고
품질, 보안, 모범 사례에 대한 구체적이고 실행 가능한 피드백을 제공하세요.

시스템 프롬프트

서브에이전트는 전체 Claude Code 시스템 프롬프트가 아닌 이 마크다운 본문만 시스템 프롬프트로 받습니다 (작업 디렉토리 같은 기본 환경 정보는 포함).

YAML Frontmatter 필드

필드	필수	설명
name	O	고유 식별자. 소문자와 하이픈만
description	O	Claude가 위임 판단에 사용
tools	-	사용 가능한 도구. 생략 시 전체 상속. Task(agent_type) 구문으로 서브에이전트 생성 제한
disallowedTools	-	차단할 도구
model	-	sonnet, opus, haiku, inherit (기본: inherit)
permissionMode	-	default, acceptEdits, dontAsk, bypassPermissions, plan
maxTurns	-	최대 에이전틱 턴 수
skills	-	시작 시 로드할 Skills (전체 콘텐츠 주입)
mcpServers	-	사용 가능한 MCP 서버 (이름 참조 또는 인라인 정의)
hooks	-	서브에이전트 라이프사이클 Hook
memory	-	영속 메모리 범위: user, project, local
background	-	true면 항상 백그라운드 실행 (기본: false)
isolation	-	worktree면 격리된 git 워크트리에서 실행

tools 필드 상세

Agent(agent_type) 구문으로 어떤 서브에이전트를 생성할 수 있는지 제한합니다:

tools: Agent(worker, researcher), Read, Bash

이것은 허용 목록입니다. Agent를 완전히 생략하면 서브에이전트를 생성할 수 없습니다. 이 제한은 claude --agent로 메인 스레드로 실행될 때만 적용됩니다.

Task → Agent 이름 변경

버전 2.1.63에서 Task 도구가 Agent로 이름이 변경되었습니다. 기존 Task(...) 참조는 호환성을 위해 별칭으로 계속 동작합니다.

permissionMode 값

모드	동작
default	표준 권한 확인
acceptEdits	파일 수정 자동 승인
dontAsk	권한 프롬프트 자동 거부 (명시 허용 도구만 작동)
bypassPermissions	모든 권한 검사 건너뜀 (주의)
plan	읽기 전용 탐색 모드

영속 메모리 (Persistent Memory)

memory 필드로 서브에이전트에게 세션 간 유지되는 메모리 디렉토리를 부여합니다:

범위	위치	용도
user	~/.claude/agent-memory/<name>/	모든 프로젝트 공통 (권장)
project	.claude/agent-memory/<name>/	프로젝트별, git 공유 가능
local	.claude/agent-memory-local/<name>/	프로젝트별, git 미추적

메모리가 활성화되면:

• 시스템 프롬프트에 메모리 읽기/쓰기 지침 포함
• MEMORY.md 처음 200줄이 자동 로드
• Read, Write, Edit 도구가 자동 활성화

---
name: code-reviewer
description: 코드 리뷰어 — 이전 리뷰 패턴을 기억합니다
tools: Read, Grep, Glob
memory: user
---

코드를 리뷰할 때 먼저 메모리에서 이전에 발견한 패턴을 확인하세요.
리뷰 완료 후 새로 배운 내용을 메모리에 저장하세요.

저장 위치와 우선순위

위치	범위	우선순위
--agents CLI 플래그	현재 세션	1 (최고)
.claude/agents/	현재 프로젝트	2
~/.claude/agents/	모든 프로젝트	3
플러그인 agents/	플러그인 활성 시	4 (최저)

같은 이름의 서브에이전트가 여러 레벨에 있으면 우선순위가 높은 것이 적용됩니다.

서브에이전트 생성과 관리

서브에이전트는 두 가지 방법으로 만들고 관리합니다:

• Claude에게 자연어로 요청: "코드 리뷰용 서브에이전트를 만들어줘"처럼 대화로 요청하면 Claude가 파일 생성·수정·삭제까지 처리합니다
• 파일 직접 편집: .claude/agents/(프로젝트) 또는 ~/.claude/agents/(사용자)의 마크다운 파일을 직접 작성하거나 수정합니다

/agents 위저드 제거

버전 2.1.198에서 /agents 인터랙티브 위저드(보기·생성·편집·삭제 메뉴)가 제거되었습니다. 이제 위의 두 방식 — Claude에게 요청하거나 .claude/agents/ 파일을 직접 편집 — 을 사용합니다.

CLI 정의 (--agents)

세션 한정 서브에이전트를 JSON으로 정의합니다:

claude --agents '{
  "code-reviewer": {
    "description": "코드 변경 후 자동 리뷰. 품질, 보안, 모범 사례에 집중.",
    "prompt": "당신은 시니어 코드 리뷰어입니다.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

지원 필드: description, prompt, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, skills, memory.

격리 실행 (Worktree)

isolation: worktree로 설정하면 서브에이전트가 git 워크트리의 격리된 복사본에서 실행됩니다:

---
name: experimental-refactor
description: 실험적 리팩토링을 격리 환경에서 수행
isolation: worktree
tools: Read, Write, Edit, Bash
---

코드를 자유롭게 실험하세요. 변경사항이 없으면 워크트리가 자동 정리됩니다.

Hook 연동

서브에이전트 frontmatter에서 직접 Hook을 정의할 수 있습니다. 해당 서브에이전트가 활성화된 동안만 실행되고, 완료 시 정리됩니다:

---
name: safe-executor
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
  Stop:
    - hooks:
        - type: prompt
          prompt: "모든 태스크가 완료됐는지 확인: $ARGUMENTS"
---

Stop Hook은 런타임에 자동으로 SubagentStop으로 변환됩니다.

실전 예시

DB 전문 에이전트

---
name: db-expert
description: 데이터베이스 스키마 분석과 쿼리 최적화
tools: Read, Grep, Glob, Bash(psql *)
model: sonnet
memory: project
---

데이터베이스 전문가입니다.
- 스키마 분석 시 인덱스 효율성을 반드시 확인
- 쿼리 최적화 제안 시 EXPLAIN 결과를 근거로 제시
- 마이그레이션 작성 시 롤백 전략 포함

보안 감사 에이전트

---
name: security-auditor
description: 보안 취약점 검사 — OWASP Top 10 중심
tools: Read, Grep, Glob
model: opus
permissionMode: plan
---

보안 감사관입니다. OWASP Top 10 기준으로:
1. SQL 인젝션 가능성 검사
2. XSS 취약점 식별
3. 인증/인가 로직 검증
4. 민감 데이터 노출 확인
5. 구체적 수정 방안 제시

문서 작성 에이전트

---
name: doc-writer
description: API 문서와 README 자동 생성
tools: Read, Glob, Grep, Write, Edit
model: sonnet
skills:
  - doc-template
---

기술 문서 작성자입니다.
코드를 분석하고 명확하고 실용적인 문서를 작성합니다.
doc-template 스킬의 형식을 따릅니다.

설계 원칙

• 하나의 역할에 집중: 각 서브에이전트는 하나의 전문 분야만 담당. 범용 에이전트보다 집중된 에이전트가 더 정확합니다
• 상세한 설명: Claude가 description을 보고 위임 여부를 판단합니다. "코드 리뷰"보다 "코드 품질과 보안 모범 사례를 검토합니다"가 더 정확한 위임을 유도합니다
• 최소 도구 권한: 필요한 도구만 부여하세요. 읽기 전용 에이전트에 Write/Edit를 줄 필요가 없습니다
• 비용 제어: model: sonnet이나 model: haiku로 빠르고 저렴한 모델을 지정할 수 있습니다. 탐색 작업에는 Haiku, 복잡한 분석에는 Sonnet이 적합합니다
• 결과 크기 주의: 서브에이전트의 결과가 메인 대화에 반환됩니다. 여러 서브에이전트가 상세한 결과를 반환하면 메인 컨텍스트를 빠르게 소비할 수 있습니다
• git 커밋: 프로젝트 서브에이전트는 .claude/agents/에 저장하고 팀과 공유하세요

서브에이전트 제약

서브에이전트는 다른 서브에이전트를 생성할 수 없습니다. 중첩 위임이 필요하면 Skills를 사용하거나, 메인 대화에서 서브에이전트를 순차 호출하세요.