Claude Code 서브에이전트 실전 배치 — 역할 분리부터 병렬 3~5개 스윗스팟까지

서브에이전트를 만들긴 했는데 Claude가 위임을 안 하거나, 병렬로 돌리면 오히려 느려진 적이 있을 겁니다. 역할 분리를 잘못 잡으면 컨텍스트만 낭비하고 토큰 청구서만 늘어납니다.

Claude Code를 실무 코딩·리팩토링·리뷰에 써온 관점에서 배치 기준을 정리했습니다. 이 순서대로 가면 서브에이전트 배치가 손에 잡힙니다.

서브에이전트란 — 왜 메인 대화에 안 두나

Claude Code 서브에이전트는 별도 컨텍스트에서 돌고 결과 summary만 메인 대화로 반환하는 워커다. 메인 대화에서 파일 30개를 grep하면 그 결과가 전부 메인 컨텍스트를 채운다. 서브에이전트에 시키면 검색 과정은 격리된 곳에서 끝나고, 메인에는 "핵심 3개 파일" 한 줄만 돌아온다.

 

핵심은 이거다. 서브에이전트를 쓰는 이유는 병렬이 아니라 컨텍스트 절약이다. 리서치·대량 검색·긴 로그 분석처럼 중간 산출물이 큰 작업일수록 격리 효과가 크다. 결과가 짧은 한 줄 작업은 빼도 왕복 비용만 든다.

 

슬래시 커맨드와 헷갈리기 쉽다. 슬래시 커맨드는 내 대화에서 그대로 실행되는 프롬프트 매크로고, 서브에이전트는 별도 워커다. 반복 프롬프트를 줄이려면 커맨드, 컨텍스트를 격리하려면 서브에이전트를 쓴다.

배치 — .claude/agents 파일 하나로 정의

서브에이전트는 .claude/agents/ 아래 마크다운 파일 하나로 정의한다. 프론트매터에 메타데이터를 넣고, 본문이 그대로 시스템 프롬프트가 된다.

---
name: code-reviewer
description: 변경 후 품질·보안 점검. diff가 생기면 위임.
tools: Read, Grep, Glob
model: sonnet
---

당신은 코드 리뷰어입니다. 변경된 파일의 보안·성능·컨벤션을
점검하고 발견 사항만 요약해서 반환하세요. 파일은 수정하지 않습니다.

프론트매터 4개 필드만 기억하면 된다. name·description은 필수, tools·model은 선택이다. tools를 생략하면 전체 도구를 상속하고, model을 생략하면 메인 대화 모델을 상속한다.

 

핵심은 description이다. description이 위임 트리거라서, 여기가 모호하면 Claude가 Claude Code 서브에이전트를 안 부른다. "코드 리뷰 담당"처럼 뭉뚱그리지 말고 "변경 후 품질·보안 점검, diff가 생기면"처럼 언제 위임할지 조건을 박아야 자동 위임이 걸린다.

역할 분리 — 리서치·구현·리뷰·테스트로 나누기

역할은 4개면 실무 대부분이 커버된다. 하나가 다 하게 만들면 도구 권한이 넓어지고 컨텍스트가 뒤섞인다.

서브에이전트	description (위임 트리거)	tools	model	격리
리서치	코드베이스 검색·구조 파악	Read·Grep·Glob	haiku	불필요
구현	기능 구현·다단계 수정	전체	inherit	worktree 권장
리뷰	변경 후 품질·보안 점검	Read·Grep·Glob	sonnet	불필요 (읽기전용)
테스트	실패 테스트 재현·수정	Read·Bash·Edit	sonnet	worktree

분리의 실익은 모델 라우팅에서 나온다. 검색만 하는 리서치 워커는 model: haiku로 내리면 토큰 단가가 크게 떨어진다. 리뷰·테스트는 판단이 필요하니 sonnet을 준다. 읽기 전용인 리서치·리뷰는 tools를 Read·Grep·Glob로 좁혀두면 실수로 파일을 건드릴 일이 없다.

 

worktree 격리를 구현·테스트에만 붙이는 이유도 단순하다. 이 둘만 파일을 실제로 쓰기 때문이다. 자동 위임 습관은 Claude Code 활용법 정리에서 더 다뤘다.

병렬 3~5개 스윗스팟 — worktree 격리와 계층 상한

