서브에이전트

중급

특화된 AI 도우미 생성 및 활용 가이드

16분 소요

서브에이전트란?

서브에이전트는 특정 유형의 작업을 처리하기 위해 특화된 AI 도우미입니다. 부수적인 작업이 검색 결과, 로그, 파일 내용 등으로 메인 대화를 압도할 때 서브에이전트를 사용하세요. 서브에이전트는 자체 컨텍스트에서 해당 작업을 수행하고 요약된 결과만 반환합니다. 동일한 지시사항으로 같은 종류의 워커를 계속 생성해야 할 때 사용자 지정 서브에이전트를 정의할 수 있습니다. 각 서브에이전트는 사용자 지정 시스템 프롬프트, 특정 도구 접근 권한 및 독립적인 권한을 가진 자체 컨텍스트 윈도우에서 실행됩니다. Claude가 서브에이전트의 설명과 일치하는 작업을 만나면, 해당 서브에이전트에 위임하고 서브에이전트는 독립적으로 작업하여 결과를 반환합니다. 컨텍스트 절약 효과를 실제로 확인하려면, 컨텍스트 윈도우 시각화에서 서브에이전트가 별도의 윈도우에서 연구를 처리하는 세션을 살펴보세요.

ℹ️서브에이전트를 쉽게 이해하기

서브에이전트는 **"AI 비서의 보조 비서"**라고 생각하면 됩니다.

여러분이 Claude Code(메인 비서)에게 큰 프로젝트를 맡기면, Claude Code가 스스로 판단하여 세부 작업을 보조 비서(서브에이전트)에게 나눠줍니다. 예를 들어 "이 프로젝트의 버그를 찾아줘"라고 하면, 메인 비서는 보조 비서에게 "너는 프론트엔드 폴더를 살펴봐"라고 시키고, 본인은 백엔드 폴더를 살피는 식입니다.

처음 사용하시는 분은 서브에이전트를 직접 설정할 필요가 없습니다. Claude Code가 필요하다고 판단하면 자동으로 서브에이전트를 활용합니다.

서브에이전트를 사용하는 경우

다음과 같은 상황에서 서브에이전트를 활용하면 효과적입니다:

컨텍스트 보존: 탐색 및 구현 작업을 메인 대화에서 분리하여 컨텍스트를 보존합니다.
제약 조건 적용: 서브에이전트가 사용할 수 있는 도구를 제한하여 제약 조건을 적용합니다.
구성 재사용: 사용자 수준 서브에이전트를 통해 프로젝트 전반에 걸쳐 구성을 재사용합니다.
동작 전문화: 특정 도메인에 초점을 맞춘 시스템 프롬프트로 동작을 전문화합니다.
비용 제어: 작업을 Haiku와 같은 더 빠르고 저렴한 모델로 라우팅하여 비용을 제어합니다.

Claude는 각 서브에이전트의 설명을 사용하여 작업을 위임할 시기를 결정합니다. 서브에이전트를 생성할 때, Claude가 언제 사용할지 알 수 있도록 명확한 설명을 작성하세요. Claude Code에는 Explore, Plan, General-purpose와 같은 여러 내장 서브에이전트가 포함되어 있습니다. 특정 작업을 처리하기 위한 사용자 지정 서브에이전트를 생성할 수도 있습니다.

서브에이전트와 에이전트 팀의 차이

⚠️여러 에이전트의 병렬 실행이 필요한가요?

서브에이전트: 단일 세션 내에서 작동. 메인 대화 내 작업 위임
백그라운드 에이전트: 여러 독립적인 세션을 병렬로 실행하고 한 곳에서 모니터링합니다. (백그라운드 에이전트 참고)
에이전트 팀: 여러 에이전트가 서로 소통하면서 작업해야 할 때 사용합니다. (에이전트 팀 참고)

💡컨텍스트 윈도우란?

컨텍스트 윈도우는 AI가 한 번에 기억할 수 있는 대화 내용의 크기입니다. 사람의 단기 기억과 비슷합니다.

