Claude Code Subagent의 개념 소개

소개

Claude Code를 사용하여 복잡한 작업을 처리할 때 다음과 같은 딜레마에 직면했을 수 있습니다. 주요 대화의 맥락이 점점 길어지고 AI가 이전의 중요한 정보를 "잊기" 시작하며 응답 품질이 점차 저하됩니다.

이 문제를 해결하기 위해 Subagent가 탄생했습니다.

Skills가 Claude의 "작업 매뉴얼"인 경우 Subagent는 귀하가 고용하는 "정규직 직원"입니다. 이들은 자체 독립 워크스테이션(컨텍스트)을 갖고 특정 유형의 작업에 집중하며 완료 후 결과를 보고합니다.

하위 에이전트 이해

당신이 회사의 CEO라고 상상해보십시오. 회사 규모가 작으면 모든 일을 직접 처리합니다. 그러나 비즈니스가 확장됨에 따라 재무 회계사, 채용 HR, 개발 엔지니어 등 정규 직원을 고용하기 시작합니다. 각 직원은 자신의 스테이션에서 근무하며 작업을 완료한 후 귀하에게 보고합니다.

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

기술적 관점에서 서브에이전트는 다음과 같은 특성을 지닌 전문 AI 보조자입니다.

왜 독립적인 컨텍스트가 필요한가요?

이는 Subagent의 핵심 설계 개념이며 깊은 이해가 필요합니다.

일반적인 대화에서는 모든 정보가 동일한 맥락에 쌓입니다. Claude가 코드 베이스를 검색하고, 파일을 분석하고, 수정하도록 하면 이 모든 중간 처리가 컨텍스트 공간을 차지합니다. 대화가 진행되고 상황이 더욱 혼잡해짐에 따라 Claude는 이전의 중요한 정보를 "잊기" 시작할 수 있습니다.

하위 에이전트는 다음을 변경합니다.

主对话（专注于高层目标）
│
├── 用户：帮我优化这个模块的性能
│
├── Claude：我来分析一下...
│   │
│   └── [调用 Explore Subagent]
│       │ 在独立上下文中：
│       ├── 搜索相关文件
│       ├── 分析代码结构
│       ├── 识别性能瓶颈
│       └── 返回：发现 3 个优化点...
│
└── Claude：根据分析，我发现 3 个优化点...

하위 에이전트의 분석 프로세스는 기본 대화를 오염시키지 않습니다. 주요 대화는 명확성과 초점을 유지하면서 정제된 결과만 얻었습니다.

내장 하위 에이전트 유형

Claude Code는 가장 일반적인 사용 시나리오를 다루는 세 가지 강력한 내장 하위 에이전트를 제공합니다.

하위 에이전트 탐색

타겟팅: 코드베이스를 빠르게 읽기 전용으로 탐색합니다.

특징:

• Haiku 모델 사용(빠르고 낮은 대기 시간)
• 엄격한 읽기 전용 - 파일을 생성, 수정 또는 삭제할 수 없습니다.
• 사용 가능한 도구: Glob, Grep, Read, Bash(읽기 전용 작업)

사용 시기: "이 기능은 어디에 구현되어 있나요?"와 같은 탐구적인 질문을 하면 그리고 "오류는 어떻게 처리되나요?" Claude는 자동으로 Explore Subagent를 호출합니다.

세부정보 수준:

하위 에이전트 계획

포지셔닝: 코드 베이스를 연구하고 구현 계획을 준비합니다.

특징:

• Sonnet 모델 사용(강력한 추론 기능)
• 전용 탐색 도구: Read, Glob, Grep, Bash
• 계획 모드에서 자동으로 호출됩니다.

사용 시기: 계획 모드에 들어가서 Claude가 계획을 제안하기 전에 연구를 수행해야 하는 경우 Plan Subagent는 자동으로 정보를 수집한 다음 연구 결과에 따라 계획 제안을 제공합니다.

범용 하위 에이전트

포지셔닝: 복잡한 다단계 작업을 처리합니다.

특징:

• Sonnet 모델 사용
• 모든 도구에 대한 액세스(읽기 및 쓰기 포함)
• 탐구와 수정이 필요한 복잡한 작업에 적합

사용 시기: 작업에 여러 단계가 포함되어 수정하기 전에 검색이 필요하거나 초기 검색이 실패하고 여러 전략을 시도해야 하는 경우.

나의 이해와 실천

