Claude Code 서브에이전트 만들기 실전 가이드: 자동 위임·비용 절감 세팅까지

Claude Code 서브에이전트 한 줄 요약

claude code subagent는 .claude/agents/<name>.md 파일 하나로 붙일 수 있어요. 자동 위임을 노리면 description에 발동 조건을 적고, 단순 탐색은 model: haiku나 CLAUDE_CODE_SUBAGENT_MODEL=haiku로 분리하면 돼요. 2026년 4월 15일 기준 에이전트 팀은 아직 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1이 필요한 실험 기능이라, 대부분은 서브에이전트부터 잡는 쪽이 덜 헷갈리거든요.

서브에이전트 만들었는데 자동으로 안 불려서 한 시간 날렸어요. 파일은 맞게 놨고 이름도 멀쩡한데, 막상 Claude는 메인 세션에서 혼자 다 하려고 들더라고요. 그때 알게 된 게 있어요. claude code subagent는 파일 하나 만드는 걸로 끝나는 기능이 아니에요. description으로 라우팅 규칙을 잡아야 하고, 어떤 환경에서 돌릴지 정해야 하고, 비용이 새는 지점도 같이 봐야 하죠. 2026년 들어 공식 문서 기준 사용 환경이 CLI, 데스크톱, 웹, VS Code, JetBrains, 모바일 원격 제어, Slack, Chrome, CI/CD, SDK까지 넓어졌는데요, 이걸 한 번에 안 묶어두면 글이 금방 낡아요. 설치 자체가 아직이면 Claude Code 사용법: 설치부터 첫 실행까지 5분 가이드부터 보고 오는 편이 빨라요.

Claude Code 서브에이전트는 어디서 쓸 수 있을까

서브에이전트 개념은 하나인데, 쓰는 환경이 달라지면 진입 방식과 체감 포인트가 꽤 달라져요. 2026년 4월 15일 기준 공식 문서에 나온 사용 환경을 한 번에 보면 헷갈림이 많이 줄어요. 모바일에서 작업만 찍어두고 데스크톱으로 이어받는 흐름도 의외로 쓸만하거든요.

공식 지원 환경 10가지

사용 환경	공식 상태	서브에이전트 쓸 때 포인트	메모
CLI	기본 진입점	.claude/agents/, claude agents, --agent가 가장 단순해요	로컬 파일 접근이 편해요
Desktop App	정식	병렬 세션, 작업 패널, diff 보기 체감이 좋아요	macOS, Windows 지원
Web App	연구 미리보기	클라우드에서 오래 도는 작업 맡기기 좋아요	claude.ai/code 기준
VS Code	정식 확장	@ 문맥, 원격 세션 이어받기, 브라우저 연동이 편해요	에디터 중심 작업에 맞아요
JetBrains	정식 플러그인	선택 영역 공유, diff 보기, 진단 공유가 강점이에요	IntelliJ, PyCharm, WebStorm 등
Mobile App	보조 표면	작업 시작, 진행 확인, 원격 조종 쪽이 핵심이에요	직접 파일 세팅용은 아니에요
Slack	통합	채널에서 @Claude로 코딩 요청 보내고 웹 세션으로 넘겨요	DM은 안 돼요
Chrome 확장	통합	로그인 상태 브라우저로 테스트 자동화할 때 좋아요	VS Code와 같이 쓰면 편해요
CI/CD	통합	GitHub Actions, GitLab CI/CD에서 반복 검증 흐름 만들기 좋아요	대화형 디버깅과는 결이 달라요
SDK/API	공식 문서 있음	Claude Agent SDK에서 subagent를 코드로 정의할 수 있어요	앱 안에 내장할 때 봐야 해요

실무에서 먼저 잡을 두 가지

실무에서는 CLI나 VS Code부터 잡는 게 제일 덜 꼬여요. Slack, 모바일, 웹은 “시작하고 이어받는 표면”에 가깝고, SDK는 제품 안에 녹일 때 보는 문서라고 생각하면 편하거든요.

커스텀 서브에이전트 1분 세팅

프로젝트 전용 서브에이전트는 .claude/agents/ 아래 마크다운 하나면 시작돼요. 처음에는 역할 하나만 좁게 잡는 편이 덜 꼬여요. 이걸 왜 굳이 파일로 만들어야 할까요?

파일로 빼두면 같은 역할을 매번 다시 설명할 필요가 없어요. 팀이 같이 쓰는 규칙도 묶기 좋고요. 프로젝트 공유용이면 .claude/agents/, 개인 전역용이면 ~/.claude/agents/로 보면 됩니다.

체크할 건 딱 다섯 개예요.

• name: 소문자와 하이픈만
• description: 언제 불러야 하는지
• tools: 정말 필요한 것만
• model: haiku, sonnet, opus, inherit
• isolation: 병렬 편집이면 worktree