대화가 길어지면 AI가 앞부분의 내용을 잊어버릴 수 있는데, 서브에이전트를 사용하면 각 작업이 별도의 기억 공간을 사용하므로 메인 대화의 기억을 아낄 수 있습니다.

내장 서브에이전트

Claude Code에는 Claude가 필요하다고 판단할 때 자동으로 사용하는 내장 서브에이전트가 포함되어 있습니다. 각 서브에이전트는 부모 대화의 권한을 상속받으며, 추가적인 도구 제한이 적용됩니다. Explore와 Plan은 CLAUDE.md 파일과 부모 세션의 git status를 건너뛰어 빠르고 저렴한 연구를 수행합니다. 다른 모든 내장 및 사용자 지정 서브에이전트는 둘 다 로드합니다. 서브에이전트에 무엇이 로드되는지에 대한 자세한 내용은 시작 시 로드되는 내용을 참조하세요.

Explore

항목	내용
모델	메인 대화에서 상속, Claude API에서는 Opus로 제한 (Explore는 세션에 선택한 모델보다 더 비싼 모델에서 실행되지 않음)
도구	읽기 전용 도구 (쓰기 및 편집 도구 접근 거부)
용도	파일 검색, 코드 검색, 코드베이스 탐색

Explore는 코드베이스 검색 및 분석에 최적화된 빠르고 읽기 전용의 에이전트입니다. Claude는 변경 없이 코드베이스를 검색하거나 이해해야 할 때 Explore에 위임합니다. 이는 탐색 결과를 메인 대화 컨텍스트 밖에 유지합니다.

v2.1.198부터 Explore는 항상 Haiku에서 실행되는 대신 메인 대화의 모델을 상속합니다. Claude API에서는 상속된 모델이 Opus로 제한됩니다. 즉, 상위 티어의 메인 대화는 Explore를 Opus에서 실행하고, Sonnet 또는 Haiku의 메인 대화는 동일한 모델에서 Explore를 실행합니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 또는 AWS의 Claude Platform과 같은 다른 공급자에서는 Explore가 메인 대화의 모델을 직접 상속합니다. Explore라는 사용자 또는 프로젝트 서브에이전트는 내장 서브에이전트를 재정의하고 자체 모델 필드를 유지하므로, model: haiku로 정의하여 탐색을 저비용 모델로 유지할 수 있습니다.

Explore를 호출할 때 Claude는 탐색의 깊이를 지정합니다:

quick: 타겟 검색용
medium: 균형 잡힌 탐색용
very thorough: 포괄적인 분석용

Plan

항목	내용
모델	메인 대화에서 상속
도구	읽기 전용 도구 (쓰기 및 편집 도구 접근 거부)
용도	계획 제시 전 컨텍스트 수집을 위한 코드베이스 연구

Plan은 계획 모드 중에 컨텍스트를 수집하는 데 사용되는 연구 에이전트입니다. 계획 모드에서 Claude가 코드베이스를 이해해야 할 때, 연구를 Plan 서브에이전트에 위임하여 탐색 출력이 별도의 컨텍스트 윈도우에 유지되고 메인 대화는 읽기 전용으로 유지됩니다.

General-purpose

항목	내용
모델	메인 대화에서 상속
도구	서브에이전트가 사용할 수 있는 모든 도구
용도	복잡한 연구, 다단계 작업, 코드 수정

General-purpose는 탐색과 작업(수정)이 모두 필요한 복잡한 다단계 작업을 위한 유능한 에이전트입니다. Claude는 탐색과 수정이 모두 필요하거나, 결과를 해석하기 위한 복잡한 추론이 필요하거나, 여러 종속적인 단계가 필요한 경우 General-purpose에 위임합니다.

기타 내장 에이전트

Claude Code에는 특정 작업을 위한 추가 헬퍼 에이전트가 포함되어 있습니다. 이들은 일반적으로 자동으로 호출되므로 직접 사용할 필요가 없습니다.

