Claude Code 서브에이전트(Subagents) 완벽 가이드 2026

서브에이전트가 해결하는 진짜 문제: 컨텍스트 오염

Claude Code로 큰 코드베이스를 다뤄본 사람이라면 한 번쯤 겪는 일이 있습니다. "이 함수가 어디서 호출되는지 전부 찾아줘" 같은 광범위한 탐색을 시키면, Claude가 수십 개의 파일을 열어 읽으면서 컨텍스트 윈도우가 순식간에 채워집니다. 정작 본 작업을 시작하기도 전에 컨텍스트가 탐색 과정의 부산물로 가득 차버리는 것입니다. 이것이 바로 컨텍스트 오염(context pollution) 문제입니다.

서브에이전트는 이 문제를 정공법으로 해결합니다. 메인 에이전트가 무거운 탐색을 직접 하는 대신, 별도의 서브에이전트에게 "전부 찾아서 결론만 가져와"라고 위임합니다. 서브에이전트는 자신만의 독립된 컨텍스트에서 50개 파일을 열든 100개 파일을 읽든 자유롭게 탐색하지만, 메인 에이전트에게는 정리된 최종 답변 한 덩어리만 돌려줍니다. 탐색에 쓴 수만 토큰은 서브에이전트의 컨텍스트와 함께 사라지고, 메인 컨텍스트는 깨끗하게 유지됩니다.

서브에이전트의 동작 방식

Claude Code에서 서브에이전트는 Task 도구(에이전트 도구)를 통해 호출됩니다. 자세한 사양은 Anthropic 공식 서브에이전트 문서에서 확인할 수 있습니다. 동작 흐름은 다음과 같습니다.

1. 메인 에이전트가 작업을 판단해 Task 도구를 호출하며, 서브에이전트 유형과 구체적인 지시를 전달합니다.
2. 서브에이전트가 새로운 빈 컨텍스트에서 시작해, 자신에게 주어진 도구로 작업을 수행합니다.
3. 작업이 끝나면 서브에이전트는 마지막 응답 텍스트를 메인 에이전트에게 결과로 반환합니다.
4. 메인 에이전트는 그 결과 텍스트만 받아 다음 단계를 이어갑니다. 서브에이전트의 중간 대화는 메인에 보이지 않습니다.

여기서 가장 중요한 특성은 "서브에이전트의 최종 메시지가 곧 반환값"이라는 점입니다. 서브에이전트는 사람에게 말을 거는 것이 아니라 메인 에이전트에게 데이터를 돌려주는 함수처럼 동작합니다. 그래서 서브에이전트에게 작업을 줄 때는 "무엇을 조사하고, 무엇을 결과로 돌려줄지"를 명확히 지정하는 것이 품질을 좌우합니다.

내장 서브에이전트 유형

커스텀 에이전트를 만들기 전에, Claude Code가 기본 제공하는 유형부터 이해하는 것이 좋습니다.

Explore 유형은 특히 유용합니다. "이 기능이 어디에 구현돼 있는지 찾아줘" 같은 요청에서, 전체 파일을 메인 컨텍스트로 끌어오지 않고 발췌만 읽어 위치와 결론만 보고합니다. 코드를 찾는 데는 강하지만 코드를 감사·검토하는 용도는 아니라는 점을 기억하세요.

커스텀 서브에이전트 만들기

같은 역할을 반복적으로 위임한다면, 커스텀 서브에이전트로 정의해두는 것이 효율적입니다. 프로젝트 단위는 .claude/agents/, 사용자 전역은 ~/.claude/agents/ 폴더에 마크다운 파일을 만듭니다.

기본 구조

다음은 코드 리뷰 전용 서브에이전트의 예시입니다. .claude/agents/code-reviewer.md 파일을 만듭니다.

---
name: code-reviewer
description: 코드 변경을 검토할 때 사용. 버그·보안·가독성 위주로 본다.
tools: Read, Grep, Glob
model: sonnet
---

당신은 꼼꼼한 시니어 코드 리뷰어입니다.
주어진 변경 사항을 다음 기준으로 검토하세요.

1. 정확성 — 로직 오류, 엣지 케이스 누락
2. 보안 — 입력 검증, 인젝션, 비밀값 노출
3. 가독성 — 명명, 중복, 과도한 복잡도

