claudekit / guides / subagents
[ Guide · Advanced · 10분 ]

Subagent로 작업 분리하기

published · updated

Subagent를 활용해 메인 컨텍스트를 분리하고 작업을 병렬화하는 방법을 안내합니다. 언제 Subagent가 적합한지, 어떻게 정의하는지 다룹니다.

Subagent가 해결하는 문제

긴 세션에서 다음 같은 비효율이 발생합니다:

  • 검색 결과와 로그 출력이 메인 컨텍스트를 채워 토큰 예산 잠식
  • 코드 리뷰처럼 다른 시각이 필요한 작업을 메인 에이전트가 그대로 자체 평가 (편향)
  • 독립적 작업들을 순차 처리하느라 시간 낭비

Subagent는 독립 컨텍스트로 분리된 보조 에이전트입니다. 결과만 메인에 돌려주므로 컨텍스트가 깨끗하게 유지되고, 병렬 실행도 가능합니다.

Subagent 정의

subagent는 frontmatter가 있는 마크다운 파일 하나로 정의합니다. 둘 수 있는 위치와 우선순위는 다음과 같습니다.

위치범위우선순위
managed settings조직 전체1 (가장 높음)
--agents CLI 플래그현재 세션2
.claude/agents/현재 프로젝트3
~/.claude/agents/모든 프로젝트4
플러그인의 agents/플러그인이 켜진 곳5 (가장 낮음)

같은 이름의 subagent가 여러 위치에 있으면 우선순위가 높은 쪽을 사용합니다. 예전의 /agents 마법사는 Claude Code 2.1.198에서 제거됐습니다. 지금은 Claude에게 subagent를 만들어 달라고 하거나 위 디렉토리의 파일을 직접 편집합니다.

.claude/agents/code-reviewer.md 예시:

---
name: code-reviewer
description: |
  Use after a logical chunk of code is written to review it against
  the original plan and project coding standards.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer. Given a recent change set, identify:
1. Bugs and logic errors
2. Security vulnerabilities
3. Deviations from project conventions

Report only high-confidence issues. Skip stylistic nitpicks.

frontmatter 필드

필수 필드는 name과 description 두 가지입니다.

필드용도
name호출 시 사용할 이름 (필수)
descriptionClaude가 이 subagent에 작업을 맡길 조건 (필수, Skill의 description과 같은 역할)
tools이 에이전트가 사용 가능한 도구. 생략하면 subagent가 쓸 수 있는 모든 도구를 상속
modelsonnet, opus, haiku, fable, 전체 모델 ID(예: claude-opus-5-5), inherit 중 선택. 생략하면 CLAUDE_CODE_SUBAGENT_MODEL 환경 변수, 그다음 메인 대화의 모델 순으로 정해짐

이 밖에 disallowedTools, permissionMode, maxTurns, skills, mcpServers, hooks, memory, background, effort, isolation, color 등을 지원합니다. 여러 단어로 된 필드는 camelCase로 쓰며, Claude Code는 인식하지 못하는 필드를 오류 없이 무시하므로 필드 이름의 오타에 주의합니다.

호출 방식

자동 호출

description에 명시된 조건에 맞으면 메인 에이전트가 자동으로 Agent 도구를 호출합니다.

명시적 호출

자연어로 지정하거나, @-멘션으로 특정 subagent를 지목합니다.

code-reviewer 에이전트로 src/auth/ 디렉토리 검토해줘
@"code-reviewer (agent)" 인증 관련 변경 사항 확인해줘

세션 전체를 특정 subagent로 실행하려면 claude --agent code-reviewer를 사용하고, 프로젝트 기본값으로 두려면 .claude/settings.json에 { "agent": "code-reviewer" }를 넣습니다. 둘 다 있으면 CLI 플래그가 우선합니다.

병렬 실행

다음을 병렬로:
- code-reviewer로 src/auth/ 검토
- security-auditor로 의존성 취약점 확인
- test-coverage-analyzer로 테스트 누락 영역 분석

메인 대화에서 띄운 subagent는 기본적으로 백그라운드에서 실행됩니다. Claude는 기다리지 않고 작업을 이어가다가, 각 subagent가 끝날 때 알림으로 결과를 받습니다. 한 세션에서 동시에 실행되는 subagent는 기본 20개이며 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS로 바꿀 수 있습니다.

fork와 중첩 실행

  • fork — 새 컨텍스트로 시작하는 대신 부모 대화를 그대로 이어받는 subagent입니다. 기본으로 켜져 있으며 CLAUDE_CODE_FORK_SUBAGENT=0으로 끌 수 있습니다.
  • 중첩 — subagent는 다시 자기 subagent를 띄울 수 있으며, 기본으로 메인 대화 아래 3단계까지 허용됩니다. CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1로 설정하면 중첩을 끕니다.