에이전트	모델	Claude 사용 시점
statusline-setup	Sonnet	`/statusline`을 실행하여 상태 라인을 구성할 때
claude-code-guide	Haiku	Claude Code 기능에 대해 질문할 때

참고: 내장 서브에이전트는 항상 대화형 세션에 등록됩니다. 특정 내장 유형을 차단하려면 특정 서브에이전트 비활성화에 표시된 대로 permissions.deny에 추가하세요. Claude가 어떤 서브에이전트에도 위임하는 것을 방지하려면 permissions.deny로 Agent 도구 자체를 거부하세요. 내장 Explore 및 Plan 서브에이전트만 제거하려면 CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1을 설정하세요. (Claude Code v2.1.198 이상 필요) 이 경우 Claude는 서브에이전트에 위임하는 대신 파일을 직접 읽고 탐색합니다. 비대화형 모드 및 Agent SDK에서는 CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1을 설정하여 모든 내장 유형을 제거하고 사용자 지정 서브에이전트만 제공할 수 있습니다.

이러한 내장 서브에이전트 외에도 사용자 지정 프롬프트, 도구 제한, 권한 모드, 훅 및 스킬을 사용하여 자신만의 서브에이전트를 생성할 수 있습니다. 다음 섹션에서는 서브에이전트를 시작하고 사용자 지정하는 방법을 보여줍니다.

Quickstart: 첫 번째 서브에이전트 생성하기

서브에이전트는 YAML frontmatter가 포함된 마크다운 파일로 정의됩니다. 수동으로 생성하거나 Claude에게 작성을 요청할 수 있습니다. v2.1.198부터 /agents 명령은 더 이상 대화형 생성 마법사를 열지 않습니다. 대신 Claude에게 요청하거나 .claude/agents/를 직접 편집하라는 알림을 출력합니다. 이 가이드는 Claude에게 요청하여 사용자 수준 서브에이전트를 생성하는 과정을 안내합니다. 이 서브에이전트는 코드를 검토하고 코드베이스 개선 사항을 제안합니다.

1단계: Claude에게 서브에이전트 생성 요청

Claude Code에서 다음과 같이 서브에이전트 생성을 요청하세요:

Claude, create a personal subagent that acts as a code improvement agent. It should scan files and suggest improvements for readability, performance, and best practices. It should explain each issue, show the current code, and provide an improved version. It should use Sonnet model and only read-only tools.

Claude가 식별자, 설명, 시스템 프롬프트, 모델 및 도구 설정을 포함한 서브에이전트 파일을 ~/.claude/agents/에 생성할 것입니다.

2단계: 생성된 파일 확인 및 수정 (선택 사항)

Claude가 생성한 서브에이전트 파일은 ~/.claude/agents/ 경로에 저장됩니다. 필요에 따라 이 파일을 열어 내용을 검토하고 수정할 수 있습니다.

마크다운 파일로 직접 생성하기

.claude/agents/ 디렉토리에 마크다운 파일을 생성하여 서브에이전트를 정의합니다.

.claude/agents/
  code-reviewer.md
  test-writer.md
  doc-generator.md

ℹ️내장 vs 커스텀 서브에이전트

내장 서브에이전트: Claude Code가 자동으로 사용합니다. 별도 설정이 필요 없습니다
커스텀 서브에이전트: 여러분이 직접 만드는 전문 AI 도우미입니다. 예를 들어 "보안 전문가 에이전트", "테스트 전문가 에이전트" 등을 만들 수 있습니다

커스텀 서브에이전트는 프로젝트의 .claude/agents/ 폴더에 마크다운 파일로 만듭니다. 마크다운 파일 안에 에이전트의 역할과 규칙을 적어두면, Claude Code가 필요할 때 그 전문가를 불러서 사용합니다.

서브에이전트 파일 구조

각 파일은 YAML frontmatter와 마크다운 본문으로 구성됩니다.

---
name: "코드 리뷰어"
description: "코드 품질, 보안, 성능을 검토하는 전문 리뷰어"
tools:
  - Read
  - Grep
  - Glob
  - Bash(eslint)
  - Bash(npm test)
