Claude Code 서브에이전트 실전 — 조사·구현·검증을 나눠 맡기는 법

7월 30, 2026

Claude Code로 큰 작업을 시키다 보면 컨텍스트가 금방 지저분해진다. 코드베이스를 뒤지느라 읽어들인 파일 수십 개가 대화에 쌓이면, 정작 구현 단계에서 중요한 내용이 밀려나고 품질이 떨어진다. 이 문제를 구조적으로 푸는 기능이 서브에이전트(subagent)다. 이번 글에서는 서브에이전트가 뭔지, 어떻게 만드는지, 그리고 조사→구현→검증으로 역할을 나누는 실전 구성을 실제 사용 순서대로 정리한다.

서브에이전트가 뭔가 — 작업 위임 개념

서브에이전트는 메인 대화와 분리된 별도 컨텍스트에서 도는 보조 에이전트다. 메인 에이전트가 "이 조사를 해 와라"고 위임하면, 서브에이전트는 자기만의 깨끗한 컨텍스트에서 파일을 뒤지고 작업한 뒤 결과 요약만 메인에 보고한다. 중간에 읽은 파일 내용 수만 토큰은 서브에이전트 컨텍스트에서 소비되고 버려진다. 메인 대화는 결론만 받으니 깨끗하게 유지된다.

포인트는 세 가지다. 첫째, 컨텍스트가 독립이라 메인 대화가 오염되지 않는다. 둘째, 에이전트마다 시스템 프롬프트·허용 도구·모델을 다르게 지정할 수 있어 역할을 강제할 수 있다. 셋째, 독립적인 작업이라면 여러 서브에이전트를 병렬로 돌릴 수 있다.

만드는 법 — 파일 하나가 에이전트 하나

서브에이전트는 마크다운 파일로 정의한다. 프로젝트 전용이면 .claude/agents/ 폴더에, 모든 프로젝트에서 쓰려면 홈 디렉터리의 ~/.claude/agents/에 둔다. Claude Code 안에서 /agents 명령을 쓰면 대화형으로 만들 수도 있는데, 구조를 이해하려면 한 번은 손으로 써 보는 것이 좋다.

파일 형식은 YAML 프런트매터 + 본문이다. 예를 들어 코드 리뷰 담당은 이렇게 만든다. .claude/agents/code-reviewer.md:

---
name: code-reviewer
description: 코드 변경 직후 품질·버그·보안 관점 리뷰를 수행한다.
  코드를 수정한 뒤에는 반드시 이 에이전트를 사용할 것.
tools: Read, Grep, Glob, Bash
model: sonnet
---
너는 꼼꼼한 시니어 코드 리뷰어다.
변경된 부분을 중심으로 버그 가능성, 엣지 케이스 누락,
보안 문제를 찾고, 심각도 순으로 정리해 보고한다.
코드를 직접 수정하지 말고 지적만 하라.

name, description은 필수다. 특히 description이 자동 위임의 기준이 된다. 메인 에이전트는 이 설명을 읽고 "지금 이 작업을 위임할까"를 판단하므로, 언제 써야 하는지를 설명에 명시하는 것이 요령이다.
tools는 허용 도구 목록이다. 생략하면 메인과 같은 도구를 쓸 수 있다. 리뷰어에게 편집 도구를 빼는 식으로 역할을 강제할 수 있다.
model은 선택이다. 단순 조사는 가벼운 모델, 핵심 구현은 상위 모델로 나누면 비용을 아낄 수 있다.
프런트매터 아래 본문 전체가 그 에이전트의 시스템 프롬프트가 된다.

실전 구성 — 조사·구현·검증 3분할

내가 실제로 쓰는 기본 구성은 세 개다.

researcher(조사): tools: Read, Grep, Glob으로 읽기 전용. "관련 코드가 어디에 있고 어떤 구조인지 파일 경로와 함께 요약하라"는 프롬프트를 준다. 코드베이스가 클수록 효과가 크다.
implementer(구현): 편집·실행 도구까지 허용. 조사 결과를 받아 실제 코드를 수정한다. "요구된 범위 밖의 파일은 건드리지 말 것" 같은 규칙을 시스템 프롬프트에 박아 둔다.
verifier(검증): tools: Read, Bash. 테스트를 실행하고 결과를 보고하되 코드는 수정하지 못하게 한다. 구현한 쪽이 스스로 채점하지 않게 분리하는 것이 핵심이다.

사용할 때는 메인 대화에서 이렇게 흘러간다. 먼저 "researcher 서브에이전트로 결제 로직 구조를 조사해줘"라고 명시적으로 시키거나, description을 잘 써 뒀다면 그냥 작업을 지시해도 알아서 위임한다. 조사 요약이 돌아오면 그 요약을 근거로 구현을 지시하고, 끝나면 검증을 돌린다. 서로 의존이 없는 조사 작업(예: 프런트엔드 구조와 백엔드 구조를 각각 조사)은 병렬로 던질 수 있어 시간이 절약된다.

언제 좋은가 / 오히려 느려지는 경우

서브에이전트가 만능은 아니다. 위임에는 대가가 있다. 서브에이전트는 매번 깨끗한 컨텍스트에서 시작하므로 메인이 이미 아는 내용도 다시 파악해야 하고, 그만큼 시간과 토큰이 든다.

좋은 경우: 넓은 코드 탐색·조사처럼 과정은 길고 결론은 짧은 작업, 독립적인 작업의 병렬 처리, 메인 컨텍스트를 길게 유지해야 하는 장기 세션, 역할별 도구 제한이 필요한 경우.
피할 경우: 파일 한두 개 고치는 단순 작업(위임 오버헤드가 본작업보다 크다), 단계마다 사람 확인이 필요한 작업, 앞 단계 결과에 강하게 의존해 어차피 순차로만 진행되는 작업.

컨텍스트 관리와 비용

비용 관점에서 서브에이전트는 양날이다. 토큰 총량은 늘어난다. 각 서브에이전트가 시스템 프롬프트와 파일 읽기를 반복하기 때문이다. 대신 메인 컨텍스트가 길어지며 생기는 품질 저하와 재작업이 줄어서, 긴 세션 전체로 보면 이득인 경우가 많았다. 절충 요령은 두 가지다. 조사·요약처럼 난도가 낮은 역할에는 model을 가벼운 모델로 지정하고, 서브에이전트 프롬프트에 "결과는 파일 경로와 핵심 요약 위주로 간결하게 보고하라"를 넣어 보고서 길이를 통제하는 것이다.

주의점

서브에이전트끼리는 대화 맥락을 공유하지 않는다. 넘겨야 할 정보는 메인이 위임 지시문에 명시해야 한다.
description이 모호하면 자동 위임이 엉뚱하게 발동하거나 아예 안 된다. "언제 쓰라"를 문장으로 적는다.
에이전트를 너무 잘게 쪼개면 관리 비용이 커진다. 3~5개로 시작해서 실제로 반복 사용되는 것만 남기는 편이 낫다.
프로젝트 폴더의 .claude/agents/는 git으로 팀과 공유되므로, 팀 컨벤션에 맞는 프롬프트인지 확인하고 커밋한다.

※ 이 글의 서브에이전트 문법과 동작 방식은 2026년 기준이며 변경될 수 있습니다.

이 블로그 검색

에이븐스튜디오