Claude Code Subagent

• 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/>핵심 맥락 유지됨

Agent를 만드는 기준

1단계: Agent vs Skill 분리 판단

아래 4가지 질문을 순서대로 확인한다. 하나라도 YES이면 Agent 후보이다.

flowchart TD
    Q1{{"자기완결적인가?"}}
    Q2{{"도구 접근을<br/>제한해야 하는가?"}}
    Q3{{"대량 출력이<br/>예상되는가?"}}
    Q4{{"도메인 특화<br/>system prompt가<br/>필요한가?"}}

    AGENT["✅ Agent"]
    SKILL["💡 Skill / Main 처리"]

    Q1 -->|YES| AGENT
    Q1 -->|NO| SKILL
    Q1 -->|"YES지만 확인 필요"| Q2

    Q2 -->|YES| AGENT
    Q2 -->|NO| Q3

    Q3 -->|YES| AGENT
    Q3 -->|NO| Q4

    Q4 -->|YES| AGENT
    Q4 -->|NO| SKILL

”자기완결적인가?” 구체적 기준

추상적인 “자기완결적”을 3가지 조건으로 풀면:

조건	YES → Agent	NO → Skill
입력이 명확한가? 한 문장으로 지시 가능?	”CLAUDE.md + plan.md 읽고 구현 문서 작성해"	"사용자가 뭘 원하는지 물어보면서 만들어”
중간 판단 불필요한가? 혼자 끝까지 가능?	코드 분석 → 문서 생성 (판단 기준이 prompt에 있음)	초안 → 사용자 확인 → 수정 → 재확인
결과물이 독립적인가? 다른 결과 없이도 의미 있음?	”Flutter 구현 문서” (Web 없이도 의미 있음)	“3개 플랫폼 통합 요약” (3개 결과 필요)

도구 제한

특정 도구만 허용하거나 차단해야 하면 반드시 Agent이다.

• 예: 읽기 전용 탐색 에이전트 → tools: Read, Glob, Grep (Write/Edit 차단)
• 예: DB 읽기 전용 → hooks.PreToolUse로 SELECT만 허용

대량 출력

코드베이스 탐색, 테스트 실행, 로그 분석 등 출력이 많은 작업은 메인 컨텍스트를 오염시키므로 Agent로 격리하고 요약만 반환받는다.

도메인 특화 prompt

플랫폼별 아키텍처, 컨벤션, 패턴 등 특화된 system prompt가 필요하면 Agent로 분리하여 .claude/agents/에 정의한다.

2단계: Agent로 결정된 후 세부 설계

질문	결정 사항
비용 최적화: 어떤 모델이 적합한가?	haiku (파일 탐색) / sonnet (구현 분석) / opus (아키텍처 설계)
실패 복구: Agent 실패 시 대안이 있는가?	Skill이 직접 처리할 수 있는 fallback 경로 확보

안티패턴

하지 말 것	이유	대안
파일 1개당 Agent 1개	오버헤드만 증가	도메인 단위로 묶기
Agent가 Agent 생성	불가능 (공식 제약)	Skill chaining 또는 Main orchestration
사용자 확인이 2회 이상 필요한 작업을 Agent로	Agent는 사용자 상호작용 불가	Skill로 전환
모든 작업을 Agent로	컨텍스트 전환 비용	단순 작업은 Main에서 직접

Skill vs Agent 판단 기준

핵심 차이

속성	Skill	Agent (Subagent)
실행 위치	Main conversation 내부	별도 conversation (격리)
컨텍스트	Main과 공유	독립 (전달받은 것만 사용)
사용자 상호작용	가능	불가 (결과만 반환)
도구 제한	불가 (Main 도구 전부 사용)	가능 (tools 필드)
중첩 호출	Skill → Agent 가능	Agent → Agent 불가
적합한 작업	오케스트레이션, 사용자 확인 루프	독립적 분석/생성, 대량 출력

오케스트레이션 패턴

오케스트레이션 = 여러 작업을 순서대로 또는 동시에 실행시키고, 결과를 모아서, 다음 단계로 넘기는 역할

