Source: https://aiprimetech.io/ko/claude-code/subagents/

[홈](/ko/) › [Claude Code](/ko/claude-code/) › 서브에이전트

[개요](/ko/claude-code/)[설치](/ko/claude-code/install/)[CLI 참조](/ko/claude-code/cli/)[요금 및 한도](/ko/claude-code/pricing/)[Agent SDK](/ko/claude-code/sdk/)[스킬 및 플러그인](/ko/claude-code/skills/)[GitHub](/ko/claude-code/github/)[웹, 데스크톱 및 IDE](/ko/claude-code/web-and-desktop/)[모델](/ko/claude-code/models/)[오류](/ko/claude-code/errors/)[오픈 소스인가요?](/ko/claude-code/open-source/)[튜토리얼](/ko/claude-code/tutorial/)[학생용 안내](/ko/claude-code/for-students/)[QA 자동화](/ko/claude-code/qa-automation/)[Cursor와 비교](/ko/claude-code/vs-cursor/)[Codex 및 OpenCode와 비교](/ko/claude-code/vs-codex/)[하위 에이전트](/ko/claude-code/subagents/)[훅](/ko/claude-code/hooks/)[MCP](/ko/claude-code/mcp/)[생태계](/ko/claude-code/ecosystem/)[VS Code](/ko/claude-code/vscode/)[OpenRouter](/ko/claude-code/openrouter/)[요청 속도 제한](/ko/claude-code/rate-limits/)[중국어 가이드](/claude-code/zh/)

최종 업데이트: 2026년 10월 11일

# Claude Code 하위 에이전트: 작동 방식, 정의 방법, 에이전트 팀

서브에이전트는 자체 시스템 프롬프트, 자체 도구 권한, 그리고 가장 중요한 자체 컨텍스트 창을 가진 별도의 Claude Code 작업자입니다. 메인 세션은 서브에이전트에 작업을 위임하고 요약을 돌려받아 컨텍스트를 깔끔하게 유지합니다. 서브에이전트를 잘 활용하면 한 시간 만에 성능이 떨어지는 세션을 하루 종일 실행되는 세션으로 바꿀 수 있습니다.

## TLDR
- 다음 위치에 Markdown 파일로 정의합니다. .claude/agents/ (프로젝트) 또는 ~/.claude/agents/ (사용자용): 프런트 매터에는 name, description, tools, model을 지정하고, 본문에는 시스템 프롬프트를 작성합니다.
- Claude는 설명이 작업과 일치하면 자동으로 위임하고, 에이전트 이름을 지정하면 명시적으로 위임합니다.
- 각 서브에이전트는 자체 컨텍스트를 가지며 자체 토큰 사용량에 따라 과금됩니다. 결과는 요약된 형태로 반환됩니다.
- /agents 이를 생성하고 관리합니다. 에이전트 팀은 이 개념을 세션 간 조율로 확장합니다.

## 서브에이전트 정의하기 

```
# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Reviews a diff for correctness, security and test coverage. Use after any non-trivial change.
tools: Read, Grep, Glob, Bash(git diff *)
model: sonnet
---
You are a senior reviewer. Read the staged diff, list concrete defects with file:line,
flag untested paths, and stop. Do not edit files.
```

name 는 서브에이전트를 호출할 때 사용하는 이름입니다. description 는 Claude가 스스로 호출 여부를 판단하는 기준이므로, 직무명 대신 라우팅 규칙으로 작성하세요("단순하지 않은 변경 후에는 항상 사용" 등). tools 는 수행할 수 있는 작업을 제한합니다. 편집할 수 없는 검토자가 더 안전한 검토자입니다. model 는 모델 등급을 고정합니다. haiku 는 탐색과 분류에, sonnet 는 대부분의 작업에, opus 는 어려운 단계에 사용하고, 또는 inherit 를 사용해 상위 세션의 모델을 따릅니다. 

## 프로젝트 에이전트와 사용자 에이전트 

다음 위치의 파일은 .claude/agents/ 저장소에 속하며 저장소와 함께 이동합니다. 커밋하면 모든 팀원이 동일한 검토 에이전트, 테스트 작성 에이전트, 마이그레이션 에이전트를 사용할 수 있습니다. 다음 위치의 파일은 ~/.claude/agents/ 모든 프로젝트에서 개인용으로 사용합니다. 이름이 충돌하면 프로젝트 에이전트가 우선합니다. /agents 를 세션 내에서 사용하면 파일을 직접 수정하지 않고도 두 종류의 에이전트를 나열하고, 생성하고, 편집할 수 있습니다. 

## Claude가 작업을 위임하는 시점 

