Claude Subagent 완전 가이드

서론

Claude Code로 복잡한 작업을 처리할 때, 이런 곤경에 빠져본 적이 있을 것입니다: 메인 대화의 컨텍스트가 점점 길어지면서 AI가 이전의 중요한 정보를 "잊어버리기" 시작하고, 응답 품질이 점차 떨어지는 현상입니다.

Subagent(서브에이전트)는 바로 이 문제를 해결하기 위해 탄생했습니다.

Skills가 Claude에게 주는 "작업 매뉴얼"이라면, Subagent는 여러분이 고용한 "전담 직원"입니다. 이들은 자신만의 독립적인 작업 공간(컨텍스트)을 가지고, 특정 유형의 업무에 집중하며, 완료 후 결과를 보고합니다.

Subagent 이해하기

여러분이 한 회사의 CEO라고 상상해보세요. 회사 규모가 작을 때는 모든 업무를 직접 처리합니다. 하지만 사업이 확장되면서 전담 직원을 고용하기 시작합니다: 회계사는 재무를 담당하고, HR은 채용을 담당하며, 엔지니어는 개발을 담당합니다. 각 직원은 자신의 자리에서 업무를 처리하고, 완료 후 보고합니다.

Subagent는 Claude Code에서 바로 이러한 역할을 수행합니다.

기술적 관점에서 보면, Subagent는 전문화된 AI 어시스턴트로서 다음과 같은 특징을 가지고 있습니다:

독립 컨텍스트가 필요한 이유

이것은 Subagent의 가장 핵심적인 설계 이념으로, 깊이 이해할 가치가 있습니다.

일반 대화에서는 모든 정보가 하나의 컨텍스트에 쌓입니다. Claude에게 코드베이스를 검색하고, 파일을 분석하고, 수정을 진행하도록 할 때, 이 모든 중간 과정이 컨텍스트 공간을 차지합니다. 대화가 깊어질수록 컨텍스트는 점점 혼잡해지고, Claude는 초기의 중요한 정보를 "잊어버리기" 시작할 수 있습니다.

Subagent는 이 점을 바꿨습니다:

주 대화 (상위 목표에 집중)
│
├── 사용자: 이 모듈의 성능을 최적화해줘
│
├── Claude: 분석해보겠습니다...
│   │
│   └── [Explore Subagent 호출]
│       │ 독립 컨텍스트에서:
│       ├── 관련 파일 검색
│       ├── 코드 구조 분석
│       ├── 성능 병목 식별
│       └── 반환: 3개의 최적화 포인트 발견...
│
└── Claude: 분석 결과, 3개의 최적화 포인트를 발견했습니다...

Subagent의 분석 과정은 메인 대화를 오염시키지 않습니다. 메인 대화는 정제된 결과만 받으므로, 명확함과 집중력을 유지합니다.

Anthropic이 모범 사례에서 권장하는 바와 같습니다:

내장 Subagent 유형

Claude Code에는 세 가지 자주 사용되는 내장 Subagent가 기본 제공되어 바로 사용할 수 있습니다:

이러한 내장 에이전트는 작업 유형에 따라 자동으로 호출됩니다.

나의 이해와 실전 경험

공식 내장 세 가지 Subagent를 자세히 관찰하면 공통점을 발견할 수 있습니다: 모두 조사 및 계획 유형의 작업입니다. Explore는 코드베이스 탐색을 담당하고, Plan은 계획 수립을 담당하며, General-purpose조차 주로 조사와 분석에 사용됩니다. 코드를 작성하기 위한 전용 에이전트는 하나도 없습니다.

이는 Subagent에 대한 저의 이해를 뒷받침합니다: Subagent의 핵심 가치는 "깨끗한 컨텍스트"가 아니라, 메인 agent가 실행에 집중할 수 있게 하는 것입니다.

역할 분담 모델

저의 사용 방식은 간단합니다: Subagent는 조사, 계획, 리뷰와 같은 "정보 수집" 작업을 담당하고, 메인 agent는 실제 실행을 담당합니다.

Subagent (조사원)              메인 Agent (실행자)
     │                           │
     ├── 코드베이스 구조 탐색        │
     ├── 의존성 관계 분석            │
     ├── 실행 계획 수립              │
     └── 정제된 컨텍스트 반환 ────────→ 컨텍스트 기반으로 작업 실행
                                  │
                                  ├── 코드 작성
                                  ├── 파일 수정
                                  └── 테스트 실행

Subagent에게 코드를 작성하게 하지 않는 이유

일부 사람들은 메인 agent가 여러 subagent를 조율하여 코드를 작성하게 하는 것을 좋아하는데, 이 방식은 그다지 신뢰할 수 없다고 생각합니다. 이유는 간단합니다: 컨텍스트가 심각하게 부족합니다.

Subagent의 컨텍스트는 독립적이므로, 메인 대화에서 무엇을 논의했는지, 어떤 결정을 내렸는지, 어떤 제약이 있는지 알지 못합니다. 코드를 작성하게 하는 것은, 마치 배경 정보가 전혀 없는 상태에서 신입 사원에게 독립적으로 작업을 완수하라고 하는 것과 같습니다. 산출되는 코드가 기대와 다를 가능성이 높습니다.

반면, Subagent를 "조사원"으로 포지셔닝하면 훨씬 합리적입니다:

• 조사 작업 자체가 많은 컨텍스트를 필요로 하지 않습니다
• 반환하는 것은 코드가 아닌 정보이므로, 메인 agent가 완전한 컨텍스트를 기반으로 해당 정보를 활용할 수 있습니다
• 조사 결과에 편차가 있더라도 메인 agent가 보정할 수 있습니다

