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로 표준화하는 패턴
자주 묻는 질문
Subagent는 무엇인가요?
메인 대화에서 분리된 별도 컨텍스트로 실행되는 보조 에이전트입니다. 독립된 작업·검색·검토를 위임하면 메인 컨텍스트를 깨끗하게 유지할 수 있고, 여러 에이전트를 병렬로 실행해 작업 시간도 줄어듭니다.
언제 Subagent를 써야 하나요?
독립적이고 결과만 받으면 되는 작업(코드 리뷰, 광범위한 검색, 보안 감사)에 적합합니다. 반대로 메인 컨텍스트의 진행 상태가 필요한 협업 작업은 메인에서 직접 하는 것이 효율적입니다.
어떻게 정의하나요?
`~/.claude/agents/<agent-name>.md` 또는 플러그인 내 `agents/<agent-name>.md`로 만듭니다. frontmatter에 description(호출 조건), tools(사용 가능 도구), model(선택 모델)을 정의하고 본문에 시스템 프롬프트를 작성합니다.
여러 Subagent를 병렬 실행할 수 있나요?
네. 한 메시지에서 여러 Agent 도구 호출을 동시에 보내면 병렬 실행됩니다. 독립적인 검색·분석을 동시에 처리할 때 효과적입니다.
Subagent와 Plugin은 어떻게 다른가요?
Plugin은 슬래시 커맨드·훅·Skills를 묶은 패키지이고, Subagent는 그 안에 포함될 수도 있는 독립 실행 단위입니다. Plugin이 컨테이너라면 Subagent는 실행 가능한 작업자입니다.