Claude Code SDK의 서브에이전트는 메인 에이전트에 의해 조율되는 전문화된 AI입니다. 컨텍스트 관리와 병렬화를 위해 서브에이전트를 사용하세요. 이 가이드는 SDK 애플리케이션이 마크다운 파일을 통해 생성된 서브에이전트와 상호작용하고 활용하는 방법을 설명합니다.

​
개요

서브에이전트는 지정된 디렉토리에 YAML frontmatter가 포함된 마크다운 파일을 배치하는 파일시스템 기반 접근 방식을 통해서만 생성됩니다. 그러면 SDK가 실행 중에 이러한 사전 정의된 서브에이전트를 호출할 수 있습니다.

​
서브에이전트 사용의 이점

​
컨텍스트 관리

서브에이전트는 메인 에이전트와 별도의 컨텍스트를 유지하여 정보 과부하를 방지하고 상호작용을 집중적으로 유지합니다. 이러한 격리는 전문화된 작업이 관련 없는 세부사항으로 메인 대화 컨텍스트를 오염시키지 않도록 보장합니다. 예시: research-assistant 서브에이전트는 수십 개의 파일과 문서 페이지를 탐색할 수 있으면서도 모든 중간 검색 결과로 메인 대화를 어지럽히지 않고 관련 발견사항만 반환할 수 있습니다.

​
병렬화

여러 서브에이전트가 동시에 실행되어 복잡한 워크플로우를 극적으로 가속화할 수 있습니다. 예시: 코드 리뷰 중에 style-checker, security-scanner, test-coverage 서브에이전트를 동시에 실행하여 리뷰 시간을 몇 분에서 몇 초로 단축할 수 있습니다.

​
전문화된 지시사항과 지식

각 서브에이전트는 특정 전문 지식, 모범 사례, 제약 조건을 가진 맞춤형 시스템 프롬프트를 가질 수 있습니다. 예시: database-migration 서브에이전트는 SQL 모범 사례, 롤백 전략, 데이터 무결성 검사에 대한 상세한 지식을 가질 수 있으며, 이는 메인 에이전트의 지시사항에서는 불필요한 노이즈가 될 것입니다.

​
도구 제한

서브에이전트는 특정 도구로 제한되어 의도하지 않은 작업의 위험을 줄일 수 있습니다. 예시: doc-reviewer 서브에이전트는 Read와 Grep 도구에만 액세스할 수 있어 분석은 할 수 있지만 문서 파일을 실수로 수정하지 않도록 보장할 수 있습니다.

​
서브에이전트 생성

서브에이전트는 특정 디렉토리의 마크다운 파일로 정의됩니다:
  • 프로젝트 수준: .claude/agents/*.md - 현재 프로젝트에서만 사용 가능
  • 사용자 수준: ~/.claude/agents/*.md - 모든 프로젝트에서 사용 가능

​
파일 형식

각 서브에이전트는 YAML frontmatter가 포함된 마크다운 파일입니다: 
---
name: code-reviewer
description: Expert code review specialist. Use for quality, security, and maintainability reviews.
tools: Read, Grep, Glob, Bash  # Optional - inherits all tools if omitted
---

서브에이전트의 시스템 프롬프트가 여기에 들어갑니다. 이것은 서브에이전트의
역할, 능력, 문제 해결 접근 방식을 정의합니다.

서브에이전트가 따라야 할 구체적인 지시사항, 모범 사례, 제약 조건을
포함하세요.

​
구성 필드

필드필수설명
name예소문자와 하이픈을 사용한 고유 식별자
description예이 서브에이전트를 언제 사용할지에 대한 자연어 설명
tools아니오허용된 도구의 쉼표로 구분된 목록. 생략하면 모든 도구를 상속

​
SDK가 서브에이전트를 사용하는 방법

Claude Code SDK를 사용할 때 파일시스템에 정의된 서브에이전트가 자동으로 사용 가능합니다. Claude Code는:
  1. .claude/agents/ 디렉토리에서 서브에이전트를 자동 감지합니다
  2. 작업 매칭을 기반으로 자동으로 호출합니다
  3. 전문화된 프롬프트와 도구 제한을 사용합니다
  4. 각 서브에이전트 호출에 대해 별도의 컨텍스트를 유지합니다
SDK는 파일시스템 구성을 존중합니다 - 런타임에 서브에이전트를 생성하는 프로그래밍 방식은 없습니다. 모든 서브에이전트는 SDK 실행 전에 파일로 정의되어야 합니다.

​
서브에이전트 예시

코드 리뷰어, 테스트 러너, 디버거, 보안 감사자를 포함한 서브에이전트의 포괄적인 예시는 메인 서브에이전트 가이드를 참조하세요. 이 가이드에는 효과적인 서브에이전트 생성을 위한 상세한 구성과 모범 사례가 포함되어 있습니다.

​
SDK 통합 패턴

​
자동 호출

SDK는 작업 컨텍스트를 기반으로 적절한 서브에이전트를 자동으로 호출합니다. 서브에이전트의 description 필드가 언제 사용되어야 하는지 명확히 나타내도록 하세요: 
---
name: performance-optimizer
description: Use PROACTIVELY when code changes might impact performance. MUST BE USED for optimization tasks.
tools: Read, Edit, Bash, Grep
---

​
명시적 호출

사용자는 프롬프트에서 특정 서브에이전트를 요청할 수 있습니다: 
// SDK를 사용할 때 사용자는 서브에이전트를 명시적으로 요청할 수 있습니다:
const result = await query({
  prompt: "code-reviewer 서브에이전트를 사용하여 인증 모듈을 확인하세요"
});

​
도구 제한

서브에이전트는 tools 필드를 통해 제한된 도구 액세스를 가질 수 있습니다:
  • 필드 생략 - 서브에이전트가 사용 가능한 모든 도구를 상속 (기본값)
  • 도구 지정 - 서브에이전트가 나열된 도구만 사용 가능
읽기 전용 분석 서브에이전트의 예시: 
---
name: code-analyzer
description: Static code analysis and architecture review
tools: Read, Grep, Glob  # No write or execute permissions
---

당신은 코드 아키텍처 분석가입니다. 코드 구조를 분석하고,
패턴을 식별하며, 변경 없이 개선사항을 제안하세요.

​
관련 문서