적합한 작업 vs 부적합한 작업

적합부적합
코드 리뷰 (독립 시각)메인 작업의 다음 단계
광범위한 검색, 탐색사용자와 상호작용 필요
보안, 성능 감사진행 상태 공유 필요
여러 영역 동시 분석짧고 단순한 질문
긴 결과를 메인 컨텍스트에서 격리메인의 의사결정에 즉시 반영

좋은 description 작성

자동 호출되려면 description이 정확해야 합니다.

좋은 예

description: |
  Use after writing or modifying code in a logical chunk
  (a feature, a bugfix, a refactor) to review the change against
  the original plan and project coding standards. Reports
  high-confidence issues only.

나쁜 예

description: Reviews code  # 너무 일반적, 트리거 조건 모호

도구 권한 제한

tools 필드로 Subagent가 사용할 수 있는 도구를 제한합니다.

tools: Read, Grep, Glob   # 읽기 전용 — 코드 변경 불가

리뷰, 감사 에이전트는 보통 읽기 전용으로 제한하는 것이 안전합니다. 상속받은 도구 중 일부만 빼려면 disallowedTools를 사용합니다.

실전 사용 패턴

패턴 1: 메인 컨텍스트 보호

긴 검색 결과나 로그가 필요하면 Subagent로 위임 후 요약만 받습니다. Explore는 코드베이스 검색과 분석에 쓰는 내장 읽기 전용 subagent입니다.

Explore 에이전트로 'authentication' 키워드를 src/ 전체에서 찾고, 발견 위치와 패턴을 200자 이내로 요약해줘

패턴 2: 독립 검토

자체 작업을 자체 평가하면 편향이 생깁니다. Subagent에게 “독립 시각으로 검토”를 요청합니다.

code-reviewer 에이전트로 방금 변경한 마이그레이션이 안전한지 독립 검토. 내 분석에 동의하지 말고 자체 판단으로.

패턴 3: 병렬 분석

다음을 병렬로:
- agent-A로 X
- agent-B로 Y
- agent-C로 Z

다음 단계

  • Superpowers — subagent-driven-development, dispatching-parallel-agents 등 subagent를 활용하는 스킬 포함 (superpowers:code-reviewer 에이전트는 v5.1.0에서 제거됨)
  • Code Review, PR Review — 검토 전용 에이전트 모음
  • Skill 직접 만들기 — Subagent 호출을 Skill로 표준화하는 패턴
  • Subagent 공식 문서 — frontmatter 필드 전체 목록과 최신 동작
§ 9

자주 묻는 질문

자주 묻는 질문
§ 9.1
Subagent는 무엇인가요?
메인 대화에서 분리된 별도 컨텍스트로 실행되는 보조 에이전트입니다. 독립된 작업, 검색, 검토를 위임하면 메인 컨텍스트를 깨끗하게 유지할 수 있고, 여러 에이전트를 병렬로 실행해 작업 시간도 줄어듭니다.
§ 9.2
언제 Subagent를 써야 하나요?
독립적이고 결과만 받으면 되는 작업(코드 리뷰, 광범위한 검색, 보안 감사)에 적합합니다. 반대로 메인 컨텍스트의 진행 상태가 필요한 협업 작업은 메인에서 직접 하는 것이 효율적입니다.
§ 9.3
어떻게 정의하나요?
프로젝트의 `.claude/agents/`, 사용자 전체에 쓰는 `~/.claude/agents/`, 또는 플러그인의 `agents/` 디렉토리에 `<agent-name>.md`를 만듭니다. frontmatter에 필수 필드인 `name`, `description`을 넣고 필요하면 `tools`, `model` 등을 추가한 뒤, 본문에 시스템 프롬프트를 작성합니다.
§ 9.4
여러 Subagent를 병렬 실행할 수 있나요?
네. 메인 대화에서 띄운 subagent는 기본적으로 백그라운드에서 실행되므로, 여러 개를 요청하면 동시에 진행되고 각각 끝날 때 Claude가 알림을 받습니다. 한 세션에서 동시에 실행되는 subagent는 기본 20개까지입니다.
§ 9.5
Subagent와 Plugin은 어떻게 다른가요?
Plugin은 슬래시 커맨드, 훅, Skills를 묶은 패키지이고, Subagent는 그 안에 포함될 수도 있는 독립 실행 단위입니다. Plugin이 컨테이너라면 Subagent는 실행 가능한 작업자입니다.