model: claude-sonnet-4-6
maxTurns: 30
---
 
# 코드 리뷰 지침
 
당신은 코드 리뷰 전문가입니다. 다음 기준으로 코드를 검토하세요:
 
## 검토 항목
 
1. **코드 품질**: 가독성, 명명 규칙, 중복 코드
2. **보안**: SQL 인젝션, XSS, 인증 우회 취약점
3. **성능**: 불필요한 연산, N+1 쿼리, 메모리 누수
4. **테스트**: 테스트 커버리지, 엣지 케이스
5. **타입 안전성**: TypeScript strict 모드 준수
 
## 출력 형식
 
각 이슈를 심각도별로 분류하여 보고하세요:
- CRITICAL: 즉시 수정 필요
- WARNING: 개선 권장
- INFO: 참고 사항

YAML frontmatter 전체 필드

필드	타입	설명
name	string	에이전트 표시 이름
description	string	에이전트 역할 설명 (자동 위임 결정 시 사용)
tools	string[]	사용 가능한 도구 목록
model	string	사용할 Claude 모델
permissionMode	string	권한 모드 (default, plan, bypassPermissions)
maxTurns	number	최대 실행 턴 수
memory	string	영구 메모리 범위 (user, project, local)
background	boolean	백그라운드 실행 여부
isolation	string	격리 모드 (worktree)
hooks	object	에이전트별 Hook 설정
skills	string[]	참조할 스킬 목록
mcpServers	object	에이전트 전용 MCP 서버 설정

서브에이전트 설정

모델 선택

에이전트에 적절한 Claude 모델을 선택하세요.

---
name: "빠른 스캐너"
model: claude-haiku-4-5  # 저비용, 빠른 작업용
---

복잡한 추론이 필요하면 더 강력한 모델을 사용하세요.

---
name: "아키텍처 설계자"
model: claude-opus-4-6  # 고성능 모델
---

모델 선택 가이드:

Haiku: 빠른 검색, 읽기 작업, 저비용
Sonnet: 일반적인 코드 작업, 기능과 속도 균형
Opus: 복잡한 추론, 아키텍처 설계, 고성능

도구 접근 제어

에이전트가 사용 가능한 도구를 tools 필드로 명시합니다.

---
name: "읽기 전용 분석기"
tools:
  - Read
  - Grep
  - Glob
---

권한 모드로 도구 접근을 추가 제어할 수 있습니다.

---
name: "제한된 에이전트"
permissionMode: "plan"  # 계획 모드에서만 실행 가능
---

서브에이전트 범위 우선순위

여러 위치에서 동일한 이름의 에이전트가 정의된 경우, 다음 우선순위로 적용됩니다.

1. CLI (--agents 옵션)          ← 가장 높음
2. 프로젝트 (.claude/agents/)
3. 사용자 (~/.claude/agents/)
4. 플러그인                     ← 가장 낮음

프로젝트 에이전트가 사용자 에이전트보다 우선합니다. CLI로 전달한 임시 에이전트가 가장 높은 우선순위를 가집니다.

영구 메모리 (Persistent Memory)

서브에이전트에 memory 필드를 설정하면 세션 간에 정보를 유지할 수 있습니다.

메모리 범위:

범위	저장 위치	공유 범위
user	`~/.claude/`	사용자의 모든 프로젝트
project	`.claude/`	해당 프로젝트의 모든 사용자
local	`.claude/local/`	현재 사용자, 현재 프로젝트

---
name: "학습 도우미"
description: "사용자의 학습 진도를 기억하는 도우미"
memory: user
---
 
사용자의 학습 진도와 선호도를 기억하고, 이전 세션에서 학습한 내용을
바탕으로 다음 학습을 안내합니다.

메모리를 가진 에이전트는 이전 세션의 대화 내용이나 학습 결과를 기억하여 연속적인 작업을 수행할 수 있습니다.

도움이 되었나요?