Subagent가 해결하는 문제
긴 세션에서 다음 같은 비효율이 발생합니다:
- 검색 결과·로그 출력이 메인 컨텍스트를 채워 토큰 예산 잠식
- 코드 리뷰처럼 다른 시각이 필요한 작업을 메인 에이전트가 그대로 자체 평가 (편향)
- 독립적 작업들을 순차 처리하느라 시간 낭비
Subagent는 독립 컨텍스트로 분리된 보조 에이전트입니다. 결과만 메인에 돌려주므로 컨텍스트가 깨끗하게 유지되고, 병렬 실행도 가능합니다.
Subagent 정의
~/.claude/agents/<agent-name>.md 또는 플러그인 내 agents/<agent-name>.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 | 자동 호출 조건 (Skill의 description과 같은 역할) |
tools | 이 에이전트가 사용 가능한 도구 (없으면 메인과 동일) |
model | sonnet, opus, haiku 중 선택 (없으면 메인과 동일) |
호출 방식
자동 호출
description에 명시된 조건에 맞으면 메인 에이전트가 자동으로 Agent 도구를 호출합니다.
명시적 호출
code-reviewer 에이전트로 src/auth/ 디렉토리 검토해줘병렬 실행
한 메시지에서 여러 Agent 호출을 보내면 병렬 실행됩니다.
다음을 병렬로:
- code-reviewer로 src/auth/ 검토
- security-auditor로 의존성 취약점 확인
- test-coverage-analyzer로 테스트 누락 영역 분석세 작업이 동시에 실행되어 결과를 한 번에 받습니다.
적합한 작업 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 # 읽기 전용 — 코드 변경 불가리뷰·감사 에이전트는 보통 읽기 전용으로 제한하는 것이 안전합니다.
실전 사용 패턴
패턴 1: 메인 컨텍스트 보호
긴 검색 결과나 로그가 필요하면 Subagent로 위임 후 요약만 받습니다.
explore 에이전트로 'authentication' 키워드를 src/ 전체에서 찾고, 발견 위치와 패턴을 200자 이내로 요약해줘패턴 2: 독립 검토
자체 작업을 자체 평가하면 편향이 생깁니다. Subagent에게 “독립 시각으로 검토”를 요청합니다.
code-reviewer 에이전트로 방금 변경한 마이그레이션이 안전한지 독립 검토. 내 분석에 동의하지 말고 자체 판단으로.패턴 3: 병렬 분석
다음을 병렬로:
- agent-A로 X
- agent-B로 Y
- agent-C로 Z다음 단계
- Superpowers — code-reviewer 등 잘 설계된 에이전트 다수 포함
- Code Review, PR Review — 검토 전용 에이전트 모음
- Skill 직접 만들기 — Subagent 호출을 Skill로 표준화하는 패턴