Claude Code 서브에이전트 완전 가이드 — 개념부터 병렬 실행, 발동 안 될 때 대처까지

대규모 프로젝트에서 Claude Code에 파일 조사를 시키면, 닥치는 대로 파일을 읽어 들여 어느새 컨텍스트가 빵빵하게 차 버립니다. 금세 자동 컴팩트(auto-compact)가 돌아 성능이 떨어지는… 경험, 없으신가요?

이걸 해결하는 것이 서브에이전트입니다. 한마디로 하면, 메인과는 다른 컨텍스트에서 움직이는 Claude Code의 분신. 일을 맡기면 독립해서 작업하고, 마지막에 결과 요약만 돌려줍니다.

이 글에서는 서브에이전트의 개념 → 만드는 법 → 대화 형식으로 만들기 → 병렬 실행 → 발동하지 않을 때의 대처까지를 한 편에 정리했습니다.

이 글에서 알 수 있는 것

• 서브에이전트의 개념과, 왜 컨텍스트를 절약할 수 있는가
• 정의 파일(.claude/agents/)의 작성법과 주요 필드
• /agents 를 이용한 대화 형식 작성
• 커스텀 커맨드에서 여러 서브에이전트를 병렬로 호출하는 실전 패턴
• 서브에이전트가 의도대로 발동하지 않을 때의 대처법

제1장: 서브에이전트란(개념)

메인과는 독립된 "전문 팀"

평소 직접 말을 걸고 있는 Claude Code를 "메인"이라 하면, 서브에이전트는 복제된 독립 분신입니다. 조직으로 치면 메인이 프로젝트 매니저, 서브에이전트가 전문 팀에 해당해요.

PM이 "이 조사 좀 해 둬"라고 전문 팀에 넘기면, 팀은 독립해서 작업합니다. 그동안 PM은 지켜볼 필요가 없고, 중간 경과는 PM의 머릿속에서 잊힌다는 게 포인트. 작업이 끝나면 "파일은 여기 있었습니다", "이런 내용이었습니다"라는 요약만 돌아옵니다(조사뿐 아니라 파일 편집·삭제 같은 작업도 가능합니다).

왜 컨텍스트를 절약할 수 있는가

메인에서 직접 조사하면 읽어 들인 파일 정보가 과정으로 전부 남아, 조사 후에도 컨텍스트를 계속 압박합니다. 서브에이전트에 맡기면 과정은 메인에 남지 않고 요약만 남습니다.

어떤 장면에서 활약하는가

• 대규모 코드베이스 조사(대량의 파일 읽기)
• 여러 파일에 대한 병렬 편집(예: 테스트 커버리지 향상. 테스트마다 독립적이라 충돌하기 어렵다)
• 많은 코드를 읽고 문서를 만드는 작업

어느 것이든 대량의 읽고 쓰기로 컨텍스트를 압박하기 쉬운 태스크로, 독립 컨텍스트의 서브에이전트가 제 몫을 하는 자리입니다.

내장 서브에이전트

직접 만드는 것이 기본이지만, 처음부터 마련되어 있는 내장 서브에이전트도 있습니다. 자주 등장하는 것은 다음 3가지로, Claude가 태스크에 따라 자동으로 라우팅합니다(직접 호출하는 일은 드뭅니다).

내장의 종류는 버전에 따라 늘고 줍니다(claude-code-guide 처럼 Claude Code 자체의 사용법을 조사해 주는 것이 마련되어 있는 시기도 있습니다). 이것들은 의식하지 않아도 자동으로 쓰이니, 머리 한구석에 두는 정도면 충분해요.

주의점

1. 컨텍스트는 공유되지 않는다: 서브에이전트는 그때까지의 메인 대화를 모릅니다. "처음 불려 온 전문 팀"이니, 의뢰 내용과 배경을 명확히 전달해야 합니다.
2. 쓰기의 병렬은 충돌에 주의: 여러 서브에이전트가 같은 파일을 동시 편집하면 정합성이 무너집니다. 익숙해지기 전에는 읽기 전용(읽고 제안만 하는 것)부터 시작하는 걸 추천해요.
3. 토큰은 별도 과금이 아니지만 소비는 는다: 서브에이전트는 별도 과금이 아니고, 각자 독자적인 컨텍스트를 가지는 만큼 토큰 소비는 많아지기 쉽습니다(무겁게 쓰면 단일 스레드의 몇 배가 되기도). 컨텍스트를 절약하는 대신 토큰을 쓴다는 트레이드오프를 의식하세요.

제2장: 정의 파일 만드는 법

배치 장소

서브에이전트는 Markdown 파일로 정의하고, 두는 곳으로 스코프가 정해집니다.

동명이면 높은 우선도(프로젝트)가 이깁니다. /agents 커맨드로 목록을 확인합니다.

구조: 프론트매터 + 본문(=시스템 프롬프트)

커스텀 커맨드와 마찬가지로 YAML 프론트매터와 본문으로 구성됩니다. 본문은 서브에이전트의 시스템 프롬프트가 됩니다.

---
name: code-reviewer
description: 코드의 품질·보안·명명 규칙을 리뷰하는 전문 에이전트. 코드를 변경한 직후에 쓴다.
tools: Read, Grep, Glob
model: sonnet
---

당신은 코드 리뷰 전문가입니다. 대상 파일을 읽고, 명명 규칙·가독성·
보안·오류 처리 관점에서 리뷰해 주세요.
보고는 "중요 / 경고 / 제안"의 3단계로 정리해 주세요.

주요 필드

description이 생명

description 은 메인의 컨텍스트에 상주하며, Claude가 "이 서브에이전트를 불러야 하나"를 판단하는 재료가 됩니다. 애매하면 불리지 않아요. 언제·무엇을 하는지를 구체적으로 씁시다.

