오전에는 새 기능을 만들고, 오후에는 코드 리뷰를 하고, 저녁에는 보안 점검을, 밤늦게는 테스트를 돌린다. 각각의 작업은 서로 다른 전문 지식을 요구한다. 인테리어를 한 사람이 디자인부터 전기, 타일까지 모두 맡으면 어느 하나도 제대로 끝나지 않듯, Claude Code에 모든 관점을 동시에 요구하면 컨텍스트가 꼬여 어느 것도 깊이 다루지 못한다. Claude Code는 이 문제를 서브에이전트(subagent)로 풀어낸다. 이 글에서는 서브에이전트가 무엇이고, 왜 메인 컨텍스트를 지키는 가장 빠른 방법인지, 어떻게 만들고 호출하는지를 정리한다
서브에이전트가 해결하는 문제
긴 대화는 반드시 오염된다. 처음에는 React 컴포넌트 최적화로 시작했는데 중간에 DB 쿼리 성능, 마지막에는 CSS 이슈까지 섞이면 모델도 사람도 핵심 목표에서 멀어진다. 메인 컨텍스트가 무거워질수록 응답 품질이 떨어지고 토큰이 빠르게 소진된다
서브에이전트는 이 문제를 두 축으로 해결한다
- 작업별 전문화: 코드 리뷰, 보안 점검, 디버깅 등 각 작업에 특화된 시스템 프롬프트와 도구 권한을 가진 전문가를 따로 둔다
- 컨텍스트 분리: 서브에이전트는 자기만의 컨텍스트 윈도우에서 작업하고, 결과 요약만 메인 대화에 돌려준다. 메인 대화는 깨끗하게 유지된다
공식 문서가 서브에이전트의 첫 번째 용도로 컨텍스트 보존을 꼽는 것도 같은 이유다
내장 서브에이전트 세 가지부터 알아둔다
Claude Code는 사용자가 따로 만들지 않아도 자동으로 활용하는 내장 서브에이전트를 제공한다. 직접 만들기 전에 이 셋의 역할을 알아두면 어느 시점에 커스텀이 필요한지 판단하기 쉽다
| 이름 | 모델 | 도구 | 용도 |
|---|---|---|---|
| Explore | Haiku | 읽기 전용 | 코드베이스 검색·탐색 |
| Plan | 상속 | 읽기 전용 | plan mode에서 사전 조사 |
| General-purpose | 상속 | 모든 도구 | 탐색·수정이 모두 필요한 다단계 작업 |
Explore는 빠른 검색에 최적화되어 있어 변경 없는 조회는 자동 위임된다. Plan은 plan mode에서만 동작한다. General-purpose는 가장 유능하지만 가장 비싸므로 작업 성격에 따라 선택적으로 호출된다
/agents 명령으로 서브에이전트를 만든다
/agents 명령은 서브에이전트 생성·관리 인터페이스를 연다. 흐름은 단순하다
/agents
└── Library 탭 → Create new agent
├── 위치 선택 (Project / Personal)
├── 생성 방법 (Generate with Claude / Manual)
├── 설명 입력 (예: "코드 구현 후 자동 리뷰하는 에이전트")
├── 도구 선택
├── 모델 선택 (Sonnet / Opus / Haiku / inherit)
└── 색상 지정 → 저장
공식 문서는 처음에는 Generate with Claude로 초안을 만든 뒤 필요한 부분만 수정하는 방식을 권장한다. 짧은 설명만 입력해도 검토 항목, 피드백 구조, 우선순위 가이드가 포함된 시스템 프롬프트가 만들어진다
생성된 파일은 마크다운으로 다음 위치에 저장된다
.claude/agents/code-reviewer.md # 프로젝트 전용 ~/.claude/agents/code-reviewer.md # 모든 프로젝트 공통
frontmatter로 서브에이전트의 동작을 제어한다
서브에이전트 파일은 YAML frontmatter와 마크다운 본문으로 구성된다. 본문이 시스템 프롬프트가 된다
--- name: code-reviewer description: 코드 변경 직후 품질·보안·가독성을 검토. 적극 사용할 것. tools: Read, Grep, Glob, Bash model: sonnet color: yellow --- 당신은 시니어 코드 리뷰어다. 호출되면 git diff부터 확인하고 수정된 파일에 집중한다. ...
자주 쓰는 frontmatter 필드는 다음과 같다
| 필드 | 역할 |
|---|---|
name, description | 필수. 위임 판단의 핵심 근거 |
tools | 허용 도구 목록 (생략 시 모두 상속) |
disallowedTools | 거부 도구 목록 |
model | sonnet/opus/haiku/inherit 또는 전체 모델 ID |
permissionMode | default/acceptEdits/auto/plan 등 |
mcpServers | 이 서브에이전트만 접근하는 MCP 서버 |
skills | 시작 시 컨텍스트에 미리 주입할 skill 목록 |
memory | user/project/local — 대화 간 학습 누적 |
isolation | worktree 지정 시 별도 git worktree에서 실행 |
hooks | 이 서브에이전트 라이프사이클 한정 hook |
description에 “use proactively” 또는 “must be used” 같은 문구를 넣으면 Claude가 더 능동적으로 위임한다. 한국어 환경에서도 영문 키워드가 트리거 신호로 효과적이다
저장 위치가 적용 범위와 우선순위를 결정한다
같은 이름의 서브에이전트가 여러 위치에 있으면 우선순위가 높은 정의가 이긴다
| 위치 | 범위 | 우선순위 |
|---|---|---|
| 관리되는 설정 | 조직 전체 | 1 (최고) |
--agents CLI 플래그 | 현재 세션 | 2 |
.claude/agents/ | 프로젝트 | 3 |
~/.claude/agents/ | 사용자 전체 | 4 |
플러그인 agents/ | 플러그인 활성 시 | 5 (최저) |
팀이 공유해야 할 워크플로우는 .claude/agents/에 두고 Git에 커밋한다. 개인 단축은 ~/.claude/agents/에 둔다. 일회성 자동화 스크립트라면 --agents 플래그로 JSON을 직접 전달한다
호출 방법 세 가지 – 자동, 명시, 세션 전체
서브에이전트를 호출하는 방식은 강도에 따라 셋으로 나뉜다
첫째, 자동 위임. Claude가 사용자 요청과 각 서브에이전트의 description을 비교해 적합한 에이전트에 작업을 자동으로 넘긴다. 별도 문법은 없다
"인증 모듈 코드 리뷰해줘" → Claude가 code-reviewer를 자동 호출
둘째, 명시적 호출. 자연어로 이름을 부르거나 @-mention으로 강제한다
Use the code-reviewer agent to look at the auth changes @code-reviewer (agent) 인증 모듈을 검토해줘
셋째, 세션 전체를 특정 서브에이전트로 시작. 메인 스레드 자체가 그 서브에이전트의 시스템 프롬프트, 도구 제한, 모델을 그대로 받는다
claude --agent code-reviewer
.claude/settings.json에 "agent": "code-reviewer"를 두면 프로젝트 기본값으로 적용된다
컨텍스트 보존이 가장 큰 이점이다
서브에이전트의 이점은 네 가지로 정리되지만 — 유연한 권한, 재사용성, 도메인 전문성, 컨텍스트 보존 — 본질은 마지막이다. 서브에이전트는 자체 컨텍스트에서 작업하고 요약만 돌려준다
[메인 대화] │ "유튜브 API + 결제 + 신규 기능 구현" │ ├──▶ youtube-expert (서브에이전트) │ │ API 문서 분석, 인풋·아웃풋 정리 │ └──▶ 요약만 반환: "필요한 엔드포인트 3개와 스펙" │ ├──▶ payment-expert (서브에이전트) │ │ 결제 흐름 분석, 검증 항목 점검 │ └──▶ 요약만 반환: "결제 검증 체크리스트" ▼ [메인 대화]는 핵심 설계와 구현에만 집중
이 분리 덕분에 메인 컨텍스트는 핵심 목표에만 토큰을 쓰고, 세션을 더 길게 유지할 수 있다. 복잡한 기능 하나를 한 세션 안에 끝낼 가능성이 올라간다는 뜻이다
권한 분리도 같은 맥락에서 효과를 낸다. 코드 리뷰어에는 Read, Grep, Glob만 부여해 실수로 파일을 수정하는 사고를 차단한다. DB 조회 전용 에이전트라면 permissionMode와 PreToolUse hook으로 SELECT만 허용하게 만든다
Anthropic이 권장하는 활용 패턴
공식 문서는 서브에이전트를 가장 효과적으로 쓰는 시점과 패턴을 네 가지로 정리한다
첫째, 탐색 단계 우선 활용. Anthropic이 검증한 워크플로우는 탐색 → 계획 → 구현 → 커밋 순으로 흐른다. 탐색 단계에서 도메인 정보를 모을 때 서브에이전트를 쓰면 메인 컨텍스트를 비워둔 채 깊이 있는 조사를 할 수 있다
둘째, 대량 출력 격리. 테스트 실행, 로그 분석, 문서 가져오기처럼 출력이 많은 작업은 서브에이전트로 격리해 결론만 받는다
"테스트 스위트를 서브에이전트로 돌리고, 실패한 항목과 에러 메시지만 보고해줘"
셋째, 병렬 연구. 독립적인 조사 영역이 여러 개라면 서브에이전트를 동시에 띄운다
"인증, DB, API 모듈을 각각 별도 서브에이전트로 동시에 조사해줘"
넷째, 서브에이전트 체이닝. 한 에이전트의 출력을 다음 에이전트의 입력으로 넘겨 단계별 워크플로우를 구성한다
"code-analyzer로 성능 문제를 찾고, 그 결과를 optimizer에게 넘겨 수정해줘"
정리
정리하면 서브에이전트는 작업을 전문가에게 위임하는 동시에 메인 컨텍스트 오염을 차단하는 도구다. 복잡한 작업을 길게 끌고 가야 한다면 메인 대화에서 모든 것을 처리하지 말고 서브에이전트에게 도메인별로 잘라 맡기는 것이 가장 빠른 품질 개선이다