방식은 암시적 위임과 명시적 위임으로 나뉩니다. 암시적 위임에서는 메인 에이전트가 모든 서브에이전트의 설명을 읽고 작업이 일치하면 위임합니다. 설명에 사용 시점이 이미 명시되어 있다면 "이 작업에 code-reviewer 서브에이전트를 실행해 줘"라고 요청할 필요가 없습니다. 명시적 위임에서는 프롬프트에 이름을 지정합니다. 두 경우 모두 서브에이전트는 자체 컨텍스트에서 실행되며, 전달받은 정보와 직접 읽은 정보만 확인하고 결과를 반환합니다. 메인 세션은 그 결과를 요약하여 자체 기록에 반영합니다. 서브에이전트는 다른 서브에이전트를 생성하지 않으며, 계층 구조는 단일 하위 수준으로 제한됩니다. 

## 서브에이전트가 세션 비용을 낮게 유지하는 이유 

Claude Code는 매 턴마다 전체 대화를 다시 전송합니다. 파일 사십 개를 읽는 하위 에이전트는 자체 컨텍스트 창에서 작업하고, 상위 에이전트는 한 문단만 전달받습니다. 하위 에이전트가 없으면 그 사십 개 파일은 세션이 끝날 때까지 메인 컨텍스트에 남아 매 턴마다 다시 전송됩니다. 따라서 대규모 코드베이스에서는 Haiku 하위 에이전트로 탐색하고, Sonnet 하위 에이전트로 검토하며, 상위 에이전트의 컨텍스트는 의사결정에 사용하는 방식이 적합합니다. 각 하위 에이전트는 자체 토큰 사용량에 따라 과금됩니다. 무료인 것은 아니지만, 사용 범위가 제한됩니다. 

## 병렬 실행과 사용량 제한 

여러 하위 에이전트를 동시에 실행할 수 있으며, 각각은 병렬 스트리밍 요청입니다. 이는 어떤 엔드포인트에서든 동시 요청 제한에 가장 빨리 도달하는 방법이므로, 새 게이트웨이 계정에서는 두세 개를 병렬로 실행하는 것부터 시작하고 실제 워크로드가 생기면 동시 요청 한도 상향을 요청하세요. 그렇지 않을 때 발생하는 429은 오류 가이드에서 설명합니다. 

## 에이전트 팀 

최신 Claude Code 빌드에는 에이전트 팀이 추가되어 있습니다. 하나의 상위 에이전트가 수명이 짧은 하위 에이전트에 작업을 위임하는 대신, 여러 세션이 이름을 가진 팀원으로서 공유 작업 목록과 상호 메시지를 통해 협업합니다. 따라서 리더는 작업을 배정하고, 상태를 확인하고, 팀원을 중지할 수 있습니다. 설정으로 활성화해야 하는 실험적 기능이며 릴리스마다 달라지므로, 블로그 게시물 대신 다음을 확인하세요: claude --help 그리고 변경 로그에서 현재 플래그를 확인하세요. 개념적으로는 하위 에이전트에 지속성과 통신 기능을 더한 것이며, 비용 구조도 동일하지만 팀원 수만큼 늘어납니다. 

## 게이트웨이에서 

하위 에이전트와 팀은 상위 세션과 동일한 엔드포인트와 키를 사용하므로, ANTHROPIC_BASE_URL=https://aiprimetech.io 이 모든 경우에 적용됩니다. 정액제 무제한 요금제에서는 병렬 실행이 과금보다 공정 사용의 문제가 됩니다. 다중 에이전트를 많이 사용하는 사용자가 결국 이 요금제를 선택하는 경향이 있는 이유입니다. 

 | 계획 | 기간 | 가격

 | 1시간 무제한 | 1시간 | $1

 | 24시간 무제한 | 24시간 | $10

 | 1주 무제한 | 1주 | $49

 | 15일 무제한 | 15일 | $89

[모든 무제한 요금제 →](/ko/plans/)

## 먼저 무료로 사용해 보세요

신규 계정에는 $5의 무료 API 크레딧이 제공됩니다 사용할 코드: CLAUDECODE — Sonnet으로 저녁 한나절 Claude Code를 사용하기에 충분합니다. 이후에는 액면가의 7.69231배에 해당하는 크레딧이 제공됩니다.

```
export ANTHROPIC_BASE_URL=https://aiprimetech.io
export ANTHROPIC_API_KEY=your_key
```

[코드 CLAUDECODE로 계정 만들기](/register?promo=CLAUDECODE)

## 자주 묻는 질문

Claude Code의 하위 에이전트란 무엇인가요?