나의 일상적인 사용법

1. 새 작업을 시작하기 전: Explore 에이전트로 관련 코드의 구조를 빠르게 파악합니다
2. 복잡한 작업 계획 수립: Plan 에이전트로 요구사항을 분석하고 실행 단계를 수립합니다
3. 코드 리뷰: Review 에이전트로 코드 품질과 보안 문제를 점검합니다
4. 실제 코딩: 메인 agent가 수집된 컨텍스트를 기반으로 코드를 작성합니다

현재 사용 중인 agent 목록입니다:

이렇게 하면 메인 agent의 컨텍스트 윈도우가 깨끗하게 유지되어, "내가 알아야 할 정보"만 존재하고 "Subagent가 검색 과정에서 생성한 수많은 중간 결과"는 포함되지 않습니다.

Subagent 사용 방법

사용 가능한 에이전트 확인

/agents 명령어를 사용하면 현재 환경에서 사용 가능한 모든 Subagent를 확인할 수 있습니다:

/agents

이 명령은 내장 에이전트와 사용자가 설정한 커스텀 에이전트를 나열합니다.

자동 위임

대부분의 경우 어떤 Subagent를 사용할지 수동으로 지정할 필요가 없습니다. Claude가 작업 유형에 따라 적절한 에이전트를 자동으로 선택합니다:

• 코드 탐색 작업 → Explore Subagent
• 계획 수립이 필요한 경우 → Plan Subagent
• 복잡한 다단계 작업 → General-purpose Subagent

명시적 호출

특정 에이전트를 명확하게 사용하고 싶다면, 프롬프트에서 직접 지정할 수 있습니다:

Explore 에이전트를 사용하여 authentication이 포함된 모든 파일을 검색해줘

또는:

서브에이전트를 실행하여 이 모듈의 의존성 관계를 분석해줘

Subagent를 어디서 찾을 수 있는가

내장 에이전트

Claude Code에 기본 제공되는 세 가지 내장 에이전트(Explore, Plan, General-purpose)는 별도의 설정 없이 바로 사용할 수 있습니다.

커뮤니티 리소스

wshobson/agents - 코드 리뷰, 테스트 실행 등 자주 사용되는 에이전트를 포함한 우수한 Subagent 템플릿 라이브러리입니다:

이동

Claude Plugin Hub - 다양한 agent와 플러그인을 찾을 수 있는 플러그인 마켓플레이스입니다:

이동

커스텀 Subagent 생성

내장 에이전트와 커뮤니티 리소스 외에도, 자신만의 Subagent를 생성할 수 있습니다.

설정 파일 위치

설정 형식

각 Subagent는 YAML frontmatter와 시스템 프롬프트를 포함하는 Markdown 파일입니다:

---
name: code-reviewer
description: Reviews code for security and style issues. Use PROACTIVELY after code changes.
tools: Read, Grep, Glob
model: sonnet
---

You are a senior code reviewer focusing on:
- Security vulnerability detection
- Code style and best practices
- Performance optimization

## Review Output
1. **Critical Issues**: Security, correctness
2. **Warnings**: Style, performance
3. **Suggestions**: Refactoring opportunities

필드 설명

도구 권한

에이전트 역할에 따라 최소 필요 권한을 설정합니다:

고급 기능

Subagent는 독립적인 개체로서, 메인 agent의 대부분의 기능에 접근할 수 있습니다:

MCP 도구 접근

tools 필드를 생략하면 모든 MCP 도구가 자동으로 상속됩니다. 명시적으로 지정해야 하는 경우 형식은 다음과 같습니다:

tools: Read, Grep, mcp__github__create_issue, mcp__linear__list_issues

Skills 지식

Subagent가 특정 Skill의 지식을 사용해야 하는 경우, 시스템 프롬프트 본문에 명시합니다:

---
name: code-reviewer
description: Reviews code for quality issues
tools: Read, Grep, Glob
---

You are a code reviewer. Follow the guidelines in the code-standards skill.

When reviewing:
- Apply project coding standards
- Check for security issues

이렇게 하면 Subagent가 실행 시 관련 Skill의 지침을 참고합니다.

권한 모드

제한 사항

• 다른 Subagent를 호출할 수 없습니다 (무한 재귀 방지)
• 단계별 계획을 지원하지 않습니다

모범 사례

• 단일 책임: 각 에이전트는 하나의 명확한 목표에 집중합니다
• 최소 권한: 필요한 도구만 부여합니다
• 명확한 설명: description이 자동 호출의 품질을 결정하므로, "언제 사용하는지"를 명확히 작성합니다
• 버전 관리: 프로젝트 레벨 설정을 Git에 커밋하여 팀 간 공유를 용이하게 합니다

마무리

Subagent의 핵심 가치는 메인 agent가 실행에 집중할 수 있게 하는 것입니다. Subagent를 실행자가 아닌 조사원으로 포지셔닝하면, Claude Code의 효율이 크게 향상되는 것을 체감할 수 있습니다.

Claude Code의 기본 사용법에 아직 익숙하지 않다면, 먼저 나의 Claude Code 모범 사례를 읽고 핵심 명령어와 워크플로를 파악하시기 바랍니다.

추가 읽기

• Claude 시스템 아키텍처 완전 해석 -- Subagent의 전체 Claude 시스템에서의 위치
• Claude Skills란 무엇인가 -- Skills와 Subagent의 차이점 및 상호 보완 관계