# 프로젝트 전용 폴더 만들기
mkdir -p .claude/agents

# 현재 잡히는 에이전트 보기
claude agents

# 출력 예시
# Project agents
# - code-reviewer

---
name: code-reviewer
description: Use proactively when Python or TypeScript files change in src/ or tests/
tools: Read, Grep, Glob, Bash
model: haiku
isolation: worktree
---

당신은 코드 리뷰 전용 서브에이전트예요.
변경 파일을 먼저 읽고, 위험한 문제부터 짧게 요약하세요.
수정 제안이 있으면 이유와 영향 범위를 같이 적으세요.

# 세션 다시 열고 등록 여부 체크
claude agents

# 출력 예시
# Project agents
# - code-reviewer

공식 문서는 /agents 인터페이스를 기본 진입으로 밀고 있어요. 그래도 손으로 파일을 하나 만들어보면 뭐가 발동 조건이고 뭐가 시스템 프롬프트인지 구조가 훨씬 빨리 보여요. MCP를 서브에이전트에만 따로 붙일 생각이면 MCP 서버 사용법: Claude Code 연결 가이드도 같이 보는 게 좋아요.

서브에이전트 자동 위임이 안 될 때

자동 위임은 description이 얼마나 구체적인지에 거의 달렸어요. 애매한 설명은 잘 안 불리고, 조건이 적힌 설명은 확률이 확 달라지더라고요. description 한 줄 바꿨는데 진짜 달라질까?

진짜 달라져요. 공식 문서도 description을 “언제 위임할지(delegate)”로 설명해요. 기능 소개 문장이 아니라 트리거 문장이라는 뜻이죠. 여기서 많이 막혀요. “코드 리뷰 전문가”처럼 쓰면 예쁘긴 한데, 정작 Claude가 언제 불러야 할지 모르거든요.

애매한 설명	더 나은 설명	왜 나은지
Code review expert	Use proactively after 3+ edits in src/ or when tests fail	발동 조건이 보여요
Security agent	Review auth, billing, and secret handling before commit	범위가 좁아요
Debugger	Investigate failing tests and summarize root cause first	기대 출력이 보여요

# 1) 자연어로 요청
Use the code-reviewer subagent to inspect the recent auth changes

# 2) 확정 호출
@"code-reviewer (agent)" auth 변경만 보고 위험한 부분부터 정리해줘

# 3) 세션 전체를 특정 에이전트로 시작
claude --agent code-reviewer

자동 위임이 들쭉날쭉하면 저는 두 단계로 가요. 먼저 description에 발동 조건을 더 적고, 그래도 불안하면 @agent로 확정 호출합니다. 커밋 직전 자동 검사까지 붙이고 싶다면 Claude Code Hooks 완벽 가이드 – 자동화 훅 설정법처럼 훅으로 넘기는 편이 더 예측 가능해요.

CLAUDE_CODE_SUBAGENT_MODEL과 Max 과금 체크

비용 문제는 모델 분리와 인증 경로를 같이 봐야 해요. CLAUDE_CODE_SUBAGENT_MODEL만 잡아도 체감이 달라지고, Max 구독자는 ANTHROPIC_API_KEY 유무를 먼저 보는 게 안전해요.

가격은 2026년 4월 15일 기준 Anthropic 개인 요금표와 API 요금표 기준으로 적었어요.

항목	2026-04-15 기준 공식 표기	실무 메모
Claude Pro	월 $20, 연간 결제 시 월 $17 상당	Claude Code 포함
Max 5x	월 $100	긴 세션과 잦은 병렬 작업용
Max 20x	월 $200	하루 종일 붙는 쪽에 맞아요
Claude Haiku 4.5 API	입력 $1 / MTok, 출력 $5 / MTok	단순 서브에이전트용으로 많이 써요

Haiku로 돌려도 품질 괜찮냐고요? 단순 검색, 로그 요약, 테스트 실행처럼 “읽고 돌리고 요약하는 일”은 Haiku로 빼도 꽤 버텨요. 반대로 설계 판단, 까다로운 디버깅, 애매한 리팩터링은 메인 모델을 그대로 두는 편이 품질 편차가 적어요.

# 서브에이전트만 Haiku로 분리
export CLAUDE_CODE_SUBAGENT_MODEL=haiku

# 현재 셸에 API 키가 잡혀 있는지 보기
env | grep ANTHROPIC

# Max 구독으로만 쓸 생각이면 키 해제
unset ANTHROPIC_API_KEY

# 출력 예시
ANTHROPIC_API_KEY=sk-ant-...

