Subagent가 해결하는 문제
긴 세션에서 다음 같은 비효율이 발생합니다:
- 검색 결과와 로그 출력이 메인 컨텍스트를 채워 토큰 예산 잠식
- 코드 리뷰처럼 다른 시각이 필요한 작업을 메인 에이전트가 그대로 자체 평가 (편향)
- 독립적 작업들을 순차 처리하느라 시간 낭비
Subagent는 독립 컨텍스트로 분리된 보조 에이전트입니다. 결과만 메인에 돌려주므로 컨텍스트가 깨끗하게 유지되고, 병렬 실행도 가능합니다.
Subagent 정의
subagent는 frontmatter가 있는 마크다운 파일 하나로 정의합니다. 둘 수 있는 위치와 우선순위는 다음과 같습니다.
| 위치 | 범위 | 우선순위 |
|---|---|---|
| managed settings | 조직 전체 | 1 (가장 높음) |
--agents CLI 플래그 | 현재 세션 | 2 |
.claude/agents/ | 현재 프로젝트 | 3 |
~/.claude/agents/ | 모든 프로젝트 | 4 |
플러그인의 agents/ | 플러그인이 켜진 곳 | 5 (가장 낮음) |
같은 이름의 subagent가 여러 위치에 있으면 우선순위가 높은 쪽을 사용합니다. 예전의 /agents 마법사는 Claude Code 2.1.198에서 제거됐습니다. 지금은 Claude에게 subagent를 만들어 달라고 하거나 위 디렉토리의 파일을 직접 편집합니다.
.claude/agents/code-reviewer.md 예시:
---
name: code-reviewer
description: |
Use after a logical chunk of code is written to review it against
the original plan and project coding standards.
tools: Read, Grep, Glob, Bash
model: sonnet
---
You are a senior code reviewer. Given a recent change set, identify:
1. Bugs and logic errors
2. Security vulnerabilities
3. Deviations from project conventions
Report only high-confidence issues. Skip stylistic nitpicks.
frontmatter 필드
필수 필드는 name과 description 두 가지입니다.
| 필드 | 용도 |
|---|---|
name | 호출 시 사용할 이름 (필수) |
description | Claude가 이 subagent에 작업을 맡길 조건 (필수, Skill의 description과 같은 역할) |
tools | 이 에이전트가 사용 가능한 도구. 생략하면 subagent가 쓸 수 있는 모든 도구를 상속 |
model | sonnet, opus, haiku, fable, 전체 모델 ID(예: claude-opus-5-5), inherit 중 선택. 생략하면 CLAUDE_CODE_SUBAGENT_MODEL 환경 변수, 그다음 메인 대화의 모델 순으로 정해짐 |
이 밖에 disallowedTools, permissionMode, maxTurns, skills, mcpServers, hooks, memory, background, effort, isolation, color 등을 지원합니다. 여러 단어로 된 필드는 camelCase로 쓰며, Claude Code는 인식하지 못하는 필드를 오류 없이 무시하므로 필드 이름의 오타에 주의합니다.
호출 방식
자동 호출
description에 명시된 조건에 맞으면 메인 에이전트가 자동으로 Agent 도구를 호출합니다.
명시적 호출
자연어로 지정하거나, @-멘션으로 특정 subagent를 지목합니다.
code-reviewer 에이전트로 src/auth/ 디렉토리 검토해줘
@"code-reviewer (agent)" 인증 관련 변경 사항 확인해줘
세션 전체를 특정 subagent로 실행하려면 claude --agent code-reviewer를 사용하고, 프로젝트 기본값으로 두려면 .claude/settings.json에 { "agent": "code-reviewer" }를 넣습니다. 둘 다 있으면 CLI 플래그가 우선합니다.
병렬 실행
다음을 병렬로:
- code-reviewer로 src/auth/ 검토
- security-auditor로 의존성 취약점 확인
- test-coverage-analyzer로 테스트 누락 영역 분석
메인 대화에서 띄운 subagent는 기본적으로 백그라운드에서 실행됩니다. Claude는 기다리지 않고 작업을 이어가다가, 각 subagent가 끝날 때 알림으로 결과를 받습니다. 한 세션에서 동시에 실행되는 subagent는 기본 20개이며 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS로 바꿀 수 있습니다.
fork와 중첩 실행
- fork — 새 컨텍스트로 시작하는 대신 부모 대화를 그대로 이어받는 subagent입니다. 기본으로 켜져 있으며
CLAUDE_CODE_FORK_SUBAGENT=0으로 끌 수 있습니다. - 중첩 — subagent는 다시 자기 subagent를 띄울 수 있으며, 기본으로 메인 대화 아래 3단계까지 허용됩니다.
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1로 설정하면 중첩을 끕니다.
적합한 작업 vs 부적합한 작업
| 적합 | 부적합 |
|---|---|
| 코드 리뷰 (독립 시각) | 메인 작업의 다음 단계 |
| 광범위한 검색, 탐색 | 사용자와 상호작용 필요 |
| 보안, 성능 감사 | 진행 상태 공유 필요 |
| 여러 영역 동시 분석 | 짧고 단순한 질문 |
| 긴 결과를 메인 컨텍스트에서 격리 | 메인의 의사결정에 즉시 반영 |
좋은 description 작성
자동 호출되려면 description이 정확해야 합니다.
좋은 예
description: |
Use after writing or modifying code in a logical chunk
(a feature, a bugfix, a refactor) to review the change against
the original plan and project coding standards. Reports
high-confidence issues only.
나쁜 예
description: Reviews code # 너무 일반적, 트리거 조건 모호
도구 권한 제한
tools 필드로 Subagent가 사용할 수 있는 도구를 제한합니다.
tools: Read, Grep, Glob # 읽기 전용 — 코드 변경 불가
리뷰, 감사 에이전트는 보통 읽기 전용으로 제한하는 것이 안전합니다. 상속받은 도구 중 일부만 빼려면 disallowedTools를 사용합니다.
실전 사용 패턴
패턴 1: 메인 컨텍스트 보호
긴 검색 결과나 로그가 필요하면 Subagent로 위임 후 요약만 받습니다. Explore는 코드베이스 검색과 분석에 쓰는 내장 읽기 전용 subagent입니다.
Explore 에이전트로 'authentication' 키워드를 src/ 전체에서 찾고, 발견 위치와 패턴을 200자 이내로 요약해줘
패턴 2: 독립 검토
자체 작업을 자체 평가하면 편향이 생깁니다. Subagent에게 “독립 시각으로 검토”를 요청합니다.
code-reviewer 에이전트로 방금 변경한 마이그레이션이 안전한지 독립 검토. 내 분석에 동의하지 말고 자체 판단으로.
패턴 3: 병렬 분석
다음을 병렬로:
- agent-A로 X
- agent-B로 Y
- agent-C로 Z
다음 단계
- Superpowers — subagent-driven-development, dispatching-parallel-agents 등 subagent를 활용하는 스킬 포함 (
superpowers:code-reviewer에이전트는 v5.1.0에서 제거됨) - Code Review, PR Review — 검토 전용 에이전트 모음
- Skill 직접 만들기 — Subagent 호출을 Skill로 표준화하는 패턴
- Subagent 공식 문서 — frontmatter 필드 전체 목록과 최신 동작