서브에이전트 정의하기
# .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 |
먼저 무료로 사용해 보세요
신규 계정에는 $5의 무료 API 크레딧이 제공됩니다 사용할 코드: CLAUDECODE — Sonnet으로 저녁 한나절 Claude Code를 사용하기에 충분합니다. 이후에는 액면가의 7.69231배에 해당하는 크레딧이 제공됩니다.
export ANTHROPIC_BASE_URL=https://aiprimetech.io
export ANTHROPIC_API_KEY=your_key자주 묻는 질문
Claude Code의 하위 에이전트란 무엇인가요?
자체 시스템 프롬프트, 도구 권한, 모델 선택 및 컨텍스트 창을 갖춘 별도의 에이전트입니다. .claude/agents/의 Markdown 파일로 정의하며, 메인 세션이 이 에이전트에 작업을 위임합니다.
Claude Code 하위 에이전트 문서는 어디에 있나요?
공식 참조 문서는 Anthropic의 Claude Code 문서에서 Sub-agents 항목에 있습니다. 이 페이지는 파일 형식, 위임이 이루어지는 시점, 비용을 설명하는 실용적인 안내입니다.
하위 에이전트는 추가 비용이 드나요?
다른 요청과 마찬가지로 자체 토큰 사용량에 따라 과금됩니다. 대량으로 읽은 내용을 상위 컨텍스트에 넣지 않아 긴 세션에서는 비용을 절약할 수 있지만, Opus에서 여러 하위 에이전트를 병렬로 실행하면 비용이 더 많이 듭니다.
에이전트 팀이란 무엇인가요?
하나의 상위 에이전트와 수명이 짧은 보조 에이전트 대신, 여러 Claude Code 세션이 이름을 가진 팀원으로서 메시지와 공유 작업 목록을 통해 협업하는 실험적 확장 기능입니다.
게이트웨이에서 Claude Code 실행하기
동일한 모델, 환경 변수 두 개, 액면가의 7.69231배에 해당하는 크레딧 또는 정액 무제한 요금제를 이용하세요. 신규 계정: 코드 CLAUDECODE로 $5의 무료 API 크레딧을 받으세요.
API 키 발급받기 무제한 요금제 보기AI Prime Tech는 독립 API 게이트웨이이며 Anthropic과 제휴 관계가 없고, Anthropic의 보증이나 후원을 받지 않습니다. “Claude”와 “Claude Code”는 Anthropic의 상표입니다. 여기에 설명된 Claude Code 기능은 작성 당시 Anthropic의 공개 문서를 기준으로 하며 자주 변경됩니다. 이 페이지의 가격과 모델 목록은 이 게이트웨이의 실시간 설정에서 가져옵니다.