Claude Code 완전 가이드 · 3 min read
Sub-Agents
독립된 컨텍스트에서 자율적으로 동작하는 전문 에이전트입니다. 메인 컨텍스트를 보호하면서 병렬 작업을 수행하는 핵심 도구입니다.
Frontmatter 필드 (14개)
| 필드 | 타입 | 설명 |
|---|---|---|
name | string | 고유 식별자 (소문자, 하이픈) |
description | string | 호출 시점 설명. "PROACTIVELY"로 자동 호출 |
tools | string/list | 허용 도구 목록 (생략 시 모든 도구 상속) |
disallowedTools | string/list | 거부할 도구 목록 |
model | string | haiku, sonnet, opus, inherit |
permissionMode | string | default, acceptEdits, dontAsk, bypassPermissions, plan |
maxTurns | integer | 최대 에이전틱 턴 수 |
skills | list | 시작 시 프리로드할 스킬 이름 |
mcpServers | list | 이 에이전트용 MCP 서버 |
hooks | object | 에이전트 스코프 라이프사이클 훅 |
memory | string | 영구 메모리: user, project, local |
background | boolean | 항상 백그라운드 태스크로 실행 |
isolation | string | "worktree"로 임시 git worktree에서 실행 |
color | string | CLI 출력 색상 (예: green, magenta) |
오케스트레이션 패턴 4가지
- 격리 실행 — "테스트를 서브에이전트로 실행하고 실패한 것만 리포트해"
- 병렬 리서치 — "인증, DB, API 모듈을 각각 별도 에이전트로 조사해"
- 체인 실행 — 순차 완료 — 각 에이전트의 결과가 다음 에이전트의 입력
- Writer/Reviewer — 한 세션이 코드 작성, 새 세션이 리뷰 (자기 코드 편향 제거)
Master-Clone 패턴 (Shrivu Shankar)
INFO: 커스텀 서브에이전트로 고정된 계층을 만드는 대신, 메인 에이전트에 전체 CLAUDE.md 컨텍스트를 주고 Agent(...)로 동적 클론을 생성하게 하세요. 커스텀 서브에이전트는 메인 에이전트에서 컨텍스트를 숨겨 전체적 추론을 방해할 수 있습니다.
DANGER: 서브에이전트는 bash 명령으로 다른 서브에이전트를 호출할 수 없습니다. 반드시
Agent(subagent_type="name")도구를 사용하세요.
TIP: "일반적인 QA, 백엔드 에이전트" 대신 기능별 전문 에이전트를 만드세요. 요청에 "use subagents"를 붙이면 Claude가 더 많은 컴퓨팅을 투입합니다. — Boris Cherny