스타일 취향이 아니라 실제 문제만 보고하세요.
각 지적에는 파일:줄 위치와 수정 제안을 함께 제시하세요.

프런트매터 필드

/agents 명령으로 관리하기

파일을 직접 만들지 않고도, 대화창에서 /agents 명령을 실행하면 서브에이전트를 대화형으로 생성·수정·삭제할 수 있습니다. 사용 가능한 에이전트 목록과 각 에이전트의 도구 권한도 여기서 확인됩니다. 다른 내장 명령은 공식 슬래시 명령어 문서에서 함께 볼 수 있습니다.

병렬 실행: 서브에이전트의 가장 큰 무기

서브에이전트의 진짜 위력은 병렬 실행에서 나옵니다. 메인 에이전트가 한 번의 응답에서 여러 Task 도구를 동시에 호출하면, 서브에이전트들이 동시에 작동합니다.

예를 들어 "프런트엔드·백엔드·인프라 세 디렉터리에서 각각 인증 관련 코드를 찾아줘"라는 작업은, 세 개의 Explore 서브에이전트를 동시에 띄워 처리할 수 있습니다. 순차로 하면 세 작업 시간의 합이 걸리지만, 병렬로 하면 가장 오래 걸리는 한 작업 시간만으로 끝납니다.

단, 병렬화가 의미 있으려면 작업들이 서로 독립적이어야 합니다. B 작업이 A 작업의 결과를 필요로 한다면 병렬이 아니라 순차로 처리해야 하며, 이 경우 메인 에이전트가 흐름을 직접 조율합니다.

언제 쓰고, 언제 쓰지 말아야 하나

서브에이전트는 강력하지만 만능은 아닙니다. 잘못 쓰면 오히려 느리고 토큰만 낭비합니다.

써야 할 때

• 광범위한 탐색 — 여러 파일·디렉터리를 훑어 결론만 필요할 때
• 병렬 가능한 독립 작업 — 서로 의존하지 않는 여러 조사를 동시에
• 컨텍스트 격리가 필요한 대량 읽기 — 로그·대형 파일을 읽되 메인을 오염시키고 싶지 않을 때
• 반복되는 전문 역할 — 리뷰·테스트·문서화 등 정형화된 작업

쓰지 말아야 할 때

• 이미 위치를 아는 단순 조회 — 파일·심볼·값을 알면 직접 처리가 빠르다
• 과정을 직접 봐야 하는 작업 — 서브에이전트는 결론만 돌려주므로 단계별 검토에는 부적합
• 긴밀하게 의존적인 연속 작업 — 매 단계가 직전 결과에 묶여 있으면 격리가 오히려 방해

실전 패턴 3가지

1. 탐색 → 계획 분리

큰 기능을 구현하기 전에, Explore 서브에이전트로 관련 코드를 모두 찾아 지도를 그리게 한 뒤, 그 결론만 받아 메인에서 계획을 세웁니다. 탐색 토큰이 계획 단계의 컨텍스트를 차지하지 않아, 더 긴 작업을 안정적으로 이어갈 수 있습니다.

2. 병렬 다각도 리뷰

하나의 변경 사항을 버그·보안·성능 세 관점의 서브에이전트에게 동시에 검토시키고, 결과를 합쳐 우선순위를 정합니다. 단일 리뷰보다 사각지대가 줄어들고, 병렬이라 시간도 절약됩니다.

3. 권한 최소화 탐색 에이전트

코드베이스를 읽기만 해야 하는 조사 작업에는 tools: Read, Grep, Glob만 부여한 전용 에이전트를 씁니다. 쓰기·실행 도구를 아예 주지 않아, 조사 중 실수로 파일을 바꾸는 사고를 원천 차단합니다.

서브에이전트를 잘 쓰는 개발자와 못 쓰는 개발자의 차이는 "얼마나 많이 띄우느냐"가 아니라 "무엇을 격리하고 무엇을 병렬화할지 아느냐"에 있습니다. 컨텍스트를 자원으로 보는 순간, 서브에이전트는 선택이 아니라 필수가 됩니다.

관련 리소스