Claude Code 서브에이전트 완전정복 — 전문 AI 여러 개로 병렬 작업

 

Claude Code를 쓰다 보면 대화가 검색 결과·로그·읽은 파일로 금세 꽉 차 느려지고 헷갈리죠. 해법이 서브에이전트(subagents)입니다. 코드 리뷰·탐색·테스트 같은 일을 각자 격리된 컨텍스트에서 병렬로 처리하는 전문 AI 팀을 붙이는 기능이에요. 개념부터 만드는 법까지 정리합니다. (심화편이니 dynamic workflows /109도 참고)

📌 30초 요약

✓ 서브에이전트 = 격리된 컨텍스트에서 도는 전문 AI
✓ 이점: 메인 대화 안 더럽힘 · 전문화 · 병렬 속도 · 도구 격리
✓ 만들기: .claude/agents/에 md 파일 or /agents 명령
💡 메인은 Opus, 서브는 Sonnet·Haiku로 비용 절감

서브에이전트가 뭔가요?

서브에이전트는 메인 대화와 별개로, 자기만의 컨텍스트 윈도우에서 도는 전문 AI예요. 핵심은 격리. 서브에이전트는 내 대화 기록도, 메인이 읽은 파일도 보지 않고 백지에서 시작해, 맡은 일만 하고 결과 요약만 돌려줍니다.

💡 서브에이전트가 실행한 모든 중간 과정(도구 호출·읽은 파일·테스트 로그)은 그 안에 갇혀 있고, 오직 최종 요약만 메인 대화로 넘어와요. 그래서 메인이 안 더러워집니다.

왜 쓰나 — 4가지 이점

컨텍스트 절약	방대한 검색·로그를 서브가 처리하고 요약만 반환 → 메인이 오래 또렷
전문화	역할별 시스템 프롬프트로 "코드 리뷰 전담"처럼 집중
병렬 속도	독립적인 여러 작업을 동시에 굴려 시간 단축
도구 격리(안전)	리뷰 에이전트는 읽기만, 문서 에이전트는 셸 금지 — 사고 방지

만드는 법

두 가지 방법이 있어요.

① 대화형 — 가장 쉬움: 세션에서 /agents 명령을 실행하면 안내에 따라 만들 수 있어요. 처음이라면 이 방법을 추천.

② 파일로 직접: .claude/agents/(프로젝트) 또는 ~/.claude/agents/(전역)에 마크다운 파일을 두면 됩니다. YAML 머리말에 이름·설명·도구를, 본문에 역할(시스템 프롬프트)을 적어요.

---
name: code-reviewer
description: 코드 변경을 검토하는 리뷰 전담. 코드 작성 후 사용.
tools: Read, Grep, Glob
---

너는 시니어 코드 리뷰어다. 변경된 코드를 읽고
버그·보안 취약점·가독성 문제를 심각도와 함께 지적하라.
파일 수정은 하지 말고, 발견 사항만 요약해 보고하라.

description이 중요해요 — Claude가 이 설명을 보고 언제 이 에이전트에게 맡길지 자동 판단합니다. "코드 작성 후 사용"처럼 호출 시점을 적어두면 알아서 위임해요. 물론 이름으로 직접 호출도 됩니다.

💡 tools 팁 — 안 적으면 기본 도구를 상속해요. tools에 필요한 것만 적으면 그 에이전트는 딱 그 도구만 씁니다(리뷰용은 Read·Grep만 → 실수로 파일 못 건드림).

이런 에이전트가 유용해요

🔍 탐색(explore)	"이 기능 어디 있지?"를 대신 뒤져 위치만 요약 (검색 로그로 메인 안 채움)
✅ 코드 리뷰	읽기 도구만 줘서 안전하게 버그·취약점 지적
🧪 테스트	테스트 실행·로그 분석을 격리해 처리하고 결과만 보고
📝 문서	셸 도구는 빼고 문서 작성에만 집중

모델로 비용 아끼기

서브에이전트의 숨은 강점은 비용 최적화예요. 메인 세션은 Opus로 어려운 판단을 맡기고, 서브에이전트는 Sonnet·Haiku로 잘 정의된 작업을 처리하면 품질은 지키면서 비용을 크게 줄일 수 있습니다.

환경변수 CLAUDE_CODE_SUBAGENT_MODEL로 서브에이전트 기본 모델을 지정할 수 있어요. 단순 탐색·포맷 같은 대량·저난도 작업은 Haiku로 돌리면 특히 이득.

병렬 실행 & 중첩

서로 의존하지 않는 작업이라면 여러 서브에이전트를 동시에 띄워요. 예를 들어 "프론트·백엔드·DB를 각각 조사"를 병렬로 굴리면 시간이 확 줄죠. 또 최신 버전에선 서브에이전트가 자기 서브에이전트를 다시 스폰하는 중첩도 되는데, 이때도 최상위 요약만 나에게 돌아옵니다.

핵심 한 줄

더러운 일은 서브에게
메인 대화는 깨끗하게

전문화 · 병렬 · 도구 격리 · 비용 절감을 한 번에

⚠️ 이건 알아두세요

서브에이전트는 메인 맥락을 못 봐요. 그래서 위임할 때 필요한 정보를 프롬프트에 명확히 담아야 합니다("어떤 파일을, 무슨 기준으로"). 또 스킬(skills)은 자동 상속되지 않아, 필요하면 머리말에 명시해야 해요. 너무 잘게 쪼개면 오히려 위임 오버헤드가 커지니 균형이 중요합니다.

자주 묻는 질문 (FAQ)

Q. 서브에이전트와 그냥 대화, 뭐가 다른가요?

일반 대화는 모든 게 한 컨텍스트에 쌓여요. 서브에이전트는 격리된 곳에서 처리하고 요약만 주니, 메인이 안 무거워지고 병렬도 됩니다.

Q. 스킬(Skill)·MCP와는 어떻게 다른가요?

MCP는 도구 연결, 스킬은 작업 절차서, 서브에이전트는 일을 대신할 전문 일꾼이에요. (차이는 Skill vs MCP /94)

Q. 초보도 써도 되나요?

네. /agents 명령으로 안내받아 하나 만들어보면 감이 와요. "코드 리뷰 에이전트"부터 시작하는 걸 추천합니다.

마치며

서브에이전트는 Claude Code를 "혼자 하는 AI"에서 "팀을 지휘하는 AI"로 바꿔줍니다. 컨텍스트는 아끼고, 속도는 올리고, 사고는 막고, 비용까지 줄이죠.

오늘 /agents로 코드 리뷰 에이전트 하나만 만들어 보세요. 규칙을 알려주는 CLAUDE.md /76, 자동화 훅 Hooks /112와 함께 쓰면 Claude Code가 완전히 달라져요 🚀

---

🔗 공식 문서 — Claude Code Subagents (code.claude.com)

※ 본 글은 Claude Code 공식 문서와 2026년 활용 가이드를 바탕으로 작성했습니다. 명령·환경변수·중첩 지원 등 세부 사양은 Claude Code 버전에 따라 다를 수 있어요.