클로드 서브에이전트 사용법 — 만들기와 컨텍스트 절약
클로드 코드 서브에이전트(subagent)는 YAML 프론트매터가 붙은 마크다운 파일 하나로 만듭니다. .claude/agents/이름.md에 저장하면 되고, 필수 항목은 name과 description 딱 둘입니다. 서브에이전트를 쓰는 이유는 하나입니다 — 곁가지 작업이 본 대화의 컨텍스트를 잡아먹지 않게 하는 것. 서브에이전트는 자기만의 컨텍스트 창에서 일하고 요약만 돌려줍니다. 검색 결과나 로그 수백 줄이 내 대화에 쌓이지 않습니다. 이 글은 Claude Code v2.1.204 기준으로 만드는 법, 필드, 그리고 언제 쓰면 손해인지까지 정리합니다.
1. 서브에이전트가 실제로 해결하는 문제
"프로젝트 어디에서 이 설정을 읽는지 찾아줘" 같은 요청을 그냥 시키면, 파일 수십 개를 읽은 내용이 전부 내 대화에 남습니다. 정작 필요한 건 "여기 있습니다" 한 줄인데 말이죠. 서브에이전트에 맡기면 그 탐색은 별도 컨텍스트 창에서 일어나고 결론만 돌아옵니다.
공식 문서가 드는 이점은 다섯 가지입니다.
- 컨텍스트 보존 — 탐색과 구현을 본 대화 밖으로 뺀다
- 제약 강제 — 쓸 수 있는 도구를 제한한다 (읽기 전용 등)
- 설정 재사용 — 사용자 수준 서브에이전트를 여러 프로젝트에서 쓴다
- 동작 특화 — 특정 분야에 집중한 시스템 프롬프트를 준다
- 비용 조절 — 가벼운 작업을 하이쿠 같은 빠르고 싼 모델로 돌린다
2. 만들기 — 파일 하나면 된다
프로젝트 폴더에 .claude/agents/code-reviewer.md를 만들고 이렇게 씁니다. --- 사이가 설정, 그 아래 본문이 그 서브에이전트의 시스템 프롬프트가 됩니다.
---
name: code-reviewer
description: 코드 품질과 모범 사례를 검토한다. 코드를 쓰거나 고친 뒤에 쓴다.
tools: Read, Glob, Grep
model: sonnet
---
너는 코드 리뷰어다. 호출되면 코드를 분석해 품질·보안·모범 사례에 대해
구체적이고 실행 가능한 피드백을 제시하라.이제 "code-reviewer 에이전트로 이 프로젝트 검토해줘"라고 하면 위임됩니다. description에 "언제 쓰는지"를 적어 두면 클로드가 알아서 부르기도 합니다.
3. 어디에 두느냐가 적용 범위를 정한다
이름이 겹치면 위쪽이 이깁니다.
| 위치 | 적용 범위 | 우선순위 |
|---|---|---|
--agents CLI 옵션 |
그 세션에만 (디스크에 저장 안 됨) | 높음 |
.claude/agents/ |
그 프로젝트 (커밋하면 팀 공유) | 중간 |
~/.claude/agents/ |
내 모든 프로젝트 | 낮음 |
플러그인 agents/ |
플러그인이 켜진 곳 | 가장 낮음 |
두 폴더 모두 하위 폴더까지 재귀적으로 훑기 때문에 agents/review/처럼 정리해도 됩니다. 다만 정체성은 오직 name 값에서 오므로 이름은 전체에서 유일해야 합니다. 같은 폴더 안에서 이름이 겹치면 파일 읽기 순서에 따라 하나만 로드되고, 어느 쪽이 이길지는 정해져 있지 않습니다.
4. 프론트매터 — 필수 둘, 나머지는 선택
필수는 name과 description뿐입니다. 나머지 중 실제로 손이 자주 가는 것만 추리면 이렇습니다.
| 필드 | 하는 일 |
|---|---|
name (필수) |
소문자와 하이픈으로 된 고유 식별자. 파일 이름과 같을 필요는 없다. |
description (필수) |
클로드가 언제 이 에이전트에 넘길지 판단하는 기준 |
tools |
쓸 수 있는 도구. 빼면 전부 물려받는다. 읽기 전용으로 묶고 싶을 때 쓴다. |
disallowedTools |
물려받은 목록에서 뺄 도구 |
model |
sonnet·opus·haiku·fable 또는 전체 모델 ID, inherit. 기본값은 inherit(본 대화와 같은 모델) |
skills |
시작할 때 컨텍스트에 미리 넣을 스킬. 설명만이 아니라 본문 전체가 들어간다. |
maxTurns |
이 횟수만큼 돌면 멈춘다. 폭주 방지용. |
isolation: worktree |
임시 git 워크트리에서 돌린다. 저장소 사본을 따로 줘서 병렬 작업이 서로 안 밟게 한다. |
color |
작업 목록에서 구분할 색. red·blue·green 등 |
서브에이전트는 이 본문(시스템 프롬프트)과 작업 폴더 같은 기본 정보만 받습니다. 클로드 코드의 전체 시스템 프롬프트는 받지 않습니다. 그래서 본문에 필요한 맥락을 충분히 적어 줘야 합니다.
5. 처음 만들면 안 잡힌다 — 재시작이 필요한 경우
클로드 코드는 ~/.claude/agents/와 .claude/agents/를 지켜보고 있어서, 파일을 고치면 몇 초 안에 반영되고 재시작이 필요 없습니다. 단 하나 예외가 있습니다.
agents 폴더 자체가 없던 상태에서 첫 에이전트를 만들면 그 세션에서는 안 잡힙니다. 재시작해야 합니다. 실제로 .claude/agents/가 없던 세션에서 파일을 만들고 불러 봤더니 "Agent type not found"가 뜨고 사용 가능 목록에 내장 에이전트만 나왔습니다. 처음 만들 때 "왜 안 되지" 싶으면 십중팔구 이것입니다.
6. 만들기 전에 — 내장 서브에이전트부터 본다
클로드 코드에는 이미 쓸 만한 것들이 들어 있습니다. 굳이 안 만들어도 되는 경우가 많습니다.
| 이름 | 쓰임 | 도구 |
|---|---|---|
Explore |
파일 찾기·코드 검색·구조 파악 | 읽기 전용 (Write·Edit 차단) |
Plan |
계획 모드에서 사전 조사 | 읽기 전용 |
general-purpose |
탐색과 수정이 둘 다 필요한 여러 단계 작업 | 전부 |
같은 종류의 일꾼을 같은 지시로 반복해서 띄우고 있을 때가 직접 만들 시점입니다. 그전까지는 내장으로 충분합니다.
7. 남용하면 오히려 느려진다
서브에이전트는 공짜가 아닙니다. 하나 띄울 때마다 맥락을 처음부터 다시 쌓고, 다시 탐색하고, 보고서를 써서 돌려주고, 나는 그 보고서를 또 읽습니다. 그래서 이런 일에는 쓰지 않는 편이 낫습니다.
- 파일 몇 개 읽고 몇 군데 고치면 끝나는 일 — 직접 하는 게 빠릅니다
- 간단한 검색 한 번
- 내 작업을 다시 확인하는 용도 — 검증은 본 흐름에서 하는 게 맞습니다
반대로 서로 독립적이고 덩치가 큰 작업(관련 없는 모듈 여러 개, 파일이 넓게 걸친 조사)에는 값을 합니다. 여러 개를 띄울 거면 한 번에 보내야 동시에 돕니다. 그리고 한 번 맡겼으면 결과를 다시 캐지 마세요. 그럴 거면 처음부터 안 맡기는 게 낫습니다.
8. 스킬과는 뭐가 다른가
헷갈리기 쉬운데 역할이 다릅니다. 스킬은 "무엇을 어떤 순서로 할지"를 담은 절차이고, 서브에이전트는 "누가 어디서 일할지"를 정하는 실행 단위입니다. 둘은 같이 씁니다 — 서브에이전트 프론트매터의 skills 필드로 스킬을 미리 물려 줄 수 있습니다. 스킬 쪽이 처음이시면 claude skills 사용법을 먼저 보시는 편이 순서상 맞습니다.
자주 묻는 질문 (FAQ)
Q. 모델을 안 적으면 어떤 모델로 도나요?
inherit이 기본값이라 본 대화와 같은 모델로 돕니다. 단순 반복 작업이라면 model: haiku로 낮춰 비용을 아낄 수 있습니다. 어떤 모델을 고를지는 Claude 모델 비교(Opus·Sonnet·Haiku)를 참고하세요.
Q. 팀과 공유하려면요?
.claude/agents/에 두고 저장소에 커밋하면 됩니다. 클론한 사람은 별도 설정 없이 씁니다. 개인용은 ~/.claude/agents/에 둡니다.
Q. 파일 이름과 name이 달라도 되나요?
됩니다. 호출에 쓰이는 건 name 값이고 파일 이름은 상관없습니다. 다만 헷갈리니 맞춰 두는 편을 권합니다.
Q. 서브에이전트가 내 작업 폴더를 옮겨 놓지는 않나요?
아닙니다. 서브에이전트 안에서 쓴 cd는 도구 호출 사이에도 유지되지 않고, 본 대화의 작업 폴더에도 영향을 주지 않습니다. 저장소 사본을 아예 따로 주고 싶으면 isolation: worktree를 씁니다.
마무리
정리하면 서브에이전트는 .claude/agents/이름.md 파일 하나이고, name·description만 있으면 돕니다. 핵심 가치는 컨텍스트 격리이니, 본 대화를 어지럽힐 만큼 큰 곁가지 작업에만 쓰세요. 작은 일까지 넘기면 왕복 비용 때문에 오히려 손해입니다. 처음 만들 때 안 잡히면 재시작부터 해 보시고, 필드는 자주 늘어나는 편이니 세부 옵션은 공식 문서를 함께 확인하시길 권합니다.
📚 참고 출처 (2026년 7월 22일 확인 · Claude Code v2.1.204 기준)
· Claude Code 공식 문서 — Create custom subagents
· Claude Code 공식 문서 — Extend Claude with skills
COMMENTS