서브 에이전트는 “전문 프롬프트”가 아니라 자동 위임(라우팅) + 컨텍스트 격리 + 비용 최적화를 위한 실행 단위입니다.
공식 문서(Claude Code) 기준 메모
- Subagents는 Markdown + YAML frontmatter로 정의되며
/agents에서 생성/관리할 수 있습니다.- built-in subagents로 Explore/Plan/general-purpose 등이 기본 제공됩니다.
- Background subagents에서는 MCP tools를 사용할 수 없습니다.
cc-system의 subagent-creator 스킬은 서브 에이전트를 “Markdown + YAML frontmatter”로 정의합니다.
---
name: subagent-name
description: When to use this subagent (include "use proactively" for auto-delegation)
tools: Tool1, Tool2, Tool3
model: sonnet
permissionMode: default
skills: skill1, skill2
---
System prompt...
출처:
subagent-creator/SKILL.mdgithub.com
description은 ‘설명’이 아니라 ‘라우팅 규칙’이다서브 에이전트가 자동으로 호출되길 원하면 description이 사실상 라우터 역할을 합니다.
cc-system의 예시:
name: brand-logo-finder
description: Finds brand logos using Brandfetch. Use when user asks for a brand's logo
tools: WebFetch, WebSearch
model: haiku
출처:
서브 에이전트가 모든 도구를 쓸 수 있으면 편하지만, 운영 관점에서는 다음이 문제입니다.
추천:
Read, Grep, Glob, WebFetchRead, Edit, Write, BashBash 중심 + 필요한 읽기 도구Monet Registry의 build-and-screenshot 에이전트는 “빌드/스크린샷”이라는 좁은 역할에 맞춰 도구를 제한합니다.
name: build-and-screenshot
tools: Bash, Read, Glob, Edit
출처:
서브 에이전트를 만드는 가장 현실적인 이유 중 하나는 비용 라우팅입니다.
운영 팁:
관련:
권한 모드는 팀/개인 선호에 따라 달라지지만, 원칙은 단순합니다.
특히 “삭제/배포/결제/보안 관련”은 승인 흐름이 안전합니다.
서브 에이전트 시스템 프롬프트에 최소한 아래를 포함하세요.
간단 예시:
---
name: checklist-worker
description: Executes a checklist item and updates status. Use proactively in batch runs.
tools: Read, Edit, Write, Bash
model: inherit
---
You execute exactly one checklist item.
- Read the item
- Do the work
- Update status to completed/blocked
- Return a 5-line report
.claude/agents/ (해당 레포에서만)~/.claude/agents/ (모든 프로젝트에서)운영 추천:
서브 에이전트를 잘 만들었다면, 이제 “스킬 레이어”로 지식/절차를 모듈화합니다.