Claude Code 서브에이전트 완전 가이드 — .claude/agents 정의부터 비용 최적화까지
.claude/agents/ 폴더에 마크다운 파일 1개로 정의하며, 독립된 컨텍스트·도구 권한을 지정할 수 있어 역할 분리와 병렬 실행 모두에 실질적으로 유용하다. 단, 프론트매터의 model: 필드는 현재 버전 기준으로 실제 적용되지 않을 수 있으므로 주의가 필요하다.서브에이전트를 쓰면 메인 에이전트의 컨텍스트 창을 오염시키지 않고 하위 작업을 위임할 수 있다. 코드 리뷰, 문서 생성, 보안 감사처럼 '한 번에 집중해야 하는 작업'이 반복되는 개발자라면 특히 효과적이다. 이 글은 파일 형식 정의부터 모델 선택과 비용 주의사항까지 실제 사용에 필요한 내용을 순서대로 짚는다.
Claude Code 서브에이전트의 역할 분리와 권한 설정을 요약한 AI 생성 대표 이미지.
서브에이전트란 정확히 무엇인가?
서브에이전트는 독립된 컨텍스트 창을 가진 별도 Claude 인스턴스다. 메인 에이전트가 작업을 위임하면, 서브에이전트는 그 작업만 처리하고 최종 결과만 돌려준다. 중간에 발생하는 파일 읽기·검색·탐색 등의 모든 중간 호출은 서브에이전트 컨텍스트 안에서 사라지며 메인 대화를 채우지 않는다.
핵심 특성은 3가지다. 첫째, 서브에이전트는 메인 시스템 프롬프트를 상속받지 않고 자신의 시스템 프롬프트만 받는다. 둘째, 허용된 도구 목록을 별도로 설정할 수 있다. 셋째, 서브에이전트 정의 파일에서 별도 모델을 지정하는 기능이 제공되나, 버전에 따라 동작이 다를 수 있다(아래 '모델 선택' 항목 참조).
파일을 어디에, 어떻게 만드는가?
서브에이전트 정의 파일은 마크다운(.md) 형식이며 2곳에 놓을 수 있다.
.claude/agents/— 프로젝트 단위. 팀 리포와 함께 버전 관리된다.~/.claude/agents/— 사용자 단위. 모든 프로젝트에서 불러올 수 있다.
하위 폴더로 정리해도 된다. agents/review/, agents/research/ 같은 방식으로 역할별 분류가 가능하며, Claude Code는 이 경로를 재귀적으로 스캔한다. 단, 에이전트 식별은 폴더 경로가 아닌 프론트매터의 name 필드로만 이루어진다. 파일을 추가하거나 수정하면 세션을 재시작해야 반영된다.
파일 구조는 다음과 같다. YAML 프론트매터가 설정, 그 아래 마크다운 본문이 시스템 프롬프트다.
---
name: code-reviewer
description: PR 코드를 품질·보안 기준으로 검토한다.
tools: Read, Grep, Glob, Bash
model: sonnet
permissionMode: default
---
당신은 시니어 코드 리뷰어다.
가독성, 엣지 케이스, 보안 취약점 순서로 검토하고
발견 사항을 bullet point로 간결하게 보고한다.
추측성 코멘트는 달지 않는다.Claude Code 내부에서 /agents UI를 통해 인터랙티브하게 만들 수도 있다. 이름·설명·도구·시스템 프롬프트를 입력하면 파일이 자동 생성된다. 빠른 반복 실험에는 UI가 편리하고, 팀 공유 목적이면 파일 방식이 낫다.
프론트매터 핵심 필드는 무엇인가?
| 필드 | 역할 | 예시 |
|---|---|---|
name |
에이전트 식별자 (고유해야 함) | security-auditor |
description |
언제 이 에이전트를 쓸지 설명. 메인 에이전트가 참조해 자동 위임 | 한 문장으로 구체적으로 |
tools |
허용할 도구 목록 (콤마 구분) | Read, Grep, Bash |
disallowedTools |
명시적으로 차단할 도구 | Bash |
model |
사용 모델 지정. 미지정 시 부모 모델을 상속. 단, 현재 버전에서는 이 필드가 무시되는 버그가 보고돼 있으므로 실제 동작 여부를 직접 확인할 것 | haiku, sonnet, opus, 또는 풀 모델 ID |
permissionMode |
권한 승인 방식. 총 5가지 값 지원 | default, acceptEdits, plan, dontAsk, bypassPermissions |
maxTurns |
최대 대화 턴 수 제한 | 10 |
background |
true이면 메인 채팅과 병렬로 실행, false이면 동기(순차) 실행 |
true |
mcpServers |
이 서브에이전트에 노출할 MCP 서버 목록. 나머지 서버는 차단됨 | [db-server] |
시스템 프롬프트는 어떻게 잘 쓰는가?
프론트매터 아래 마크다운 본문 전체가 시스템 프롬프트로 전달된다. 서브에이전트는 Claude Code의 기본 시스템 프롬프트를 받지 않기 때문에, 필요한 컨텍스트를 프롬프트 안에 직접 넣어야 한다. 작업 환경(예: '이 프로젝트는 Node.js 20 기반이다')이나 출력 형식 지침을 명시하면 안정적인 결과를 얻을 수 있다.
좋은 시스템 프롬프트의 특징은 3가지다. 첫째, 에이전트의 역할과 목적이 첫 문장에 명시된다. 둘째, 출력 형식(예: JSON, bullet, Markdown 표)을 지정한다. 셋째, 하지 말아야 할 행동을 구체적으로 적는다. 예를 들어 '수정 제안은 하지 않는다. 발견 사항만 보고한다'처럼 범위를 제한하면 서브에이전트가 불필요하게 과확장되는 것을 막을 수 있다.
언제 서브에이전트를 쓰고, 언제 쓰지 말아야 하는가?
서브에이전트가 효과적인 상황과 그렇지 않은 상황을 구분하는 것이 핵심이다.
- 역할 분리 — 코드 생성과 코드 리뷰를 동일 컨텍스트에서 섞지 않을 때
- 병렬 탐색 — 여러 모듈을 동시에 분석하거나, 독립적인 파일 그룹을 각각 처리할 때
- 반복 작업 — 같은 템플릿을 여러 입력에 적용할 때(예: 10개 파일 각각 문서화)
- 컨텍스트 오염 방지 — 중간 탐색 과정이 많은 연구성 작업을 위임할 때
- 순차적으로 연결된 작업 — 앞 결과가 뒤 입력이 되는 파이프라인은 오케스트레이터 단일 에이전트가 더 단순하다
- 단순 명령 1회 — 파일 1개 읽고 요약하는 수준이라면 서브에이전트 오버헤드가 더 크다
- 소수 병렬 분기 — 분기 수가 적을수록 오버헤드 대비 시간 절약 효과가 줄어든다. 적정 임계는 워크로드에 따라 다르므로 직접 측정이 필요하다
모델 선택이 비용을 얼마나 좌우하는가?
서브에이전트를 병렬로 띄우면 토큰 소모가 빠르게 늘어난다. 모델 선택이 비용의 핵심 레버다. 공식 API 기준(2026년 5월 시점), 입력 토큰 단가는 Haiku 4.5가 $1.00/M, Sonnet 4.6이 $3.00/M, Opus 4.7이 $5.00/M 수준이나 변동될 수 있으므로 공식 가격 페이지에서 반드시 재확인해야 한다.
GitHub 이슈(#44385)에 따르면 현재 Claude Code 일부 버전에서 서브에이전트
.md 파일의 model: 필드가 무시되며, 서브에이전트가 항상 부모 모델을 상속하는 현상이 보고돼 있다. 비용 최적화를 위해 모델을 분리하려면 환경 변수 CLAUDE_CODE_SUBAGENT_MODEL을 사용하거나, Agent 도구 호출 시 명시적으로 모델을 전달하는 방식을 사용하는 것이 현재로서는 더 확실하다. 공식 문서와 버전 릴리스 노트를 주기적으로 확인할 것.
모델별 실용적인 선택 기준은 아래와 같다.
- Haiku: 패턴 매칭, 파일 탐색, 간단한 포맷 변환. 추론이 필요 없는 기계적 작업
- Sonnet: 대부분의 프로덕션 워크로드 기본값. 코드 리뷰, RAG 응답, 분류
- Opus: 자율 코딩, 장기 작업, 품질이 결과물 가치를 직접 결정하는 경우만
병렬 서브에이전트는 단일 에이전트 대비 더 많은 비용이 드는 대신 벽시계 시간을 단축한다(절감 폭은 워크로드에 따라 다름). 20개 이상 병렬 에이전트를 한 번에 띄우는 패턴은 비용 폭주로 이어지기 쉽다. 실무에서는 동시 4~6개를 상한선으로 시작해 검증하는 것이 안전하다.
권한(permissionMode)은 어떻게 설정하는가?
서브에이전트의 permissionMode는 5가지 값을 지원한다: default, acceptEdits, plan, dontAsk, bypassPermissions. 자동화 파이프라인에서 승인 없이 실행하려면 dontAsk를 쓰되, 반드시 tools 목록을 명시적으로 좁혀야 한다. dontAsk와 좁은 tools의 조합이 '제한된 에이전트'를 만드는 표준 패턴이다.
주의할 점이 있다. 메인 에이전트가 bypassPermissions 모드로 실행 중이면, 서브에이전트는 그 모드를 상속받으며 서브에이전트 단에서 재정의할 수 없다. 권한을 좁히려면 메인 에이전트의 모드 자체를 제어해야 한다.
---
name: doc-writer
description: 함수 시그니처를 읽고 JSDoc 주석을 생성한다.
tools: Read, Glob
disallowedTools: Bash, Write
model: haiku
permissionMode: dontAsk
maxTurns: 8
---
주어진 파일에서 함수 목록을 추출하고
각 함수에 JSDoc 형식 주석을 작성한다.
파일은 수정하지 않고 주석만 출력한다.실제 사용 예시 — 코드 리뷰 자동화
다음은 PR 변경 파일을 병렬로 리뷰하는 패턴이다. 오케스트레이터가 변경 파일 목록을 가져오고, 각 파일을 code-reviewer 서브에이전트에 병렬 위임한 뒤, 결과를 종합해 PR 코멘트 초안을 만든다.
# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: 단일 소스 파일을 품질·보안 기준으로 검토한다.
tools: Read, Grep
model: sonnet
permissionMode: default
maxTurns: 6
---
당신은 시니어 코드 리뷰어다.
입력으로 파일 경로를 받는다.
다음 3가지 관점으로 발견 사항을 보고한다:
1. 로직 버그 또는 엣지 케이스
2. 보안 취약점 (SQL injection, XSS 등)
3. 불필요한 복잡도
각 항목은 '파일:라인: 설명' 형식으로 출력한다.
발견 사항이 없으면 'LGTM'만 출력한다.이 패턴에서 code-reviewer는 Read와 Grep만 가지므로 파일 수정이나 외부 호출이 불가하다. 안전한 읽기 전용 에이전트의 전형적인 모양이다.
블로그 자동화에 서브에이전트를 적용하면?
콘텐츠 파이프라인에도 서브에이전트 패턴이 잘 맞는다. 예를 들어 Obsidian 노트를 블로그 포스트로 변환하는 작업을 역할별로 분리할 수 있다. 리서치 에이전트(Haiku, 읽기 전용)가 노트를 수집하고, 편집 에이전트(Sonnet)가 초안을 작성하고, SEO 에이전트(Haiku)가 키워드를 검토하는 방식이다.
각 에이전트의 컨텍스트가 독립되기 때문에, 리서치 단계의 탐색 노이즈가 편집 단계의 프롬프트를 오염시키지 않는다.
🤖 AI·자동화 가이드 더 보기
FAQ
Q1. 서브에이전트는 메인 에이전트의 대화 기록을 볼 수 있나?
볼 수 없다. 서브에이전트는 위임받은 작업 내용과 자신의 시스템 프롬프트만 받는다. 메인 대화 히스토리는 전달되지 않는다.
Q2. ~/.claude/agents/와 .claude/agents/ 중 어디에 두는 게 낫나?
팀이 공유하거나 프로젝트에 종속된 에이전트라면 .claude/agents/(리포 내)가 맞다. 개인 작업 스타일에 맞춘 범용 에이전트라면 ~/.claude/agents/에 두면 모든 프로젝트에서 재사용된다.
Q3. 서브에이전트가 다른 서브에이전트를 호출할 수 있나?
기술적으로는 가능하다. 그러나 중첩 깊이가 깊어질수록 비용과 디버깅 복잡도가 급격히 올라간다. 실무에서는 2단계(오케스트레이터 → 서브에이전트) 이상의 중첩은 필요성을 먼저 검증하는 것이 권장된다.
Q4. 동시에 몇 개까지 병렬로 띄울 수 있나?
기술적 상한은 Claude Code 버전과 환경에 따라 다르다. 비용과 안정성 측면에서 4~6개를 시작점으로 잡고, 실제 워크로드를 검증한 후 늘리는 것이 현실적이다. 20개 이상을 한 번에 띄우는 패턴은 비용 폭주 사례가 보고되고 있어 주의가 필요하다.
Q5. 서브에이전트에서 MCP 도구를 쓸 수 있나?
쓸 수 있다. 프론트매터의 mcpServers 필드로 특정 MCP 서버만 노출할 수 있다. 이를 활용하면 특정 서브에이전트에만 데이터베이스 접근이나 외부 API 호출 권한을 부여하고, 나머지는 차단하는 세밀한 권한 설계가 가능하다.
Q6. description 필드가 자동 위임에 영향을 주나?
그렇다. 메인 에이전트는 description을 보고 어떤 서브에이전트에 작업을 위임할지 판단한다. 구체적이고 명확한 설명일수록 위임 정확도가 높아진다. '코드를 리뷰한다'보다 'PR에서 변경된 파일의 보안 취약점을 검토한다'처럼 쓰는 것이 낫다.
3줄 요약
- 서브에이전트는
.claude/agents/의 마크다운 파일 1개로 정의하며, YAML 프론트매터로 도구·권한을 지정한다. 파일 추가·수정 후에는 세션을 재시작해야 반영된다. - 역할 분리와 병렬 탐색에 효과적이나, 분기가 적거나 순차 작업에는 오버헤드가 더 크다.
- 프론트매터의
model:필드는 현재 일부 버전에서 무시되는 버그가 보고돼 있으므로, 모델별 비용 분리는CLAUDE_CODE_SUBAGENT_MODEL환경 변수로 보완하는 것이 안전하다.
다음 글 예고: Claude Code에서 훅(hooks)을 활용해 특정 이벤트(커밋 전, 파일 저장 등)에 자동으로 에이전트를 실행하는 방법을 다룬다. 서브에이전트와 훅을 조합하면 완전 자동화 파이프라인의 기반이 완성된다.
도구 기능·가격은 업데이트가 잦아 공식 문서 재확인을 권한다.
댓글
댓글 쓰기