Ch4. 서브에이전트 활용

서브에이전트는 메인 세션 안에서 독립된 컨텍스트로 작업하는 하위 에이전트입니다. 탐색/리서치 같은 작업을 분리해 메인 컨텍스트를 덜 소모할 수 있습니다.

서브에이전트의 장점

• 컨텍스트 격리: 하위 작업이 메인 컨텍스트를 덜 소모
• 작업 분리: 리서치/탐색을 분리해 집중도 향상

커스텀 에이전트 작성

.claude/agents/ 디렉토리에 Markdown 파일을 생성합니다.

에이전트 파일 구조

---
name: code-reviewer
description: 코드 리뷰 전문가. PR 변경사항을 분석하고 개선점을 제안합니다.
tools: Read, Glob, Grep, Bash
model: sonnet
memory: project
---

당신은 시니어 코드 리뷰어입니다.

## 리뷰 기준

- 보안 취약점
- 성능 문제
- 타입 안정성
- 에러 핸들링

에이전트 목록 확인

claude agents

claude agents CLI 명령으로 현재 프로젝트에 설정된 에이전트 목록을 확인할 수 있습니다. (v2.1.50)

신규 frontmatter (v2.1.33 기준)

플러그인 제공 에이전트 frontmatter (v2.1.78)

플러그인에서 제공하는 에이전트에 다음 frontmatter 필드를 사용할 수 있습니다:

• effort — 에이전트의 추론 강도를 고정 (low/medium/high)
• maxTurns — 최대 턴 수 제한
• disallowedTools — 사용 금지 도구 목록

isolation: "worktree" — git worktree 격리

에이전트 frontmatter에 isolation: "worktree"를 지정하면, 서브에이전트가 임시 git worktree에서 격리 실행됩니다. 메인 작업 디렉토리에 영향을 주지 않고 독립적으로 작업할 수 있습니다. (v2.1.49)

background: true — 항상 백그라운드 실행

에이전트 frontmatter에 background: true를 지정하면 해당 에이전트가 항상 백그라운드에서 실행됩니다. (v2.1.49)

memory 스코프

에이전트 frontmatter의 memory로 지속 메모리 범위를 제어할 수 있습니다.

initialPrompt — 자동 시작 프롬프트 (v2.1.83)

에이전트 frontmatter에 initialPrompt를 지정하면, 에이전트가 생성될 때 자동으로 해당 프롬프트가 제출됩니다. 사용자 입력 없이 즉시 작업을 시작하는 에이전트를 만들 수 있습니다.

---
name: daily-report
description: 매일 프로젝트 상태를 요약하는 에이전트
tools: Read, Glob, Grep, Bash
initialPrompt: "오늘의 git 커밋과 PR 변경사항을 요약해줘"
---

@ 멘션 타입어헤드 (v2.1.88)

이름이 지정된(named) 서브에이전트가 @ 멘션 타입어헤드 제안에 표시됩니다. 실행 중인 서브에이전트에 메시지를 보낼 때 @에이전트이름으로 빠르게 선택할 수 있습니다.

Task(agent_type)로 생성 가능한 하위 에이전트 제한

특정 에이전트만 생성 가능하도록 제한하면, 팀 정책/보안 관점에서 운영이 쉬워집니다.

---
name: orchestrator
description: 작업을 분배하고 결과를 합치는 오케스트레이터
tools: Read, Grep, Task(code-reviewer), Task(test-runner)
model: sonnet
---

모델 관련

• Agent 도구에서 model 파라미터로 개별 호출 시 모델 오버라이드를 지정할 수 있습니다. (v2.1.72)
• 에이전트 frontmatter의 model: 필드에서 full model ID (예: claude-opus-4-5)가 정상 인식됩니다. (v2.1.74)
• Team agents는 리더(호출자)의 모델을 상속합니다. (v2.1.72)
• Bedrock/Vertex/Foundry 환경에서는 서브에이전트의 모델 다운그레이드가 방지됩니다. (v2.1.73)

Agent resume 파라미터 제거

// 이전 방식 (v2.1.76 이하) — 더 이상 동작하지 않음
// Agent({ resume: agentId, prompt: "계속해줘" })

// 새 방식 (v2.1.77+)
SendMessage({ to: agentId, content: "계속해줘" })

백그라운드 실행과 알림

• run_in_background 파라미터로 에이전트를 백그라운드에서 실행하면, 완료 시 자동으로 알림을 받을 수 있습니다.
• 백그라운드 에이전트 완료 알림에는 output file 경로가 포함됩니다. (v2.1.71)

최신 운영 메모 (v2.1.97~v2.1.114)

다음 항목은 새 문법이라기보다, 실제 운영에서 체감되는 권한 전달/상태 보고/격리 안정성 변경입니다.

• v2.1.98: --dangerously-skip-permissions 사용 시 team agent가 리더의 permission mode를 상속하도록 수정되었습니다.
• v2.1.98: 오류로 종료되는 background subagent도 partial progress를 부모 agent에 보고하게 되었습니다.
• v2.1.98: 오래된 subagent worktree 정리 과정에서 untracked 파일이 있는 worktree를 잘못 삭제하지 않도록 보강되었습니다.
• v2.1.97: isolation: "worktree" 또는 cwd: override를 쓰는 subagent가 부모 세션의 Bash 작업 디렉토리를 오염시키던 문제가 수정되었습니다.
• v2.1.101: 동적으로 주입된 MCP 서버의 도구가 subagent에도 상속되도록 수정되었습니다.
• v2.1.101: 격리 worktree에서 실행되는 subagent가 자기 worktree 내부 파일을 Read/Edit 하지 못하던 문제가 수정되었습니다.
• v2.1.101: --resume 복구 중 무관한 subagent 대화 체인으로 연결되던 문제가 수정되었습니다.
• v2.1.108: 메인 모델이 Skill tool을 통해 **내장 슬래시 명령(/init, /review, /security-review 등)**도 호출할 수 있게 되어, 에이전트 오케스트레이션에서 얇은 래퍼 스킬 의존성이 줄었습니다.
• v2.1.113: 중간 스트리밍에서 멈춘 subagent가 10분 후 명확한 오류로 종료되도록 바뀌어, 조용히 hang되는 상황이 줄었습니다.

참고 문서

• 서브에이전트 개요: https://docs.claude.com/en/docs/claude-code/subagents (영어)
• Changelog (memory, Task(agent_type)): https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md (영어)
• Release v2.1.98: https://github.com/anthropics/claude-code/releases/tag/v2.1.98
• Release v2.1.101: https://github.com/anthropics/claude-code/releases/tag/v2.1.101
• Release v2.1.108: https://github.com/anthropics/claude-code/releases/tag/v2.1.108