서브 에이전트
기준일: 2026-07-13 난이도: 중급 공식 기준: Create custom subagents, Agents and parallel work
Subagent는 별도 context window에서 좁은 작업을 수행하고 결과를 호출한 세션에 돌려주는 전문 agent입니다. 메인 대화의 context를 불필요하게 키우지 않고 조사, 검토, 테스트처럼 경계가 분명한 일을 맡길 때 적합합니다.
핵심 개념
| 특성 | Subagent |
|---|---|
| Context | 메인 세션과 분리된 자체 context window |
| 통신 | 결과를 호출한 agent에 반환 |
| 정의 | YAML frontmatter와 Markdown 본문 |
| Project scope | .claude/agents/*.md |
| Personal scope | ~/.claude/agents/*.md |
| 일회성 정의 | claude --agents '<json>' |
현재 공식 문서상 v2.1.198부터 /agents는 interactive 생성 wizard를 열지 않습니다. Claude에게 파일 생성을 요청하거나 .claude/agents/를 직접 편집합니다.
선택 기준
- 짧고 독립된 결과만 필요하면 Subagent를 사용합니다.
- agent끼리 직접 소통하고 공유 task를 조정해야 하면 Agent Teams를 검토합니다.
- 여러 agent를 스크립트가 동적으로 생성·관리해야 하면 Dynamic workflows를 검토합니다.
- 같은 파일을 동시에 수정하는 작업은 병렬 위임하지 않습니다.
실습
프로젝트 전용 읽기 전용 reviewer를 정의합니다.
.claude/agents/test-reviewer.md
---
name: test-reviewer
description: 코드 변경의 회귀 위험과 테스트 누락을 검토합니다.
tools: Read, Grep, Glob
model: sonnet
---
변경된 동작과 관련 테스트를 검토하세요.
파일:줄 근거가 있는 발견만 심각도 순으로 보고하고,
코드를 수정하지 마세요.
그다음 자연어로 위임합니다.
test-reviewer subagent를 사용해 현재 변경의 테스트 누락을 검토해줘.
Subagent 파일은 현재 공식 문서에 정의된 frontmatter를 사용합니다. 재사용 orchestration을 위해 문서에 없는 별도 YAML registry를 만들지 않습니다.
도구에 입력할 프롬프트
이 작업을 subagent에 위임할 수 있는 독립 단위로 나눠줘.
각 단위에 필요한 파일 범위, 허용 tool, 결과 형식, 완료 조건을 적고,
같은 파일을 수정하는 단위는 병렬로 실행하지 마.
메인 세션에 필요한 결과만 요약해서 반환하게 해줘.
체크리스트
- Subagent에 좁고 검증 가능한 작업을 맡겼다.
-
description에 사용 시점을 구체적으로 적었다. - 필요한 tool만 허용했다.
- project와 personal scope를 올바르게 선택했다.
- 메인 대화 기록이 자동 상속되지 않는 점을 고려했다.
- 같은 파일을 여러 agent가 동시에 수정하지 않게 했다.
- 반환된 결과를 메인 세션에서 다시 검증했다.