자체 시스템 프롬프트, 도구 권한, 모델 선택 및 컨텍스트 창을 갖춘 별도의 에이전트입니다. .claude/agents/의 Markdown 파일로 정의하며, 메인 세션이 이 에이전트에 작업을 위임합니다.Claude Code 하위 에이전트 문서는 어디에 있나요?

공식 참조 문서는 Anthropic의 Claude Code 문서에서 Sub-agents 항목에 있습니다. 이 페이지는 파일 형식, 위임이 이루어지는 시점, 비용을 설명하는 실용적인 안내입니다.하위 에이전트는 추가 비용이 드나요?

다른 요청과 마찬가지로 자체 토큰 사용량에 따라 과금됩니다. 대량으로 읽은 내용을 상위 컨텍스트에 넣지 않아 긴 세션에서는 비용을 절약할 수 있지만, Opus에서 여러 하위 에이전트를 병렬로 실행하면 비용이 더 많이 듭니다.에이전트 팀이란 무엇인가요?

하나의 상위 에이전트와 수명이 짧은 보조 에이전트 대신, 여러 Claude Code 세션이 이름을 가진 팀원으로서 메시지와 공유 작업 목록을 통해 협업하는 실험적 확장 기능입니다.

## 게이트웨이에서 Claude Code 실행하기

동일한 모델, 환경 변수 두 개, 액면가의 7.69231배에 해당하는 크레딧 또는 정액 무제한 요금제를 이용하세요. 신규 계정: 코드 CLAUDECODE로 $5의 무료 API 크레딧을 받으세요.[API 키 발급받기](/register?promo=CLAUDECODE) [무제한 요금제 보기](/ko/plans/)

AI Prime Tech는 독립 API 게이트웨이이며 Anthropic과 제휴 관계가 없고, Anthropic의 보증이나 후원을 받지 않습니다. “Claude”와 “Claude Code”는 Anthropic의 상표입니다. 여기에 설명된 Claude Code 기능은 작성 당시 Anthropic의 공개 문서를 기준으로 하며 자주 변경됩니다. 이 페이지의 가격과 모델 목록은 이 게이트웨이의 실시간 설정에서 가져옵니다.

## 더 많은 Claude Code 가이드

[Claude Code: 완벽 가이드](/ko/claude-code/)[Claude Code 설치 방법](/ko/claude-code/install/)[Claude Code CLI 문서: 명령어와 플래그](/ko/claude-code/cli/)[Claude Code 요금 및 한도 설명](/ko/claude-code/pricing/)[Claude Code SDK, 이제 Claude Agent SDK로](/ko/claude-code/sdk/)[Claude Code 스킬과 플러그인](/ko/claude-code/skills/)[GitHub에서 Claude Code 사용하기: App, Action 및 @claude](/ko/claude-code/github/)[Claude Code에 웹 인터페이스가 있나요? 웹, 데스크톱 및 IDE 설명](/ko/claude-code/web-and-desktop/)[Claude Code가 사용하는 모델과 변경 방법](/ko/claude-code/models/)[Claude Code 오류와 해결 방법](/ko/claude-code/errors/)[Claude Code는 오픈 소스인가요?](/ko/claude-code/open-source/)[Claude Code 튜토리얼: 첫 실전 세션](/ko/claude-code/tutorial/)[학생을 위한 Claude: Claude Code, API 및 교육 분야에서 실제로 제공되는 혜택](/ko/claude-code/for-students/)[QA 자동화에 Claude Code를 사용하는 방법](/ko/claude-code/qa-automation/)[Claude Code와 Cursor 비교: 어떤 도구를 언제 선택하고, 둘 다 어떻게 사용할까](/ko/claude-code/vs-cursor/)[Claude Code vs Codex vs OpenCode: 터미널 에이전트 비교](/ko/claude-code/vs-codex/)[Claude Code 훅: 에이전트 동작에 대한 결정론적 제어](/ko/claude-code/hooks/)[Claude Code MCP: 서버 연결, 범위, 원격 MCP와 실제 예제](/ko/claude-code/mcp/)[Claude Code 생태계: 라우터, 프레임워크, 플러그인과 이를 모아 둔 목록](/ko/claude-code/ecosystem/)[VS Code에서 Claude Code 사용하기: 확장 프로그램, 터미널 사용 방식, 오류](/ko/claude-code/vscode/)[Claude Code에서 OpenRouter를 사용하는 방법과 사용하지 않는 편이 나은 경우](/ko/claude-code/openrouter/)[Claude 요청 한도 오류: "API 오류: 요청 한도 도달"의 의미와 해결 방법](/ko/claude-code/rate-limits/)[Claude Code 사용법: 설치부터 일상적인 사용까지](/claude-code/zh/)