[공식문서읽기] Claude Code 내장 에이전트 완벽 가이드 - 서브에이전트의 종류, 사용법, 성능 평가

개요

Claude Code는 단순한 AI 코딩 도우미가 아니라, 여러 전문 에이전트를 조율하는 오케스트레이션 시스템입니다. 사용자가 복잡한 작업을 요청하면, Claude Code는 자동으로 적합한 서브에이전트를 생성하여 독립된 컨텍스트 윈도우에서 작업을 수행하고 결과만 돌려줍니다. 이 글에서는 Claude Code에 내장된 에이전트의 종류, 사용 방법, 실전 활용 패턴, 그리고 현재 성능 평가까지 정리합니다.

---

서브에이전트란?

서브에이전트(SubAgent)는 특정 작업 유형을 처리하기 위해 Claude Code가 자동으로 생성하는 전문화된 AI 어시스턴트입니다. 각 서브에이전트는 다음과 같은 독립적 환경에서 작동합니다.

• 독립된 컨텍스트 윈도우: 메인 대화와 별도의 메모리 공간에서 작업
• 커스텀 시스템 프롬프트: 각 에이전트의 역할에 맞는 전용 지시문
• 도구 접근 제한: 필요한 도구만 허용하여 안전성 확보
• 독립적 권한 관리: 에이전트별로 별도의 권한 설정 가능

서브에이전트의 핵심 이점은 컨텍스트 보존입니다. 메인 대화의 컨텍스트를 소모하지 않으면서 탐색, 분석, 코드 수정 등을 수행하고 요약된 결과만 반환합니다.

---

내장 에이전트 종류

Claude Code에는 4가지 유형의 내장 서브에이전트가 있습니다. 각각의 역할과 특성을 살펴보겠습니다.

1. Explore 에이전트

코드베이스를 빠르게 탐색하는 읽기 전용 에이전트입니다.

• 사용 모델: Haiku (빠른 응답, 낮은 지연)
• 사용 가능 도구: Read, Grep, Glob 등 읽기 전용 도구만 허용
• 용도: 파일 검색, 코드 탐색, 코드베이스 구조 분석

Claude가 코드베이스를 이해해야 할 때 자동으로 Explore 에이전트에 위임합니다. 호출 시 탐색 깊이를 quick(빠른 조회), medium(균형 잡힌 탐색), very thorough(포괄적 분석) 세 단계로 지정할 수 있습니다.

2. Plan 에이전트

계획 모드에서 코드베이스를 조사하는 리서치 에이전트입니다.

• 사용 모델: 메인 대화와 동일 모델 상속
• 사용 가능 도구: 읽기 전용 도구만 허용 (Write, Edit 차단)
• 용도: 구현 계획 수립 전 코드베이스 조사

Plan 에이전트는 계획 모드에서 Claude가 코드베이스를 파악해야 할 때 자동으로 위임됩니다. 서브에이전트는 다른 서브에이전트를 생성할 수 없기 때문에, Plan 에이전트를 통해 무한 중첩을 방지하면서도 필요한 정보를 수집합니다.

3. General-Purpose 에이전트

탐색과 수정 모두 가능한 만능형 에이전트입니다.

• 사용 모델: 메인 대화와 동일 모델 상속
• 사용 가능 도구: 모든 도구 접근 가능
• 용도: 복잡한 리서치, 다단계 작업, 코드 수정

탐색과 수정을 동시에 해야 하거나, 복잡한 추론이 필요하거나, 여러 의존적인 단계를 순차적으로 수행해야 할 때 Claude가 자동으로 General-Purpose 에이전트에 위임합니다.

4. 기타 헬퍼 에이전트

Claude Code에는 추가적인 도우미 에이전트들도 포함되어 있습니다.

• Bash 에이전트: 별도 컨텍스트에서 터미널 명령 실행 (모델 상속)
• statusline-setup: 상태 표시줄 설정 시 자동 호출 (Sonnet 사용)
• Claude Code Guide: Claude Code 기능에 대한 질문 처리 (Haiku 사용)

---

Task 도구: 에이전트 오케스트레이션의 핵심

서브에이전트를 실제로 실행하는 것은 Task 도구입니다. Task 도구는 Claude Code의 에이전트 오케스트레이션 시스템의 핵심으로, 전문 에이전트를 생성하고 병렬 또는 순차적으로 작업을 분배합니다.

실행 모드

Task 도구는 두 가지 실행 모드를 지원합니다.

