서브에이전트

중급

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

17분 소요

서브에이전트란?

서브에이전트는 특정 유형의 작업을 처리하기 위해 특화된 AI 도우미입니다. 부수적인 작업이 검색 결과, 로그, 파일 내용 등으로 메인 대화를 압도할 때 서브에이전트를 사용하세요. 서브에이전트는 자체 컨텍스트에서 해당 작업을 수행하고 요약된 결과만 반환합니다.

동일한 지시사항으로 같은 종류의 워커를 계속 생성해야 할 때 사용자 지정 서브에이전트를 정의할 수 있습니다. 각 서브에이전트는 사용자 지정 시스템 프롬프트, 특정 도구 접근 권한 및 독립적인 권한을 가진 자체 컨텍스트 윈도우에서 실행됩니다. Claude가 서브에이전트의 설명과 일치하는 작업을 만나면, 해당 서브에이전트에 위임하고 서브에이전트는 독립적으로 작업하여 결과를 반환합니다.

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

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

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

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

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

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

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

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

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

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

서브에이전트를 사용하는 이유

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

💡컨텍스트 윈도우란?

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

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

내장 서브에이전트

Claude Code에는 Claude가 필요하다고 판단할 때 자동으로 사용하는 내장 서브에이전트가 포함되어 있습니다. 각 서브에이전트는 부모 대화의 권한을 상속받으며, 추가적인 도구 제한이 적용됩니다.

참고: Explore와 Plan은 CLAUDE.md 파일과 부모 세션의 git status를 건너뛰어 빠르고 저렴한 연구를 수행합니다. 다른 모든 내장 및 사용자 지정 서브에이전트는 둘 다 로드합니다. 서브에이전트에 무엇이 로드되는지에 대한 자세한 내용은 시작 시 로드되는 내용을 참조하세요.

Explore

항목	내용
모델	Haiku (빠르고 낮은 지연 시간)
도구	읽기 전용 도구 (쓰기 및 편집 도구 접근 거부)
용도	파일 검색, 코드 검색, 코드베이스 탐색

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

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 도구 자체를 거부하세요. 비대화형 모드 및 Agent SDK에서는 CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1을 설정하여 모든 내장 유형을 제거하고 사용자 지정 서브에이전트만 제공할 수 있습니다.

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

서브에이전트는 YAML frontmatter가 포함된 마크다운 파일로 정의됩니다. 수동으로 생성하거나 /agents 명령어를 사용할 수 있습니다. 이 가이드는 /agents 명령어를 사용하여 사용자 수준 서브에이전트를 생성하는 과정을 안내합니다. 이 서브에이전트는 코드를 검토하고 코드베이스 개선 사항을 제안합니다.

1단계: 서브에이전트 인터페이스 열기

Claude Code에서 다음 명령어를 실행하세요:

/agents

2단계: 위치 선택

Library 탭으로 전환하고 "새 에이전트 생성"을 선택한 후 "개인(Personal)"을 선택하세요. 이렇게 하면 서브에이전트가 ~/.claude/agents/에 저장되어 모든 프로젝트에서 사용 가능합니다.

3단계: Claude가 생성하도록 하기

"Claude가 생성"을 선택하고 다음과 같이 서브에이전트를 설명하세요:

A code improvement agent that scans files and suggests improvements for readability, performance, and best practices. It should explain each issue, show the current code, and provide an improved version.

Claude가 식별자, 설명 및 시스템 프롬프트를 생성합니다.

4단계: 도구 선택

읽기 전용 리뷰어의 경우, "읽기 전용 도구(Read-only tools)"를 제외한 모든 선택을 해제하세요. 모든 도구를 선택한 상태로 두면 서브에이전트는 메인 대화에서 사용 가능한 모든 도구를 상속합니다.

5단계: 모델 선택

서브에이전트가 사용할 모델을 선택하세요. 이 예제 에이전트의 경우, 코드 패턴 분석에 있어 기능과 속도의 균형을 맞추는 Sonnet을 선택하세요.

6단계: 색상 선택

서브에이전트의 색상을 선택하세요.

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

.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
---
 
사용자의 학습 진도와 선호도를 기억하고, 이전 세션에서 학습한 내용을
바탕으로 다음 학습을 안내합니다.

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

자동 위임 (Automatic Delegation)

Claude는 각 서브에이전트의 description 필드를 읽고 작업이 해당 에이전트와 일치하는지 판단합니다. 서브에이전트를 생성할 때 명확한 설명을 작성하여 Claude가 언제 사용할지 알 수 있도록 하세요.

좋은 description의 예:

discription: "프론트엔드 성능 최적화 전문가. 번들 크기, 렌더링 성능, 이미지 최적화를 분석하고 개선 방안을 제시합니다."

구체적인 작업 설명이 필요합니다:

에이전트가 언제 호출되어야 하는지 명확하게
어떤 유형의 입력을 받는지 명시
어떤 결과를 반환하는지 설명

서브에이전트 작업

서브에이전트 명시 호출 (Invoke Subagents Explicitly)

서브에이전트를 명시적으로 호출할 수도 있습니다. 자동 위임뿐만 아니라 필요할 때 특정 에이전트를 직접 지정하여 작업을 수행하도록 할 수 있습니다.

"코드 리뷰어 에이전트를 사용해서 src/ 디렉토리를 검토해줘"

Claude가 자동으로 판단하지 않더라도, 명시적으로 요청하면 해당 서브에이전트가 작업을 수행합니다.

포그라운드 또는 백그라운드 실행

서브에이전트는 포그라운드(foreground) 또는 백그라운드(background)에서 실행될 수 있습니다.

포그라운드 실행:

에이전트의 작업 진행 상황을 실시간으로 볼 수 있음
에이전트가 완료될 때까지 메인 대화가 대기
결과를 바로 확인 가능

백그라운드 실행:

에이전트가 별도로 작업을 수행하는 동안 메인 대화 계속 진행
메인 대화가 멈추지 않음
background: true 설정으로 활성화

---
name: "장시간 분석기"
background: true  # 백그라운드에서 실행
---

포크된 서브에이전트 (Forked Subagents)

기존 서브에이전트를 기반으로 새로운 서브에이전트를 생성할 수 있습니다. 이는 기존 에이전트의 설정을 재사용하면서 특정 요구 사항에 맞게 수정할 때 유용합니다.

특정 서브에이전트 비활성화 (Disable specific subagents)

내장 서브에이전트의 특정 유형을 차단하려면 permissions.deny에 추가하세요.

permissions:
  deny:
    - agent: Explore

Claude가 어떤 서브에이전트에도 위임하는 것을 방지하려면 permissions.deny로 Agent 도구 자체를 거부하세요.

permissions:
  deny:
    - tool: Agent

도움이 되었나요?