서브에이전트는 클로드 코드/클로드 에이전트 생태계에 가장 유용한 추가 기능 중 하나입니다. 복잡한 워크플로를 더 작고 전문적인 AI "팀원"으로 나누고, 메인 스레드 컨텍스트를 보존하며, 도구 액세스를 안전하게 제한할 수 있습니다. 이 문서에서는 이에 대해 설명합니다. 하위 대리인은 무엇입니까?, 생성 및 호출 방법 (CLI, 파일 시스템 및 SDK) 설계 원칙 빌드할 때 따라야 할 사항 구체적인 샘플 코드 복사해서 적용할 수 있습니다.
하위 대리인이란 무엇입니까?
A 하위 대리인 Claude Code(또는 Claude Agent SDK)가 작업을 위임할 수 있는 사전 구성된, 범위가 좁은 AI 비서입니다. 각 하위 에이전트는 다음과 같은 작업을 수행합니다.
- 고유한 이름과 명확한 목적 설명이 있어야 합니다.
- 그것의에서 실행됩니다 자신의 컨텍스트 창 주요 대화와 분리되어 있으므로 세부 사항이 길게 늘어져 조정자의 맥락을 오염시키지 않습니다.
- 제한된 세트로 구성 가능 검색을 (파일 읽기/쓰기, bash, grep, MCP 도구 등) 및 특정 모델 선택이 가능합니다.
- 행동과 제약을 안내하는 시스템 프롬프트(하위 에이전트의 성격과 지침)가 포함되어 있습니다.
이러한 속성으로 인해 하위 에이전트는 토큰을 많이 사용하는 작업(연구, 대규모 로그 검색), 보안에 민감한 작업(스캐닝이나 잠재적으로 파괴적인 도구), 반복적이고 명확하게 지정된 작업(스타일 검사, 테스트 실행)에 적합합니다.
Anthropic은 빠르게 반복 작업을 해왔습니다. Claude Code CLI와 Agent SDK가 리팩토링되어 확장되었습니다. 클로드 에이전트 SDK번들 에이전트 및 관련 사용자 정의(슬래시 명령, MCP 서버, 후크)를 위한 플러그인 지원이 도입되었습니다. 기술 Claude.ai, Claude Code 및 Agent SDK에서 재사용할 수 있도록 도메인 워크플로를 패키징하는 방법을 제공합니다. 이러한 업데이트를 통해 공유, 설치 및 버전 여러 팀과 프로젝트에 걸쳐 하위 에이전트를 사용합니다. 프로덕션 워크플로를 구축할 계획이라면 플러그인/스킬 패키징과 SDK 기반 배포 패턴을 평가해야 합니다.
하위 에이전트가 중요한 이유
이것이 즉시 유용한 세 가지 이유는 다음과 같습니다.
- 컨텍스트 보존 — 길거나 노이즈가 많은 검색, 테스트 실행 또는 스캔은 기본 컨텍스트를 압도하는 대신 하위 에이전트 내에서 실행됩니다. 이를 통해 토큰 낭비를 줄이고 결과를 추론하기가 더 쉬워집니다.
- 전문 지식 — 작업에 맞게 조정된 시스템 프롬프트에 도메인 지식과 동작을 인코딩할 수 있습니다(예:
security-auditor(비밀, 종속성 문제, 안전하지 않은 셸 사용에 초점을 맞춥니다). - 더 안전한 권한 — 하위 에이전트당 도구 제한으로 폭발 반경이 줄어듭니다(문서 검토자는 읽기 전용 도구를 가질 수 있음; 테스트 실행자는
Bash하지만Edit). - 병렬화: 여러 개의 하위 에이전트를 동시에 실행하도록 설정할 수 있습니다(예:
style-checker,security-scanner,test-runner) 그리고 간단한 결과를 수집합니다. 비용이 많이 드는 독립적인 검사에 큰 이점이 있습니다.
Claude Code에서 하위 에이전트를 사용하기 위한 전제 조건
하위 에이전트를 구축하기 전에 다음 사항이 준비되었는지 확인하세요.
1) 클로드 코드 설치 및 인증
Claude Code CLI를 설치하거나 웹/IDE 통합을 사용하세요. CometAPI의 빠른 시작 및 설정 문서 지원되는 설치 방법(npm 글로벌 패키지 또는 기본 설치 프로그램)을 나열하고 설치를 확인하는 방법을 보여줍니다. claude --version / claude doctor. 당신은 또한 필요합니다 코멧API 빠른 시작에서 언급했듯이, CometAPI의 키를 사용하여 Claude 코드에 접근하는 것이 공식 모델보다 저렴하고 편리합니다.
2) 노드/환경(일부 설치 경로의 경우) 및 기본 셸 툴링
npm 패키지를 통해 설치하는 경우 Node.js가 설치되어 있어야 합니다(예제에서는 Node.js 18 이상이 일반적입니다). Agent SDK(JavaScript/TypeScript 또는 Python)를 사용하려면 SDK 종속성이 설치된 프로젝트가 필요합니다. 많은 튜토리얼에서는 표준 개발자 도구(git, bash, optional)를 사용한다고 가정합니다. gh GitHub 워크플로우를 위한 CLI).
3) 프로젝트 레이아웃 및 CLAUDE.md
가장 좋은 방법은 저장소 수준 도우미 문서를 유지하는 것입니다.CLAUDE.md) 및 프로젝트 범위 에이전트를 배치합니다. .claude/agents/ 팀원들이 이를 상속받도록 합니다. CLAUDE.md 파일은 Claude의 컨텍스트에 자동으로 삽입되어 세션 전반에 걸쳐 일관된 동작을 유도하는 데 도움이 됩니다. 각 하위 에이전트는 YAML 프론트매터가 포함된 마크다운 파일입니다. 최소 예시:
---
name: code-reviewer
description: Expert code review specialist. Use PROACTIVELY after code changes to check security, style, and maintainability.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer. When invoked:
1. Run `git diff` to identify modified files.
2. Focus review on changed code paths.
3. List security issues, probable false positives, and suggested fixes.
4. Provide a short, prioritized action list.
Return results in JSON with fields: summary, issues.
name소문자 식별자입니다.description자동 호출 및 매칭을 안내합니다.tools도구 접근을 제한합니다(모든 것을 상속하지 않음).model될 수 있습니다sonnet,opus,haiku및inherit.
4) 권한 및 MCP 서버(선택 사항이지만 일반적임)
워크플로에서 MCP(Model Context Protocol) 서버 또는 외부 도구(Puppeteer, Sentry, 사용자 지정 REST 도구)를 사용하는 경우 MCP 서버가 구성되어 있고 접속 가능한지 확인하세요. 민감한 작업(쓰기, bash, git commit)의 경우 허용 목록과 에이전트별 허용 범위를 신중하게 설정하세요. tools 범위 지정.
Claude Code에서 하위 에이전트를 만드는 방법
세 가지 주요 방법으로 하위 에이전트를 만들 수 있습니다. 대화형 CLI를 통해(/agents), 파일 시스템 마크다운 파일로 또는 Agent SDK를 통해 프로그래밍 방식으로 사용할 수 있습니다. 단계별 옵션은 다음과 같습니다.
Claude Code는 하위 에이전트를 생성하는 세 가지 실용적인 방법을 지원합니다.
- 대화형 CLI
/agentsUI — 세션 내에서 반복적으로 생성하는 데 가장 빠릅니다. - 파일 시스템 기반 — YAML 프론트매터로 Markdown 파일을 만듭니다.
.claude/agents/(프로젝트 수준) 또는~/.claude/agents/(사용자 수준). 프로젝트 에이전트의 우선순위가 더 높습니다. - 프로그래밍 방식(에이전트 SDK) — 코드에서 하위 에이전트를 정의합니다.
agents호출할 때 매개변수query(); SDK 기반 앱에 권장됩니다. 이 접근 방식은 하위 에이전트를 동적으로 생성하거나 애플리케이션에 내장해야 하는 경우에 이상적입니다.
빠른 상호작용 흐름(권장되는 첫 번째 단계)
- 터미널에서 Claude Code를 시작하거나 VS Code에서 명령 팔레트를 엽니다.
- 슬래시 명령으로 하위 에이전트 인터페이스를 실행합니다.
/agents
- 왼쪽 메뉴에서 새로운 에이전트 만들기프로젝트 수준 또는 사용자 수준 범위를 선택하고 이름/설명/도구/시스템 프롬프트를 입력한 후 저장합니다. Claude와 함께 초안을 생성한 후 수정할 수 있습니다. 저장 후 에이전트를 사용할 수 있습니다.
/agents명시적으로 또는 자동으로 호출될 수 있습니다.
파일 시스템 기반 하위 에이전트(Markdown + YAML 프런트매터)
하위 에이전트는 YAML 프론트매터가 있는 마크다운 파일로 저장됩니다. 다음 위치에 배치하세요.
- 프로젝트 범위 :
.claude/agents/*.md(가장 높은 우선순위) - 사용자 범위:
~/.claude/agents/*.md
기본 파일 구조:
---
name: code-reviewer
description: "Review recent code changes for security and style."
tools: Read, Grep, Glob, Bash # optional; omit to inherit
model: sonnet # optional; or 'inherit'
---
You are a senior code reviewer with expertise in security, performance, and best practices.
When reviewing:
- Identify security vulnerabilities
- Prioritize clarity and maintainability
- Always provide concise examples and suggested fixes
- If unsure, ask for the minimal reproducible snippet
몇 가지 구현 참고 사항:
name하이픈을 사용하여 소문자로 입력해야 합니다.- 생략
tools하위 에이전트가 모든 메인 스레드의 도구를 상속하도록 합니다. 도구를 명시적으로 나열하면 최소 권한 모델이 적용됩니다. model: 'inherit'메인 스레드와 일관된 동작을 위해 또는 모델 별칭을 지정합니다(예:sonnet,opus,haiku).
CLI JSON 정의(임시/세션 사용)
세션을 시작할 때 임시 하위 에이전트를 인라인으로 정의할 수 있습니다.
claude --agents '{
"code-reviewer": {
"description": "Expert code reviewer.",
"prompt": "You are a senior code reviewer. Focus on security and best practices.",
"tools": ,
"model": "sonnet"
}
}'
CLI 정의 에이전트는 스크립트 실행이나 실험에 유용합니다. 프로젝트 에이전트보다 우선순위는 낮지만 사용자 에이전트보다 우선순위는 높습니다.
프로그래밍 정의(에이전트 SDK - 앱에 권장됨)
애플리케이션이나 자동화를 구축하는 경우 Agent SDK를 통해 프로그래밍 방식으로 하위 에이전트를 정의합니다. agents 매개변수(가장 통합된 옵션입니다). 예시(TypeScript):
import { query } from '@anthropic-ai/claude-agent-sdk';
async function runReview() {
const result = await query({
prompt: "Assess the authentication module for security issues",
options: {
agents: {
"code-reviewer": {
description: "Expert code review specialist",
prompt: `You are a code review specialist...`,
tools: ,
model: "sonnet"
},
"test-runner": {
description: "Runs the test suite and analyzes failures",
prompt: `You run tests and summarize failures...`,
tools: ,
model: "sonnet"
}
}
}
});
console.log(result);
}
SDK는 또한 파일 시스템 기반 에이전트를 허용합니다(로드됩니다 .claude/agents/ 해당 패턴을 선호한다면 파일)을 사용할 수 있습니다. 프로그래밍 에이전트는 동적 워크플로 및 CI 통합에 매우 유용합니다.
Python의 경우 claude-agent-sdk 패키지는 유사한 패턴을 지원합니다. 사용할 수 있습니다. query() or ClaudeSDKClient 옵션, 도구 및 MCP 서버를 프로그래밍 방식으로 구성합니다. 빠른 시작 샘플은 Python SDK 저장소를 참조하세요.
하위 에이전트를 호출하는 방법
자동 위임
클로드 코드는 자동적으로 사용자 프롬프트가 하위 에이전트의 목적과 일치할 때 하위 에이전트를 선택합니다. 이는 메인 에이전트가 자동으로 적절한 전문가에게 작업을 할당하는 백그라운드 오케스트레이션에 유용합니다. 자동 선택의 정확도를 높이려면 명확한 하위 에이전트 설명과 집중적인 시스템 프롬프트를 활용하세요.
명시적 호출(명확성을 위해 권장됨)
대화 중에 에이전트를 명시적으로 호출할 수 있습니다.
> Use the code-reviewer subagent to check my recent changes
명시적 호출은 결정적이며 예상치 못한 위임을 피하려는 프로덕션 흐름에 권장됩니다.
SDK 오케스트레이터 패턴
SDK 앱의 일반적인 패턴:
- 포크 + 모으기: 여러 개의 하위 에이전트를 병렬로 실행하고, 각 에이전트의 간결한 답변을 수집한 다음, 주 에이전트에서 결과를 요약/병합합니다.
- 감독자 루프: 오케스트레이터는 하위 에이전트에게 작업을 할당하고, 결과를 검토한 후 결과를 수락하거나 재계산/설명을 요청합니다.
- 샌드박스 실행: 잠재적으로 위험한 기능(배포, 스크립트 실행)을 엄격하게 제한된 에이전트에게 제공하고 실행하기 전에 명시적으로 사람의 승인을 요구합니다.
이러한 패턴은 Agent SDK의 세션 관리, 후크, MCP 도구를 사용한 실제 구현에 매핑됩니다.
유용하고 안전하며 구성 가능한 하위 에이전트를 만드는 방법
1) 단일 책임과 명확한 프롬프트
각 하위 에이전트는 명확한 목적과 경계, 성공 기준, 출력 형식을 명시하는 시스템 프롬프트를 가져야 합니다. 원하는 출력이 구조화된 경우(JSON, 불릿 목록, 코드 패치), 구문 분석 오류를 줄이기 위해 하위 에이전트에게 정확하게 지시해야 합니다.
2) 도구에 대한 최소 권한
하위 에이전트에게 필요한 도구만 부여합니다. 예를 들어, 문서 검토자에게는 다음이 필요하지 않습니다. Write or Bash가능하면 기본적으로 읽기 전용으로 설정하고, 필요한 경우 도구 권한을 명시적으로 상향 조정하세요. 이렇게 하면 위험이 줄어들고 감사가 간소화됩니다.
3) 간결하고 구조화된 출력 반환
하위 대리인은 반환해야 합니다. 간결하고 최종적인 답변 장기간 지속되는 사고의 흔적보다는. 일반적인 패턴은 다음과 같습니다. 하위 에이전트의 컨텍스트 내에서 집중적인 작업을 수행한 후, 첨부 파일(패치, 파일 참조, JSON)과 함께 짧은 요약을 반환합니다. 이는 오케스트레이터의 컨텍스트 효율성을 극대화합니다.
4) 테스트 가능성 및 버전 관리
하위 에이전트 파일을 버전 관리 시스템에 저장하고, 작은 입력값에 대해 실제 실행을 수행하는 CI 테스트를 생성하고, 모델/툴셋을 고정하세요. 스킬과 플러그인을 사용하는 경우, 플러그인 마켓플레이스/버전 관리 패턴을 채택하여 업그레이드 및 롤백을 관리하세요.
5) 감사 후크 및 인간 참여 체크포인트
SDK 후크(PreToolUse 후크)를 사용하여 도구 호출을 가로채고, 파괴적인 행위에 대해 사용자의 승인을 요구합니다. 모든 도구 호출을 기록하여 재생 가능한 감사를 실시합니다. SDK는 이 패턴을 지원하기 위한 후크 및 권한 부여 메커니즘을 제공합니다.
애플리케이션 샘플 - 소규모의 프로덕션 파이프라인
아래는 일반적인 부분을 보여주는 간단한 예입니다. 파일 시스템 에이전트, 두 개의 에이전트(하나는 검토용, 하나는 테스트용)를 사용하는 SDK 호출, 그리고 간단한 오케스트레이션입니다.
1) 파일 시스템 에이전트: .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Use PROACTIVELY after code changes. Perform security, style, and maintainability review on modified files.
tools: Read, Grep, Glob
model: inherit
---
You are a meticulous senior code reviewer. When invoked:
1. Run `git diff --name-only` to find modified files.
2. For each modified file, read and look for security issues, suspicious patterns, or maintainability problems.
3. Return JSON:
{
"summary": "one-line summary",
"issues": ,
"recommended_changes":
}
2) 프로그래밍적 오케스트레이션(Node.js)
import { query } from '@anthropic-ai/claude-agent-sdk';
import fs from 'fs';
async function runPipeline() {
const result = query({
prompt: 'Run PR checks: security review then unit tests.',
options: {
agents: {
'code-reviewer': {
description: 'Use PROACTIVELY after code changes; output JSON with issues.',
prompt: fs.readFileSync('./.claude/agents/code-reviewer.md', 'utf8'),
tools: ,
model: 'sonnet'
},
'test-runner': {
description: 'Run test suite and summarize failing tests.',
prompt: `You are a test-runner. Execute tests and return JSON { summary, failing_tests[] }`,
tools:
}
}
}
});
for await (const message of result) {
// Implement streaming logic: messages may include subagent outputs
console.log(message);
}
}
runPipeline().catch(console.error);
배송 시 요청 사항: 전에, code-reviewer 팀 재사용을 위해 저장소에 저장됩니다. SDK 호출은 프로그래밍 에이전트가 우선시되는 것을 보여줍니다. tools 범위 지정을 통해 실수로 인한 쓰기를 방지할 수 있습니다.
고급 주제 및 패턴
동적 에이전트 구성
환경(dev 대 prod) 또는 심각도 수준(예:)에 따라 모델 및 도구 세트를 선택하는 매개변수화된 에이전트 팩토리를 만듭니다. strict vs balanced 보안 모드). SDK 예제는 런타임에 에이전트 정의를 생성하는 방법을 보여줍니다.
병렬화
여러 개의 읽기 전용 분석 에이전트(스타일, 보안, 테스트 커버리지)를 병렬로 분리하고 JSON 출력을 메인 스레드에서 집계합니다. 이를 통해 대규모 저장소의 작업 시간을 크게 단축할 수 있습니다.
플러그인 제공 에이전트
플러그인은 플러그인 매니페스트와 함께 패키징된 하위 에이전트를 제공할 수 있습니다. /agents 사용자 지정 에이전트와 함께 사용할 수 있으며 명시적으로 호출할 수 있습니다. 이를 사용하여 표준화된 에이전트를 여러 팀에 배포할 수 있습니다.
클로드 코드 cli를 사용하는 것이 가장 권장되는 곳입니다.
CometAPI가 이제 강력한 Claude Code CLI를 완벽하게 지원한다는 소식을 전해드리게 되어 기쁩니다. Claude Code에서 Comet API 모델을 사용하려면 Claude Code를 설치하고 얻은 Comet API 키와 기본 주소로 인증하기만 하면 됩니다.
CometAPI를 통해 클로드 코드를 사용해야 하는 이유는 무엇입니까?
인공지능의 주요 기능: 개발자를 위해 특별히 구축된 모델을 사용하여 코드를 쉽게 생성, 디버깅 및 최적화합니다.
- 유연한 모델 선택: 포괄적인 모델 범위를 통해 보다 원활하게 개발할 수 있습니다.
- 원활한 통합: API는 항상 사용 가능합니다. Claude Code를 기존 워크플로에 단 몇 분 만에 통합하세요.
- **CometAPI를 통해 Claude Code를 사용하면 더 많은 비용을 절감할 수 있습니다.**CometAPI에서 제공하는 Claude API는 공식 가격에서 20% 할인되어 있으며, 공식에서 최신 모델로 업데이트됩니다.
Claude Code cli를 사용할 준비가 되셨나요? API 가이드 자세한 지침은
AI에 대한 더 많은 팁, 가이드 및 뉴스를 알고 싶다면 저희를 팔로우하세요. VK, X 및 디스코드!
도 참조 CometAPI를 통해 Claude 코드를 설치하고 실행하는 방법은 무엇입니까?
마무리
하위 대리인을 다음과 같이 처리합니다. 재사용 가능한 버전 관리형 마이크로 페르소나. 작게 시작하세요: doc-reviewer 및 test-runner 저장소의 경우 체크인하세요 .claude/agents/, 그리고 CI에서 헤드리스를 사용하여 자동화합니다. claude -p프롬프트를 반복하고, 구조화된 출력을 추가하고, 도구 권한을 강화하세요.
가장 도움이 되는 사고방식: 클로드를 프로젝트 관리자로, 하위 담당자들을 팀의 전문가로 가정해 보세요. 관리자는 명확한 용어로 업무를 위임하고, 전문가들의 결과물을 취합하고, 최종 보고서를 작성합니다. 시간이 지남에 따라 안정성, 테스트 용이성, 그리고 개발자 워크플로우의 대량 자동화 능력이 향상되는 것을 보게 될 것입니다.