• 포그라운드(Foreground): 서브에이전트가 완료될 때까지 메인 대화가 대기합니다. 빠른 작업이나 즉시 결과가 필요한 경우에 적합합니다.
• 백그라운드(Background): 서브에이전트가 비동기로 실행되며, 사용자는 다른 작업을 계속할 수 있습니다. 시간이 오래 걸리는 작업에 적합합니다.

병렬 실행

Task 도구의 가장 강력한 기능은 병렬 실행입니다. 독립적인 여러 작업을 동시에 여러 서브에이전트에 위임하여 전체 작업 시간을 크게 단축할 수 있습니다. 예를 들어 인증 모듈, 데이터베이스 모듈, API 모듈을 각각 별도의 서브에이전트가 동시에 조사하도록 할 수 있습니다.

모델 선택 전략

서브에이전트는 사용하는 모델에 따라 성능과 비용이 달라집니다.

• Haiku: 단순 검색, 빠른 분석, 반복 작업에 적합 (빠르고 저렴)
• Sonnet: 복잡한 분석과 코드 수정에 적합 (균형 잡힌 성능)
• Opus: 최고 수준의 추론이 필요한 복잡한 작업에 적합 (최고 성능)

일반적인 패턴은 메인 세션을 Opus로 실행하면서 서브에이전트는 Sonnet이나 Haiku로 설정하는 것입니다. 이렇게 하면 품질을 유지하면서 비용을 크게 절감할 수 있습니다.

---

커스텀 에이전트 만들기

내장 에이전트 외에도 프로젝트에 맞는 커스텀 서브에이전트를 만들 수 있습니다.

생성 방법

가장 간편한 방법은 /agents 명령어를 사용하는 것입니다.

/agents
→ Create new agent 선택
→ User-level 또는 Project-level 선택
→ Generate with Claude로 자동 생성 또는 직접 작성

파일 구조

서브에이전트는 YAML 프론트매터가 포함된 마크다운 파일로 정의합니다.

---
name: code-reviewer
description: 코드 품질과 보안을 검토하는 전문 에이전트
tools: Read, Glob, Grep, Bash
model: sonnet
---

코드를 리뷰할 때 품질, 보안, 유지보수성에 집중하세요.
수정이 필요한 사항은 우선순위별로 분류하여 보고하세요.

저장 위치에 따른 범위

• .claude/agents/: 해당 프로젝트에서만 사용. Git에 커밋하여 팀과 공유 가능
• ~/.claude/agents/: 모든 프로젝트에서 사용 가능한 개인 에이전트
• --agents CLI 플래그: 해당 세션에서만 사용되는 일회성 에이전트

주요 설정 옵션

커스텀 에이전트에서 활용할 수 있는 핵심 설정들입니다.

• tools / disallowedTools: 사용 가능한 도구를 허용 목록 또는 차단 목록으로 제어
• permissionMode: 권한 모드 설정 (default, acceptEdits, dontAsk, bypassPermissions, plan)
• maxTurns: 에이전트의 최대 실행 턴 수 제한
• skills: 시작 시 주입할 스킬 콘텐츠 지정
• mcpServers: 에이전트 전용 MCP 서버 연결
• hooks: 도구 사용 전후에 실행할 훅 스크립트 정의
• memory: 세션 간 학습을 위한 영속 메모리 활성화 (user, project, local)
• isolation: worktree로 설정하면 격리된 git 워크트리에서 실행

---

Agent Teams: 다중 에이전트 협업

2026년 2월에 출시된 Agent Teams는 서브에이전트의 진화된 형태입니다. 여러 Claude Code 인스턴스가 독립적으로 작업하면서 서로 소통하고 협업할 수 있습니다.

서브에이전트와의 차이점

• 서브에이전트: 메인 대화에서 작업을 위임받아 결과를 반환하는 단방향 구조
• Agent Teams: 팀 리더가 작업을 분배하고, 팀원들이 서로 소통하며 협업하는 양방향 구조

실전 사례

Anthropic 엔지니어링 블로그에 따르면, 16개의 에이전트가 병렬로 작업하여 Linux 커널을 컴파일할 수 있는 Rust 기반 C 컴파일러를 제작했습니다. 약 2,000회의 Claude Code 세션을 거쳐 10만 줄의 코드를 생성한 사례입니다.

---

실전 활용 패턴

병렬 리서치 패턴

독립적인 조사 작업을 여러 에이전트에 동시 위임하여 속도를 높입니다.

