Claude Code 서브에이전트는 특정 작업을 맡기는 전문 AI 어시스턴트입니다. 각 서브에이전트는 자체 컨텍스트 윈도와 시스템 프롬프트, 허용 도구를 갖고 독립적으로 일한 뒤 결과만 메인 대화로 돌려줍니다. 테스트 실행·문서 조회처럼 출력이 많은 곁작업을 분리해 메인 세션을 깨끗하게 유지하는 데 특히 유용합니다. (기준 시점: 2026년 6월 · 공식: code.claude.com/sub-agents)
서브에이전트란
공식 문서에 따르면 서브에이전트는 특정 종류의 작업을 처리하도록 사전 구성된 AI 어시스턴트입니다. 각 서브에이전트는 고유한 목적과 전문 영역을 갖고, 메인 대화와 분리된 자체 컨텍스트 윈도에서 동작하며, 허용된 도구와 커스텀 시스템 프롬프트로 행동이 결정됩니다. Claude Code가 어떤 작업이 서브에이전트의 설명(description)과 맞는다고 판단하면 그 작업을 위임하고, 서브에이전트는 독립적으로 일한 뒤 결과를 반환합니다.
왜 쓰나
- 컨텍스트 보존 — 곁작업의 시끄러운 출력(테스트 로그·문서·파일 내용)이 서브에이전트 안에 머물고, 메인 대화에는 요약만 돌아옵니다.
- 전문성 — 특정 도메인용 상세 지침으로 다듬어, 그 작업의 성공률을 높입니다.
- 재사용 — 한 번 만들면 여러 프로젝트에서 쓰고 팀과 공유할 수 있습니다.
- 유연한 권한 — 서브에이전트마다 도구 접근 범위를 다르게 둘 수 있어, 강력한 도구를 특정 에이전트로 한정할 수 있습니다.
만들기
가장 쉬운 방법은 /agents 명령입니다. 실행하면 "Create New Agent"에서 프로젝트/사용자 레벨을 고르고, 설명과 허용 도구를 정합니다(Claude로 초안을 생성한 뒤 다듬는 방식을 권장합니다). 또는 마크다운 파일로 직접 만들 수도 있습니다. 서브에이전트는 결국 마크다운 파일 하나로, 맨 위 YAML frontmatter(name·description·tools)가 설정이고 본문이 그 에이전트의 시스템 프롬프트가 됩니다.
어디 두나
- 프로젝트 서브에이전트 —
.claude/agents/. 코드베이스 규칙에 의존하는 워크플로에 적합하고, git으로 팀과 공유됩니다. - 사용자 서브에이전트 —
~/.claude/agents/. 리포 탐색·문서 조회처럼 어디서나 쓰는 습관에 적합합니다.
참고로 서브에이전트는 메인 Claude Code의 기본 시스템 프롬프트를 그대로 물려받지 않습니다. 자체 프롬프트와 기본 환경 정보만 갖기 때문에 오히려 의도대로 빚기 쉽습니다.
어떻게 위임되나
Claude는 각 서브에이전트의 description을 라우팅 힌트로 삼아 위임 여부를 결정합니다. 따라서 좋은 서브에이전트는 단순한 페르소나가 아니라, "언제 이걸 써야 하는지"가 분명히 적힌, 도구와 지침이 맞춰진 반복 작업 묶음입니다. 설명을 명확히 쓸수록 적절한 작업이 자동으로 위임됩니다.
알아둘 점
- 한 단계 깊이 — 서브에이전트는 또 다른 서브에이전트를 만들 수 없습니다. 오케스트레이션(여러 전문가 호출·결과 병합)은 메인 세션에서 합니다.
- 병렬 실행 — 독립 작업을 여러 서브에이전트로 동시에 돌릴 수 있습니다.
- 기본 제공 — 커스텀을 만들지 않아도 범용 서브에이전트 등 기본 도우미가 포함됩니다(구체 목록은 버전에 따라 다름).
- 토큰 — 서브에이전트도 자체 컨텍스트에서 토큰을 씁니다. 잘 쓰면 메인을 가볍게, 남용하면 예산을 태웁니다.
관련 글
- 슬래시 명령어 —
/agents로 관리 - Claude Code Skills — 능력 확장 방식 비교
- 사용법 가이드 — 터미널에서 쓰기
- CLAUDE.md 가이드 — 프로젝트 맥락 유지
고지: 이 글은 Anthropic 공식 Claude Code 문서(code.claude.com·docs.anthropic.com)를 기준으로 작성했습니다. 기본 제공 서브에이전트 목록·환경변수·세부 동작은 정책과 버전에 따라 달라질 수 있습니다(변동 가능). 명령·경로·frontmatter 필드도 시간이 지나면 바뀔 수 있으니 최신 정보는 공식 문서에서 확인하세요. 본 사이트는 Anthropic 공식 사이트가 아닙니다.