여기서 진짜 많이 삽질해요. 2026년 4월 15일에 GitHub 이슈 #39903는 Open 상태였고, Max 구독자가 서브에이전트 dispatch 중 예상치 못한 API 요금을 맞았다는 보고가 남아 있었어요. 그래서 Max만 쓸 생각이면 세션 시작 전에 환경 변수부터 보는 습관이 필요해요. 도구 자체를 갈아탈지 고민 중이면 Claude Code vs Codex: 직접 비교하고 정리한 선택 기준도 같이 보면 판단이 빨라요.

isolation worktree와 에이전트 팀 선택

병렬 작업은 빨라지지만 같은 파일을 동시에 건드리면 바로 꼬여요. 같은 파일을 여러 세션이 동시에 만져도 충돌 안 날까요?

isolation: worktree를 넣으면 각 세션이 별도 git worktree에서 돌아서 파일 충돌은 거의 안 나요. 그래도 서로 상의가 필요한 일이라면 그때 에이전트 팀으로 넘어가면 되고요. 서브에이전트는 “결과만 받아오면 되는 일”에 좋아요. 에이전트 팀은 “서로 얘기하면서 굴러야 하는 일”에 맞고요. 2026년 4월 15일 기준 공식 문서는 에이전트 팀이 일반 세션보다 토큰을 훨씬 많이 쓴다고 적어요. 그러니 팀은 정말 필요할 때만 여는 게 맞아요.

항목	서브에이전트	에이전트 팀
대화 구조	메인 세션에만 보고	팀원끼리 직접 메시지 가능
기본 상태	바로 사용 가능	실험 기능, 기본 비활성
토큰 비용	상대적으로 낮음	더 큼
잘 맞는 일	빠른 조사, 리뷰, 테스트	토론, 역할 분담, 장기 협업
켜는 방법	별도 플래그 없음	CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

---
name: test-runner
description: Run tests and summarize only failures
tools: Read, Bash, Grep
model: haiku
isolation: worktree
---

Use 3 parallel subagents:
1. auth 테스트 점검
2. API 에러 처리 확인
3. 문서 누락 검사

Return only short summaries.

작업이 서로 독립적이면 서브에이전트로 끝내는 게 보통 이득이에요. 같은 파일을 여러 명이 만질 가능성이 보이면 isolation: worktree부터 넣으세요. “역할별로 계속 얘기하면서 방향을 바꿔야 하는 작업”이면 그때 에이전트 팀을 보는 게 맞죠. 큰 그림이 더 필요하면 AI 에이전트 만들기: 도구 호출부터 워크플로우까지 실전 가이드 쪽이 이어 읽기 좋아요.

자주 묻는 질문

Q1: description에 뭐라고 써야 자동으로 잘 불리나요?

A: 능력 소개보다 발동 조건을 적으세요. use proactively류 문구, 파일 범위, 작업 종류, 기대 출력까지 넣으면 훨씬 낫거든요. 그래도 자동 위임이 안 걸리면 @"agent-name (agent)"로 명시 호출하는 게 제일 확실해요.

Q2: Max Plan인데 왜 API 요금이 따로 찍힐 수 있나요?

A: 2026년 4월 15일에 GitHub 이슈 #39903는 Open 상태였어요. ANTHROPIC_API_KEY가 셸에 남아 있으면 자식 프로세스가 그 키를 볼 수 있다는 보고가 있었고요. Max만 쓸 생각이면 세션 시작 전에 환경 변수부터 보세요.

Q3: CLAUDE_CODE_SUBAGENT_MODEL은 어디까지 낮춰도 되나요?

A: 문자열 검색이나 테스트 실행처럼 판단이 거의 필요 없는 작업이면 Haiku로 충분해요. 출력이 이상하다 싶으면 바로 model: sonnet으로 올리는 게 맞죠. “Haiku가 답을 얼버무린다” 싶을 때가 신호예요.

Q4: 서브에이전트와 에이전트 팀은 뭐가 다른가요?

A: 서브에이전트는 한 세션 안에서 잠깐 위임하는 작업자예요. 에이전트 팀은 각 세션이 독립적으로 움직이면서 서로 메시지도 주고받는 구조죠. 서로 토론이 필요 없으면 보통 서브에이전트면 충분해요.

Q5: 서브에이전트가 또 다른 서브에이전트를 만들 수 있나요?

A: 아니요. 공식 문서는 중첩 spawn 불가라고 적어요. 다단계 위임이 필요하면 메인 세션이 순서를 조율하거나, 정말 협업이 필요할 때만 에이전트 팀으로 넘기세요.

다음 단계

지금은 .claude/agents/code-reviewer.md 하나만 만들어서 claude agents에 보이는지부터 체크하세요. 자동 위임까지 묶고 싶으면 다음으로 Claude Code Hooks 완벽 가이드 – 자동화 훅 설정법에서 실행 전후 훅을 붙여보면 돼요.