세 가지 공식 내장 하위 에이전트를 주의 깊게 관찰하면 한 가지 공통점을 발견할 수 있습니다. 모두 연구 및 계획 작업입니다. Explore는 코드 베이스 탐색을 담당하고, Plan은 계획 수립을 담당하며, General-Purpose도 주로 연구 및 분석에 사용됩니다. 이들 중 어느 것도 코드 작성을 위해 특별히 설계된 것은 없습니다.

이는 Subagent에 대한 나의 이해를 확증해 줍니다. Subagent의 핵심 가치는 "클린 컨텍스트"가 아니라 주 에이전트가 작업에 집중할 수 있도록 하는 것입니다.

노동 형태의 분업

저의 사용방법은 매우 간단합니다. Subagent는 조사, 기획, 검토 등의 '정보수집' 업무를 담당하고, Main Agent는 실제 실행을 담당합니다.

Subagent（调研员）          主 Agent（执行者）
     │                           │
     ├── 探索代码库结构            │
     ├── 分析依赖关系              │
     ├── 制定实施计划              │
     └── 返回精炼的上下文 ──────────→ 基于上下文执行任务
                                  │
                                  ├── 编写代码
                                  ├── 修改文件
                                  └── 运行测试

Subagent에서 코드를 작성하도록 하면 어떨까요?

어떤 사람들은 주 에이전트가 여러 하위 에이전트를 예약하여 코드를 작성하는 것을 좋아합니다. 나는 이것이 신뢰할 수 없다고 생각합니다. 이유는 간단합니다. 컨텍스트가 심각하게 누락되었습니다.

하위 에이전트의 컨텍스트는 독립적입니다. 주요 대화에서 어떤 내용이 논의되었는지, 어떤 결정이 내려졌는지, 어떤 제약이 부과되었는지 알 수 없습니다. 코드 작성을 요청하는 것은 신입 사원에게 배경 정보 없이 작업을 완료하도록 요청하는 것과 같습니다. 생성된 코드가 기대와 일치하지 않을 가능성이 높습니다.

반대로 Subagent를 "연구원"으로 지정하는 것이 훨씬 더 합리적입니다.

• 연구 과제 자체에는 많은 맥락이 필요하지 않습니다.
• 코드 대신 정보가 반환되며, 이는 전체 컨텍스트를 기반으로 주체가 사용할 수 있습니다.
• 설문조사 결과가 편향되더라도 주체가 이를 수정할 수 있습니다.

나의 일일 사용량

1. 새 작업을 시작하기 전: Explore 에이전트가 관련 코드의 구조를 빠르게 이해할 수 있도록 하세요.
2. 복잡한 작업 계획: 계획 에이전트가 요구 사항을 분석하고 구현 단계를 공식화하도록 합니다.
3. 코드 검토: 검토 담당자가 코드 품질 및 보안 문제를 확인하도록 합니다.
4. 실제 코딩: 주체는 수집된 컨텍스트를 기반으로 코드를 작성합니다.

현재 제가 사용하고 있는 에이전트 목록은 다음과 같습니다.

이것의 장점은 "하위 에이전트 검색 프로세스 중에 생성된 중간 결과 묶음" 대신 "내가 알아야 할 정보"만 포함하여 주 에이전트의 컨텍스트 창이 깨끗하게 유지된다는 것입니다.

다른 기능과의 비교

Subagent vs Skills

이것이 가장 흔한 혼란입니다. 핵심 차이점: 기술은 클로드에게 지식을 주입합니다. 하위 에이전트는 독립 작업자를 생성합니다.

비유적으로 말하면, 기술은 훈련 자료와 같아서 클로드가 어떤 일을 하는 방법을 배울 수 있게 해줍니다. Subagent는 자신의 작업장에서 독립적으로 작업을 완료하고 결과를 보고하는 정규 직원과 같습니다.

두 가지를 결합할 수 있습니다. 코드 검토 하위 에이전트는 코드 사양 스킬을 로드하여 "전문가 + 전문 지식"의 결합된 효과를 얻을 수 있습니다.

하위 에이전트와 슬래시 명령 비교

슬래시 명령은 바로 가기 키이며 /review을 입력하면 미리 정의된 작업을 트리거할 수 있습니다. Subagent는 복잡한 다단계 작업을 자율적으로 완료할 수 있는 독립적인 작업자입니다.

Subagent vs Plugin

플러그인은 하위 에이전트를 포함할 수 있는 "컨테이너" 개념입니다.

Plugin（容器）
├── Commands（快捷命令）
├── Skills（知识包）
├── Agents（子代理）← 这就是 Subagent
└── Hooks（事件钩子）