sequenceDiagram
    autonumber
    actor User
    participant Skill as Skill (오케스트레이터)
    participant A1 as Agent A
    participant A2 as Agent B

    User->>Skill: "문서 생성해줘"
    Note over Skill: Phase 1: 입력 수집
    Skill->>User: "어떤 기획서?"
    User->>Skill: "plan.md"

    Note over Skill: Phase 2: Agent 병렬 호출
    par 병렬 실행
        Skill->>A1: "Flutter 문서 만들어"
        Skill->>A2: "Web 문서 만들어"
    end
    A1-->>Skill: flutter-impl.md 초안
    A2-->>Skill: web-impl.md 초안

    Note over Skill: Phase 3: 사용자 확인
    Skill->>User: "Flutter 문서 확인해주세요"
    User->>Skill: "수정해줘"
    Skill->>Skill: 직접 Edit 수정

    Note over Skill: Phase 4: 파일화
    Skill->>Skill: 링크 연결 + 저장
    Skill-->>User: "완료!"

왜 Agent가 오케스트레이터가 될 수 없는가?

오케스트레이터가 해야 할 일	Agent	Skill
사용자에게 질문	❌	✅
다른 Agent 호출	❌	✅ (Main이 호출)
여러 결과 취합/조율	❌	✅

→ 여러 Agent를 조율하는 역할 = 반드시 Skill

빌트인 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 컨텍스트에 주입됨

context: fork 없음 (인라인 실행)

sequenceDiagram
    autonumber
    actor User
    participant Main as 메인 에이전트
    participant Skill as SKILL.md

    User->>Main: /api-conventions
    Main->>Skill: SKILL.md 읽기
    Skill-->>Main: 마크다운 내용 반환
    Note over Main: context: fork 없음<br/>→ 프롬프트에 직접 주입
    Main->>Main: 스킬 내용을 기반으로<br/>메인 컨텍스트에서 직접 실행
    Main-->>User: 결과 응답
    Note over Main: ⚠️ 스킬 내용이<br/>메인 컨텍스트에 축적됨

context: fork 있음 (서브에이전트 위임)

sequenceDiagram
    autonumber
    actor User
    participant Main as 메인 에이전트
    participant Skill as SKILL.md
    participant Sub as Explore (Subagent)

    User->>Main: /deep-research "auth 모듈"
    Main->>Skill: SKILL.md 읽기
    Skill-->>Main: 마크다운 + frontmatter 반환
    Note over Main: context: fork 감지<br/>agent: Explore 확인
    Main->>Sub: Task 도구 호출<br/>prompt = 스킬 마크다운<br/>($ARGUMENTS → "auth 모듈" 치환)
    Note over Sub: 격리된 컨텍스트에서<br/>Read, Grep, Glob으로<br/>독립 작업 수행
    Sub-->>Main: 결과 요약만 반환
    Main-->>User: 요약 전달
    Note over Main: ✅ 메인 컨텍스트 깨끗<br/>요약만 남음

Skill에서 Subagent 실행 예제

---
name: deep-research
description: 코드베이스를 탐색하여 주제를 조사
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob
---
 
# Research Task
 
**주제:** $ARGUMENTS
 
1. Glob으로 관련 파일 찾기
2. Grep으로 패턴 검색
3. 결과 요약

Skill 주요 Frontmatter 필드

필드	설명	예시
context	fork 시 서브에이전트에서 실행	context: fork
agent	위임할 에이전트 타입	Explore, Plan, general-purpose
allowed-tools	퍼미션 없이 사용 가능한 도구	Read, Grep, Glob
$ARGUMENTS	전체 인자 치환	/skill hello world → "hello world"
$0, $1	위치별 인자 치환	/skill a b → $0=a, $1=b
!`command`	실행 전 셸 명령 출력 주입	!`gh pr diff $0`
disable-model-invocation	true 시 사용자만 호출 가능	Claude 자동 호출 차단

핵심 제약

규칙	가능 여부
Skill이 Task 도구 직접 호출	불가 — 스킬은 프롬프트 확장일 뿐
context: fork로 에이전트 위임	가능 — 메인 에이전트가 Task 호출
서브에이전트가 다른 서브에이전트 생성	불가 — 공식 제한

참고 문서

• Claude Code Subagents 공식 문서
• Claude Code Skills 공식 문서