인증 모듈, 데이터베이스 모듈, API 모듈을 별도의 서브에이전트로 병렬 조사해줘

체이닝 패턴

서브에이전트를 순차적으로 연결하여 다단계 워크플로우를 구성합니다.

code-reviewer 에이전트로 성능 이슈를 찾고, optimizer 에이전트로 수정해줘

대용량 출력 격리 패턴

테스트 실행이나 로그 분석처럼 출력이 많은 작업을 서브에이전트에 위임하여 메인 컨텍스트를 보호합니다.

서브에이전트로 전체 테스트를 실행하고, 실패한 테스트의 에러 메시지만 보고해줘

비용 최적화 패턴

환경 변수 CLAUDE_CODE_SUBAGENT_MODEL을 설정하여 서브에이전트가 사용하는 모델을 제어할 수 있습니다. 메인 세션은 Opus, 서브에이전트는 Sonnet을 사용하는 것이 일반적인 최적화 전략입니다.

---

성능 평가

SWE-bench 벤치마크

현재 Claude Code의 코딩 성능은 업계 최고 수준입니다.

• Claude Opus 4.6: SWE-bench Verified 80.8%, SWE-bench Pro 59%
• Claude Sonnet 4.6: SWE-bench Verified 79.6% (Opus 대비 1/5 비용)
• 참고: OpenAI Codex는 SWE-bench에서 Claude와 경쟁 중이나, 에이전트 오케스트레이션 기능에서는 Claude Code가 앞서는 것으로 평가됩니다

실전 평가

벤치마크 성능이 높다고 해서 실제 프로젝트에서도 동일한 성과를 보장하지는 않습니다. 업계 전문가들의 평가를 종합하면 다음과 같습니다.

• 강점: 서브에이전트를 통한 병렬 처리로 복잡한 작업의 완료 시간이 크게 단축됩니다. 특히 코드 탐색과 리팩터링 작업에서 높은 생산성을 보입니다.
• 비용 효율: Sonnet 4.6이 Opus와 1.2포인트 차이로 80% 저렴한 비용을 제공하여, 대부분의 개발자에게는 Sonnet으로 충분합니다.
• Agent Teams 비용: 3명의 팀원으로 구성된 Agent Teams는 단일 세션 대비 약 3~4배의 토큰을 사용하지만, 복잡한 작업에서의 시간 절약이 비용을 상쇄합니다.
• 코드 리뷰: Claude Code Review(다중 에이전트 아키텍처)는 단순한 단일 패스 리뷰어보다 우수하지만, 전문 코드 리뷰 도구와 비교하면 아직 개선 여지가 있습니다.

사용 시 주의사항

• 과도한 병렬화 금지: 단순한 기능에 10개의 병렬 에이전트를 실행하면 토큰 낭비와 조율 오버헤드가 발생합니다
• 독립적인 작업만 병렬화: 서로 의존성이 없는 작업만 병렬로 실행해야 합니다
• 명확한 지시 필요: 서브에이전트 수와 각 에이전트의 역할을 구체적으로 지정하면 더 나은 결과를 얻습니다

---

마무리

Claude Code의 내장 에이전트 시스템은 단순한 코드 생성을 넘어, AI 기반 소프트웨어 개발 워크플로우의 새로운 패러다임을 제시합니다. Explore, Plan, General-Purpose 에이전트를 자동으로 활용하는 기본 기능만으로도 개발 생산성이 크게 향상되며, 커스텀 에이전트와 Agent Teams를 추가하면 팀 단위의 복잡한 프로젝트도 효율적으로 처리할 수 있습니다.

현재 SWE-bench 80% 이상의 성능은 실무에서도 체감할 수 있는 수준이며, 특히 Sonnet 4.6의 가성비가 뛰어나 대부분의 개발 작업에 적합합니다. 서브에이전트를 적극적으로 활용하되, 과도한 병렬화를 피하고 명확한 작업 범위를 설정하는 것이 핵심 팁입니다.

---

참고 자료

• Claude Code 공식 문서 - 서브에이전트 생성
• Claude Code 공식 문서 - Agent Teams
• The Task Tool: Claude Code's Agent Orchestration System - DEV Community
• Building a C Compiler with a Team of Parallel Claudes - Anthropic
• Claude Code Sub-Agents: Parallel vs Sequential Patterns
• Claude Code 심화 활용법 - 하이퍼리즘 기술 블로그
• AI 코딩 에이전트 실전 비교: Kiro vs Claude Code

이 글은 Claude Code를 활용하여 작성되었습니다.