플러그인의 agents/ 디렉터리에 하위 에이전트를 정의하고 플러그인과 함께 배포할 수 있습니다.

에이전트틱 디자인 패턴

Anthropic은 공식 문서에 6가지 핵심 Agentic 디자인 패턴을 요약합니다. 이러한 패턴을 이해하면 하위 에이전트 시스템을 더 효과적으로 설계하는 데 도움이 될 수 있습니다.

이러한 모드는 조합하여 사용할 수 있습니다. 예를 들어, 코드 품질 시스템은 다음 두 가지를 모두 사용할 수 있습니다.

• 병렬화: 보안 검사와 성능 분석을 동시에 실행
• 오케스트레이터-작업자: Master Claude는 여러 전문 하위 에이전트를 조정합니다.
• Evaluator-Optimizer: 생성 후 즉시 코드 검토

핵심 장점

컨텍스트 보호

Subagent의 가장 큰 가치는 주요 대화의 맥락을 보호하는 것입니다. 코드 검색, 파일 분석 등의 중간 프로세스가 메인 다이얼로그에 누적되지 않아 메인 다이얼로그가 항상 높은 수준의 목표에 집중할 수 있습니다.

전문화 기능

자세한 지침과 적절한 도구로 구성된 특정 도메인에 대한 특수 하위 에이전트를 생성할 수 있습니다. 특수 하위 에이전트는 범용 Claude보다 특정 작업에서 더 나은 성능을 발휘합니다.

유연한 권한 제어

각 하위 에이전트는 서로 다른 도구 액세스 권한을 가질 수 있습니다. 예를 들어 탐색 클래스 Subagent는 읽기 전용 권한만 부여하고 수정 클래스 Subagent는 쓰기 권한만 부여합니다. 이렇게 세밀하게 제어하면 보안이 향상됩니다.

재사용성

Subagent는 일단 생성되면 프로젝트 전체에서 재사용하거나 플러그인을 통해 팀과 공유할 수 있습니다.

서브에이전트를 사용해야 하는 경우

하위 에이전트 사용에 적합한 시나리오:

• 작업을 실행하려면 독립적인 컨텍스트가 필요합니다.
• 작업은 복잡한 다단계 작업 흐름입니다.
• 기본 대화와 다른 도구 세트가 필요합니다.
• 작업을 실행하는 데 시간이 오래 걸릴 수 있습니다.

하위 에이전트 사용에 적합하지 않은 시나리오:

• 간단한 일회성 쿼리
• 기본 대화와 긴밀한 상호 작용이 필요합니다.
• 미션을 빠르게 완료할 수 있습니다.

일반적인 애플리케이션 시나리오

코드 검토

代码审查 Subagent
├── 专门的审查提示
├── 只读工具（Read, Grep, Glob）
└── 输出：结构化的审查报告

코드 조각을 완성하면 Code Review Subagent가 주요 개발 작업을 방해하지 않고 독립적인 컨텍스트에서 코드를 검토하도록 할 수 있습니다.

디버깅 분석

调试 Subagent
├── 错误分析专家提示
├── 读写工具
└── 输出：根因分析 + 修复方案

오류가 발생하면 디버깅 하위 에이전트는 오류의 원인을 심층적으로 분석하고 다양한 가설을 시도한 후 최종적으로 복구 제안을 제공할 수 있습니다.

코드베이스 탐색

探索 Subagent
├── Haiku 模型（快速）
├── 只读工具
└── 输出：代码结构概览

새 프로젝트를 처음 접하는 경우 Explore Subagent를 사용하면 수많은 검색 결과로 인해 주요 대화가 복잡해지지 않고 코드 베이스를 신속하게 매핑할 수 있습니다.

학습 리소스

공식 리소스

커뮤니티 리소스

요약

Claude Code Subagent는 기본적으로 상황에 독립적인 전문 AI 도우미입니다. 컨텍스트 격리를 통해 복잡한 작업에서 정보 과부하 문제를 해결하고, 주요 대화를 항상 명확하고 집중적으로 유지합니다.

세 가지 핵심 단어를 기억하세요.

개념을 이해한 후 다음 글 "Claude Code Subagent 실용 가이드"에서는 사용자 정의 서브에이전트 생성, 도구 권한 구성, 실제 프로젝트에서의 모범 사례 등을 실습해 보겠습니다.

Subagent가 불러올 수 있는 스킬에 대해 알고 싶으시면 "클로드 스킬이란?"을 읽어보세요. 배포용 Subagent를 패키징하려면 "Claude Code 플러그인이란 무엇입니까"를 읽어보시기 바랍니다.