[Claude Code] 4. subagent

1. Subagent란?

• 특정 종류의 작업을 전담하는 독립된 AI 작업자
• ✅ 주 대화의 Claude가 전체 작업을 조정하고, 필요한 하위 작업을 Subagent에 위임
• ✅ Subagent는 별도의 컨텍스트에서 파일 탐색, 분석, 테스트, 수정 등을 수행한 뒤 결과를 요약하여 주 대화로 반환함

 

목적

목적	내용
주 컨텍스트 보존	대량의 코드, 로그, 테스트 결과를 별도 컨텍스트에서 처리
전문화	백엔드, 테스트, 인프라 등 작업별 시스템 프롬프트 적용
병렬 처리	서로 독립적인 작업을 동시에 수행
권한 분리	읽기 전용, 수정 가능, Bash 제한 등 역할별 도구 통제
구성 재사용	동일한 분석·검토 절차를 여러 요청에서 반복 사용
비용 조절	단순 탐색은 Haiku, 구현은 Sonnet 등으로 분리

 

한계

• ✅ 주 대화에 대량의 검색 결과가 들어오는 것을 막아 주 컨텍스트 소비를 줄이는 효과는 있음
• ⚠️ 각 Subagent가 별도 모델 호출을 수행하므로 전체 API 사용량은 증가할 수 있음

 

2. 내장 Subagent

Explore

Plan

General-Purpose

 

3. 사용자 정의 Subagent 생성

파일 구조

• YAML formatter: 이름, 역할, 모델, 도구, 권한 등 실행 설정
• markdown: Subagent가 따라야 할 시스템 프롬프트

 

ex) backend-analyzer

---
name: backend-analyzer
description: 백엔드 모듈 구조와 기능 영향 범위를 분석한다.
tools: Read, Grep, Glob, Bash
model: sonnet
---

당신은 백엔드 아키텍처 분석 담당자다.

요청받은 기능과 관련된 모듈, 클래스, 데이터 흐름을 조사한다.
코드는 수정하지 않고 영향 범위와 변경 필요 사항만 보고한다.

필드	역할
tools	사용할 수 있는 도구 허용 목록
disallowedTools	사용하지 못하게 할 도구 목록
model	사용할 모델 지정
permissionMode	권한 승인 방식 지정
maxTurns	최대 작업 턴 제한
skills	시작 시 로드할 Skill
memory	세션 간 지속되는 기억 저장
hooks	도구 실행 전후 검증 자동화
background	항상 백그라운드 실행 여부
effort	작업 추론 수준
isolation	임시 Git worktree에서 작업
mcpServers	해당 에이전트만 사용할 MCP 서버

 

생성 위치

• 프로젝트 전용: 프로젝트루트/.claude/agents/
• 사용자 공통: ~/.claude/agents/

 

 

 

 

출처

• Claude Code Docs - 사용자 정의 subagent 만들기