Subagents

• Claude Code에서 특정 작업을 전담하는 특수화된 하위 AI 어시스턴트
• 각 subagent는 독립된 컨텍스트 윈도우에서 실행
• 커스텀 시스템 프롬프트, 개별 도구 접근 권한, 독립적 퍼미션 보유
• Claude가 subagent의 description과 매칭되는 작업을 만나면 자동 위임 → 독립 작업 후 결과 반환

해당 개념이 필요한 이유

• 컨텍스트 오염 방지: 대량 출력(테스트 로그, 파일 탐색 결과)이 메인 대화를 오염시키지 않음
• 컨텍스트 윈도우 절약: 메인 대화의 컨텍스트를 핵심 작업에만 집중할 수 있음
• 제약 강제: subagent별로 사용 가능한 도구를 제한 (예: 읽기 전용)
• 비용 제어: 단순 작업은 Haiku 같은 저렴한 모델로 라우팅

AS-IS (Subagent 없이)

sequenceDiagram
    autonumber
    actor User
    participant Main as 메인 대화 컨텍스트

    User->>Main: "테스트 실행해줘"
    Main->>Main: 테스트 출력 500줄 생성
    Note over Main: 컨텍스트에 테스트 로그가<br/>그대로 축적됨

    User->>Main: "auth 모듈 구조 파악해줘"
    Main->>Main: 20개 파일 탐색 결과 생성
    Note over Main: 파일 내용이 컨텍스트에<br/>추가로 축적됨

    User->>Main: "이제 버그 수정해줘"
    Note over Main: ⚠️ 컨텍스트 오염<br/>테스트 로그 + 탐색 결과로<br/>핵심 대화가 밀려남<br/>→ 이전 맥락 유실

TO-BE (Subagent 사용)

sequenceDiagram
    autonumber
    actor User
    participant Main as 메인 대화 컨텍스트
    participant Sub1 as test-runner (Subagent)
    participant Sub2 as Explore (Subagent)

    User->>Sub1: "테스트 실행해줘"
    Note over Sub1: 독립 컨텍스트에서<br/>테스트 500줄 실행
    Sub1-->>Main: "3개 실패" (요약만 반환)

    User->>Sub2: "auth 모듈 구조 파악해줘"
    Note over Sub2: 독립 컨텍스트에서<br/>20개 파일 탐색
    Sub2-->>Main: 구조 요약 반환

    User->>Main: "이제 버그 수정해줘"
    Note over Main: ✅ 컨텍스트 깨끗<br/>요약만 남아있어<br/>핵심 맥락 유지됨

빌트인 Subagents

Agent	모델	도구	용도
Explore	Haiku (빠름)	읽기 전용	파일 탐색, 코드 검색, 코드베이스 분석
Plan	상속	읽기 전용	Plan 모드에서 코드베이스 리서치
general-purpose	상속	전체	복합 리서치, 다단계 작업, 코드 수정
Bash	상속	터미널	별도 컨텍스트에서 커맨드 실행
Claude Code Guide	Haiku	-	Claude Code 기능 관련 질문 응답

Subagent 파일 저장 위치

위치	경로	적용 범위
CLI 플래그	--agents '{JSON}'	현재 세션만 (우선순위 최상)
Project	.claude/agents/<name>.md	해당 프로젝트만
Personal	~/.claude/agents/<name>.md	내 모든 프로젝트
Plugin	<plugin>/agents/<name>.md	플러그인 활성화된 곳

Subagent 정의 방법

.claude/agents/ (프로젝트) 또는 ~/.claude/agents/ (개인)에 Markdown 파일 작성:

---
name: code-reviewer
description: 코드 품질과 보안을 리뷰하는 전문가
tools: Read, Glob, Grep
model: sonnet
---
 
당신은 코드 리뷰어입니다. 호출되면 코드를 분석하고
품질, 보안, 모범 사례에 대한 피드백을 제공하세요.

주요 Frontmatter 필드

필드	필수	설명
name	Yes	고유 식별자 (소문자, 하이픈)
description	Yes	Claude가 위임 판단에 사용하는 설명
tools	No	사용 가능한 도구 (생략 시 전체 상속)
disallowedTools	No	차단할 도구
model	No	sonnet, opus, haiku, inherit
permissionMode	No	퍼미션 동작 모드
maxTurns	No	최대 에이전트 턴 수
skills	No	시작 시 로드할 스킬 목록
Hooks	No	라이프사이클 훅
memory	No	영구 메모리 스코프 (user, project, local)

실행 방식: Foreground vs Background

• Foreground: 메인 대화를 블로킹. 퍼미션 프롬프트가 사용자에게 전달됨
• Background: 병렬 실행. 사전에 필요한 퍼미션을 승인받고 시작. Ctrl+B로 실행 중인 작업을 백그라운드로 전환 가능

Skills와의 관계

방향	설명
Skill → Subagent	Skill에 context: fork + agent: Explore 설정 시, 스킬 내용이 subagent의 태스크가 됨
Subagent → Skill	Subagent에 skills: [api-conventions] 설정 시, 스킬 내용이 subagent 컨텍스트에 주입됨

참고 문서

• Claude Code Subagents 공식 문서