Claude Code의 Sub Agent 개요
AI 코딩 도구는 이제 단순한 코드 생성기 이상의 역할을 요구받고 있습니다. 특히 현대 소프트웨어 개발 환경에서는 다양한 도메인과 워크플로우를 다루는 상황이 많기 때문에, 하나의 AI 인스턴스만으로는 충분히 정교하고 일관된 결과를 도출하기 어렵습니다. 이런 한계를 극복하기 위해 Anthropic는 Claude Code에 서브 에이전트(Sub Agents) 라는 개념을 도입했습니다. 이는 특정 작업에 특화된 AI 보조 인스턴스를 생성하고, 이를 통해 효율적이고 반복 가능한 AI 기반 개발 환경을 구축할 수 있도록 설계된 기능입니다.
Sub Agent는 각기 다른 역할과 도구 권한을 가진 독립적인 AI이며, 사용자는 이를 명시적으로 호출하거나 Claude가 자동으로 선택하게 할 수 있습니다. 이 기능은 복잡한 문제를 분할하고, 각 문제에 특화된 처리 전략을 부여함으로써 더 나은 응답 품질과 높은 문맥 유지 능력을 제공합니다.
특히 Claude Code가 지향하는 자율형 코딩(Agentic Coding)의 철학은 단일 에이전트에 모든 책임을 부여하는 것이 아니라, 상황에 따라 다양한 Sub Agent들을 설계하고 연계하는 방식으로 발전해 왔습니다. Anthropic에서 공개한 Claude Code 활용 모범 사례 문서에서 살펴볼 수 있듯, Sub Agent를 사용하여 필요한 파일들을 읽고, 복잡한 문제를 분석하며, 전체 워크플로우를 계획하고 코드를 작성할 수 있습니다.
Sub Agent의 개념
Sub Agent는 Claude Code에서 설정 가능한 독립형 AI 구성 요소로, 특정 도메인 또는 작업에 특화된 목적을 가지고 작동합니다. 각 Sub Agent는 고유한 시스템 프롬프트, 도구 접근 권한, 자체 컨텍스트 윈도우를 가지며, 메인 Claude 인스턴스와 별개로 작업을 수행합니다. 이러한 구조 덕분에 긴 문맥을 유지하거나 반복적인 설명 없이 작업을 분산시킬 수 있습니다.
예를 들어, 하나의 Sub Agent는 테스트 코드 생성에 집중하고, 다른 하나는 로그 분석만 전담하며, 또 다른 Sub Agent는 데이터 시각화 결과를 검토하는 역할을 맡을 수 있습니다.
Sub Agent 구조와 설정 방법
Sub Agent는 Markdown 형식의 파일로 설정되며, YAML 프론트매터를 포함하여 이름(name), 소개(description), 도구(tools) 등의 필드를 정의합니다. 설정 파일은 다음 두 위치 중 하나에 배치됩니다:
.claude/agents/: 프로젝트 전용 에이전트 (우선순위 높음)~/.claude/agents/: 사용자 전체용 에이전트 (우선순위 낮음)
각 에이전트는 name 필드를 기준으로 식별되며, 같은 이름이 겹칠 경우 프로젝트 디렉토리에 있는 설정이 우선됩니다. 또한 tools 필드를 통해 Sub Agent가 사용할 수 있는 도구를 제한하거나 상속 설정을 할 수 있습니다.
예를 들어, 코드를 리뷰하는 code-reviewer 에이전트는 다음과 같이 정의할 수 있습니다:
---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
---
You are a senior code reviewer ensuring high standards of code quality and security.
When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately
Review checklist:
- Code is simple and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed
Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)
Include specific examples of how to fix issues.
자동 위임과 명시적 호출
Claude는 대화 중 특정 요청이 Sub Agent의 설명과 일치한다고 판단되면 해당 Sub Agent를 자동으로 호출할 수 있습니다. 이와 별개로 사용자가 직접 /agents 명령어를 사용하거나 프롬프트에서 해당 Sub Agent의 이름을 언급함으로써 명시적으로 호출할 수도 있습니다.
특히 복잡한 문제를 해결할 때는 초기 탐색 단계에서는 Sub Agent를 활용하는 것이 효과적입니다. 예를 들어, 전체 계획을 수립하기 전에 Sub Agent를 통해 로그를 분석하거나, 특정 조건에 대한 타당성을 검토하게 하면, 메인 컨텍스트를 절약하면서도 정밀한 사전 작업이 가능해집니다.
다음은 여러 Sub Agent들을 함께 사용하는 예시 프롬프트입니다:
First use the code-analyzer sub agent to find performance issues, then use the optimizer sub agent to fix them
워크플로우에서의 활용 예시
Claude Code를 사용할 때, 다음과 같은 단계에서 Sub Agent를 활용하면 특히 유용합니다:
- 탐색과 계획 단계: Sub Agent를 통해 사전 지식 확보 및 문서 조사 수행
- 구현 단계: 메인 Claude가 코드를 작성하되, 보조 검증은 Sub Agent가 수행
- 검토 단계: 별도의 Sub Agent를 통해 구현 내용을 독립적으로 리뷰
- 병렬 작업 처리: 여러 Sub Agent를 각각의 디렉토리 혹은 Git worktree에서 병렬로 실행
이러한 사용 패턴은 특히 대규모 리팩토링, 코드 이관(migration), 테스트 작성 등에 효과적이며, 여러 Claude 인스턴스를 동시에 활용하는 멀티-에이전트(Multi-Agent) 구조를 가능하게 합니다.
Sub Agent 활용: 모범 사례 요약
Anthropic에서는 다음과 같은 Sub Agent 사용 방식을 권장합니다:
- 단일 책임 원칙 적용: Sub Agent는 하나의 역할에 집중하도록 구성
- 시스템 프롬프트 튜닝: 명확하고 구체적인 지시사항을 포함
- 도구 권한 최소화: 보안을 고려하여 필요한 도구만 허용
- 버전 관리에 포함: 프로젝트 설정은 Git 등에 커밋하여 팀 협업에 활용
- 문맥 분산을 위한 전략적 사용: 복잡한 작업일수록 메인 컨텍스트를 보호하며 활용
서브 에이전트(Sub Agent) 공식 문서
Claude Code 활용을 위한 모범 사례 문서
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 