• 약한 예: "코드를 보는 에이전트"(발동 장면이 불명확)
• 좋은 예: "PR의 변경 사항(diff)을 읽고, 명명 규칙 위반과 보안 문제를 지적한다. 코드 변경 후에 쓴다"

model의 구분 사용

• 조사 중심 → haiku(고속·저비용)
• 리뷰 → sonnet(균형). 깊이 보고 싶거나 여유가 있으면 opus
• 평소 opus로 돌리고 있다 → inherit(호출한 쪽의 모델을 계승)

헷갈리면 "haiku 냐 그 외냐" 정도의 입자로 시작하면 충분합니다.

tools 를 생략하면 메인의 툴(MCP 포함)을 계승합니다. 읽기 전용으로 하고 싶은 리뷰계에서는 tools: Read, Grep, Glob 처럼 허가 리스트로 좁히는 것이 안전합니다.

제3장: 대화 형식으로 만들기(/agents)

YAML을 직접 쓰는 쪽이 커스터마이즈는 쉽지만, 익숙해지기 전에는 대화 형식이 편합니다.

1. /agents 를 실행하고 "신규 작성"을 고른다
2. 프로젝트인지 퍼스널(홈)인지 고른다
3. Generate with Claude(Claude에게 생성시키기)인지 Manual(수동)인지 고른다 → 대화 생성 추천
4. "보안 관점에서 리뷰하는 서브에이전트"처럼 대략 전달하면, 최적화된 description 과 본문을 Claude가 생성
5. 쓸 툴(읽기 전용 등), 모델, 표시 컬러를 골라 저장

이 방법의 이점은, 베스트 프랙티스를 몰라도 적절한 타이밍에 호출되는 description(발동 조건과 예시 포함)과, 역할·출력 포맷까지 만들어 넣은 본문이 자동으로 생성된다는 것. 익숙해지면 기존 서브에이전트를 밑틀 삼아 Claude에게 다른 것을 만들게 하는 방식도 효율적입니다.

제4장: 응용 — 커스텀 커맨드에서 병렬 호출

서브에이전트는 여러 개를 병렬로 동시 실행할 수 있습니다. 실전에서 자주 쓰는 것이, 커스텀 커맨드에서 여러 관점의 리뷰어를 한꺼번에 부르는 패턴입니다.

커스텀 커맨드 안에 "다음 3가지 전문 서브에이전트를 병렬로 기동하고, 각자의 관점으로 리뷰를 의뢰한다"라고 써 두면, 동시에 달려서 결과가 메인에 모입니다.

병렬시킬 거라면 "독립·읽기 전용"으로 설계한다 각 서브에이전트가 독립된 관점이고, 게다가 파일에 쓰지 않는다면 동시 실행해도 안전합니다. 하지만 "리뷰하고 수정까지 하는" 쓰기계를 병렬로 돌리면 같은 파일을 동시 편집해 정합성이 무너지기도 합니다. 실전에서는 리뷰 결과만 메인에 돌려주고, 수정은 메인에서 하는 2단계를 추천해요.

나아가 응용으로, 통합 역의 "부모 서브에이전트"를 만들고 거기서 자식 서브에이전트를 중첩으로 호출할 수도 있습니다(이 규모라면 커스텀 커맨드 안에서 충분히 감당되지만, 기법으로 알아 두면 활용의 폭이 넓어집니다).

제5장: 발동하지 않을 때의 대처

자동으로 부를지 말지는 거의 description 에 달려 있습니다. 불리지 않을 때는 description 개선이 기본. 4가지 대책을 챙깁시다.

마지막의 "명시적으로 호출한다"는 description 에 뭐라고 쓰여 있든 거의 확실히 발동하는 보험입니다. 프롬프트에 이름을 넣는 것 외에 @agent-name 멘션으로도 확실히 위임됩니다. 커스텀 커맨드에서 병렬로 서브에이전트를 부를 때 등 확실히 움직여야 하는 장면에서 자주 씁니다.

모든 서브에이전트에 proactively 를 쓰면 어느 것을 우선해야 할지 알 수 없게 됩니다. 잘 발동하지 않는 것만 description 을 재점검하며 키워드를 더하는 것이 요령입니다. 대화 형식 생성(/agents)에 맡겨서 좋은 description 작성법을 배우는 것도 유효해요.

정리: 서브에이전트 체크리스트

• 서브에이전트는 다른 컨텍스트에서 움직이는 분신. 돌아오는 것은 요약뿐
• 대규모 조사·병렬 편집·대량 읽고 쓰기 등 컨텍스트를 압박하는 작업에 알맞다
• 정의는 .claude/agents/(프로젝트) / ~/.claude/agents/(사용자)에 Markdown으로
• 프론트매터의 description 이 최중요. model 은 용도로 구분(조사=haiku 등)
• 읽기 전용으로 하려면 tools 를 허가 리스트로 좁힌다(disallowedTools 로 거부도 가능)
• 익숙해지기 전에는 /agents 의 대화 생성이 편하다. 쓰기 병렬은 충돌에 주의
• 발동하지 않으면 description 을 개선. 확실히 부르려면 이름 지정 / @agent-name
• 편리한 반면 토큰 소비는 늘기 쉽다. 절약과 비용의 트레이드오프를 의식

서브에이전트를 잘 다루면 메인의 컨텍스트를 어지럽히지 않고 대규모 작업을 맡길 수 있습니다. 우선은 읽기 전용 리뷰용 에이전트부터 만들어 보고, 익숙해지면 커스텀 커맨드와의 병렬 실행으로 발전시켜 보세요.