병렬은 Claude Code 서브에이전트가 서로 다른 파일을 건드릴 때만 이득이다. 같은 파일을 동시에 편집하면 충돌 나거나 마지막 쓰기가 앞을 덮는다. 이럴 땐 isolation: worktree로 각 워커를 별도 git worktree에 격리한다. 변경이 없으면 자동 정리된다.

병렬 개수에는 스윗스팟이 있다. 손으로 관리하는 실무 기준은 3~5개다. 그 이상은 어느 워커가 뭘 하는지 추적이 안 되고, 리뷰 부담이 병렬 이득을 잡아먹는다. 수십 개를 돌려야 하는 대규모 작업이면 /batch가 5~30개 worktree를 자동 관리하니 그쪽을 쓴다.

 

한 파일 빠른 수정에 병렬을 붙이는 건 overkill이다. worktree 만들고 정리하는 오버헤드가 수정보다 크다. 단일 파일 수정은 병렬 없이 메인에서 바로 하는 게 낫다.

 

계층 스폰도 상한이 있다. 서브에이전트가 다시 서브에이전트를 부르는 중첩은 depth 5가 고정 상한이라 그 아래로는 못 스폰한다. 무한 스폰을 막는 장치다. 역할당 1개 원칙이면 실무에선 depth 2~3에서 끝난다.

실패 사례 — 증상·원인·해결

Claude Code 서브에이전트를 배치하다 보면 세 가지가 자주 터진다.

증상 1: 서브에이전트를 만들었는데 Claude가 안 부른다.

원인: description이 모호해서 위임 트리거가 안 걸린다.

해결: "언제 위임할지" 조건을 명시한다. "리뷰 담당" → "변경 후 품질·보안 점검, diff 생기면".

증상 2: 병렬로 돌렸는데 더 느리고 토큰만 늘었다.

원인: 같은 파일을 여러 워커가 동시에 건드리거나, 빠른 단일 수정을 억지로 병렬화했다.

해결: 파일 단위로 파티셔닝하고 worktree로 격리한다. 단일 파일 수정은 병렬을 아예 안 쓴다.

증상 3: 서브에이전트가 과다 스폰되며 컨텍스트가 낭비된다.

원인: 중첩 위임을 남발했다.

해결: depth 5 상한을 인지하고, 역할당 1개 원칙을 지킨다.

Q&A — 자주 보는 질문 5개

Q. 서브에이전트와 슬래시 커맨드는 뭐가 다른가요?
A. 슬래시 커맨드는 내 대화에서 실행되는 프롬프트 매크로, 서브에이전트는 별도 컨텍스트에서 도는 워커입니다. 반복 프롬프트를 줄이려면 커맨드, 컨텍스트를 격리하려면 서브에이전트입니다.

Q. 에이전트 팀(Agent Teams)과는 다른 건가요?
A. 다릅니다. Agent Teams는 실험적 기능이고 기본 비활성이며 워커끼리 peer-to-peer로 협업합니다. 서브에이전트는 부모-자식 위임 구조라 흐름이 예측 가능합니다. 실무 배치는 서브에이전트가 먼저입니다.

Q. 서브에이전트마다 모델을 다르게 줄 수 있나요?
A. 됩니다. 프론트매터 model에 haiku·sonnet·opus를 지정하면 됩니다. 생략하면 메인 모델을 상속합니다. 검색만 하는 리서치 워커를 haiku로 내리면 토큰 단가가 크게 줄어듭니다.

Q. 파일 수정이 서로 안 잡히는데 어떻게 하나요?
A. 여러 워커가 같은 파일을 동시에 편집하면 마지막 쓰기가 앞을 덮습니다. isolation: worktree로 각 워커를 격리하고 파일 단위로 작업을 나누세요. 변경이 없으면 자동 정리됩니다.

Q. 서브에이전트를 몇 개까지 중첩할 수 있나요?
A. depth 5가 고정 상한입니다. 여기 도달하면 더는 스폰하지 못합니다. 역할당 1개 원칙을 지키면 실무에선 depth 2~3에서 끝납니다.

같은 환경이면 위 순서대로 따라가도 무리 없습니다.

📎 이 카테고리의 다른 글

• Claude Code 활용법 정리 — 망치는 습관 3개와 살리는 습관 7개 — 2026-04-26
• Claude Code 필수 설정 가이드 — 2026-03-20

같은 AI 활용법 카테고리에서 이어서 읽기

설치 환경: Windows 11, Node.js v24, Claude Code