Claude Code: 제대로 알고 쓰자(sub agent편)

 

커스텀 서브에이전트 만들기

Claude Code에서 작업별 워크플로우 및 향상된 컨텍스트 관리를 위한 전문화된 AI 서브에이전트를 만들고 사용할 수 있다.

서브에이전트는 특정 유형의 작업을 처리하는 전문화된 AI 어시스턴트다. 각 서브에이전트는 커스텀 시스템 프롬프트, 특정 도구 접근 권한, 독립적인 권한을 가진 자체 컨텍스트 윈도우에서 실행된다. Claude가 서브에이전트의 설명과 일치하는 작업을 만나면, 해당 서브에이전트에 위임하고 서브에이전트는 독립적으로 작동하여 결과를 반환한다.

서브에이전트 장점

• 컨텍스트 보존 - 탐색 및 구현을 메인 대화에서 분리
• 제약 조건 강제 - 서브에이전트가 사용할 수 있는 도구 제한
• 구성 재사용 - 사용자 수준 서브에이전트를 프로젝트 간에 공유
• 동작 전문화 - 특정 도메인에 집중된 시스템 프롬프트 제공
• 비용 제어 - Haiku와 같은 더 빠르고 저렴한 모델로 작업 라우팅

Claude는 각 서브에이전트의 description을 사용하여 작업을 위임할 시기를 결정한다. 서브에이전트를 만들 때 Claude가 언제 사용해야 하는지 명확하게 설명을 작성해야한다.

Claude Code에는 Explore, Plan, general-purpose와 같은 내장 서브에이전트가 여러 개 포함되어 있다. 특정 작업을 처리하기 위해 커스텀 서브에이전트를 만들 수도 있다.

내장 서브에이전트

Claude Code에는 적절한 경우 Claude가 자동으로 사용하는 내장 서브에이전트가 포함되어 있다. 각 서브에이전트는 부모 대화의 권한을 상속하며 추가적인 도구 제한도 있다.

Explore

코드베이스 검색 및 분석에 최적화된 빠른 읽기 전용 에이전트다.

• 모델: Haiku (빠름, 낮은 지연시간)
• 도구: 읽기 전용 도구 (Write 및 Edit 도구 접근 거부)
• 목적: 파일 발견, 코드 검색, 코드베이스 탐색

Claude는 변경 없이 코드베이스를 검색하거나 이해해야 할 때 Explore에 위임한다. 이렇게 하면 탐색 결과가 메인 대화 컨텍스트에 포함되지 않는다.

Explore를 호출할 때 Claude는 철저함 수준을 지정한다. 대상 검색을 위한 quick, 균형잡힌 탐색을 위한 medium, 또는 포괄적인 분석을 위한 very thorough.

Plan

계획을 제시하기 전에 컨텍스트를 수집하기 위해 플랜 모드중에 사용되는 연구 에이전트다.

• 모델: 메인 대화에서 상속
• 도구: 읽기 전용 도구 (Write 및 Edit 도구 접근 거부)
• 목적: 계획을 위한 코드베이스 연구

플랜 모드에 있고 Claude가 코드베이스를 이해해야 할 때 Plan 서브에이전트에 연구를 위임한다. 이렇게 하면 무한 중첩을 방지하면서도(서브에이전트는 다른 서브에이전트를 생성할 수 없음) 필요한 컨텍스트를 수집한다.

General-purpose

탐색과 작업을 모두 필요로 하는 복잡하고 다단계 작업을 위한 능력있는 에이전트다.

• 모델: 메인 대화에서 상속
• 도구: 모든 도구
• 목적: 복잡한 연구, 다단계 작업, 코드 수정

Claude는 탐색과 수정을 모두 필요로 하거나, 결과를 해석하기 위한 복잡한 추론이 필요하거나, 여러 종속 단계가 필요한 경우 general-purpose에 위임한다.

Other

Claude Code에는 특정 작업을 위한 추가 헬퍼 에이전트가 포함되어 있다. 이들은 일반적으로 자동으로 호출되므로 직접 사용할 필요가 없다.

에이전트	모델	Claude가 사용하는 시점
Bash	상속	별도의 컨텍스트에서 터미널 명령 실행
statusline-setup	Sonnet	상태 라인 구성을 위해 /statusline을 실행할 때
Claude Code Guide	Haiku	Claude Code 기능에 대해 질문할 때

이러한 내장 서브에이전트 외에도 커스텀 프롬프트, 도구 제한, 권한 모드, 훅, 스킬을 사용하여 자체 서브에이전트를 만들 수 있다.

서브에이전트 구성하기

/agents 명령 사용하기

/agents 명령은 서브에이전트 관리를 위한 대화형 인터페이스를 제공한다. /agents를 실행하여 다음을 수행할 수 있다.

• 사용 가능한 모든 서브에이전트 보기 (내장, 사용자, 프로젝트, 플러그인)
• 가이드 설정 또는 Claude 생성으로 새 서브에이전트 만들기
• 기존 서브에이전트 구성 및 도구 접근 편집
• 커스텀 서브에이전트 삭제
• 중복이 있을 때 어떤 서브에이전트가 활성화되어 있는지 확인

서브에이전트를 만들고 관리할때 권장하는 방법이다. 수동 생성이나 자동화를 위해 서브에이전트 파일을 직접 추가할 수도 있긴하다.

서브에이전트 범위 선택하기

서브에이전트는 YAML frontmatter가 있는 마크다운 파일이다. 범위에 따라 다른 위치에 저장할 수 있다. 여러 서브에이전트가 같은 이름을 공유하면 우선순위가 높은 위치가 우선 적용된다.

위치	범위	우선순위	만드는 방법
--agents CLI 플래그	현재 세션	1 (최고)	Claude Code 실행 시 JSON 전달
.claude/agents/	현재 프로젝트	2	대화형 또는 수동
~/.claude/agents/	모든 프로젝트	3	대화형 또는 수동
플러그인의 agents/ 디렉토리	플러그인이 활성화된 곳	4 (최저)	플러그인과 함께 설치

프로젝트 서브에이전트 (.claude/agents/)는 코드베이스 특정 서브에이전트에 이상적이다. 버전 관리에 체크인하여 팀이 협력적으로 사용하고 개선할 수 있다.

사용자 서브에이전트 (~/.claude/agents/)는 모든 프로젝트에서 사용 가능한 개인 서브에이전트다.

CLI 정의 서브에이전트는 Claude Code를 실행할 때 JSON으로 전달된다. 해당 세션에만 존재하고 디스크에 저장되지 않으므로 빠른 테스트나 자동화 스크립트에 유용하다.

claude --agents '{
  "code-reviewer": {
    "description": "전문 코드 리뷰어. 코드 변경 후 적극적으로 사용하세요.",
    "prompt": "당신은 시니어 코드 리뷰어입니다. 코드 품질, 보안, 모범 사례에 집중하세요.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

--agents 플래그는 파일 기반 서브에이전트와 동일한 frontmatter 필드를 가진 JSON을 받는다: description, prompt, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, skills, 그리고 memory. 파일 기반 서브에이전트의 마크다운 본문에 해당하는 시스템 프롬프트에 prompt를 사용할 수 있다. 전체 JSON 형식은 CLI 참조를 참조하자.

서브에이전트 파일 작성하기

서브에이전트 파일은 구성을 위한 YAML frontmatter를 사용한 다음 마크다운으로 시스템 프롬프트를 작성한다.

서브에이전트는 세션 시작 시 로드된다. 파일을 수동으로 추가하여 서브에이전트를 만드는 경우 세션을 재시작하거나 /agents를 사용하여 즉시 로드할 수 있다.

---
name: code-reviewer
description: 품질과 모범 사례를 위한 코드 검토
tools: Read, Glob, Grep
model: sonnet
---

당신은 코드 리뷰어입니다. 호출되면 코드를 분석하고 품질, 보안, 모범 사례에 대한 구체적이고 실행 가능한 피드백을 제공하세요.

frontmatter는 서브에이전트의 메타데이터와 구성을 정의한다. 본문은 서브에이전트의 동작을 안내하는 시스템 프롬프트가 된다. 서브에이전트는 이 시스템 프롬프트만 받는다. 전체 Claude Code 시스템 프롬프트는 받지 않는다.

지원되는 frontmatter 필드

다음 필드는 YAML frontmatter에서 사용할 수 있다.

필드	필수	설명
name	O	소문자와 하이픈을 사용하는 고유 식별자
description	O	Claude가 이 서브에이전트에 위임해야 하는 시점
tools	X	서브에이전트가 사용할 수 있는 도구. 생략하면 모든 도구 상속
disallowedTools	X	거부할 도구, 상속되거나 지정된 목록에서 제거됨
model	X	사용할 모델: sonnet, opus, haiku, 또는 inherit. 기본값은 inherit
permissionMode	X	권한 모드: default, acceptEdits, delegate, dontAsk, bypassPermissions, 또는 plan
maxTurns	X	서브에이전트가 중지하기 전 최대 에이전틱 턴 수
skills	X	시작 시 서브에이전트의 컨텍스트에 로드할 스킬. 전체 스킬 콘텐츠가 주입되며, 호출만 가능한 것이 아니다. 서브에이전트는 부모 대화에서 스킬을 상속하지 않는다.
mcpServers	X	이 서브에이전트에서 사용 가능한 MCP 서버. 각 항목은 이미 구성된 서버를 참조하는 서버 이름(예: "slack") 또는 서버 이름을 키로, 전체 MCP 서버 구성을 값으로 하는 인라인 정의다.
hooks	X	이 서브에이전트 범위의 라이프사이클 훅
memory	X	지속적 메모리 범위: user, project, 또는 local. 세션 간 학습 활성화

모델 선택

model 필드는 서브에이전트가 사용할 AI 모델을 제어한다.

• 모델 별칭: 사용 가능한 별칭 중 하나를 사용하자. sonnet, opus, 또는 haiku
• inherit: 메인 대화와 동일한 모델 사용
• 생략: 지정하지 않으면 inherit가 기본값 (메인 대화와 동일한 모델 사용)

서브에이전트 능력 제어하기

도구 접근, 권한 모드, 조건부 규칙을 통해 서브에이전트가 할 수 있는 일을 제어할 수 있다.

사용 가능한 도구

서브에이전트는 Claude Code의 내부 도구 중 어떤 것이든 사용할 수 있다. 기본적으로 서브에이전트는 MCP 도구를 포함하여 메인 대화의 모든 도구를 상속한다.

도구를 제한하려면 tools 필드(허용 목록) 또는 disallowedTools 필드(거부 목록)를 사용하자.

---
name: safe-researcher
description: 제한된 능력을 가진 연구 에이전트
tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit
---

생성할 수 있는 서브에이전트 제한하기

에이전트가 claude --agent로 메인 스레드로 실행될 때 Task 도구를 사용하여 서브에이전트를 생성할 수 있다. 생성할 수 있는 서브에이전트 유형을 제한하려면 tools 필드에서 Task(agent_type) 구문을 사용하자.

---
name: coordinator
description: 전문화된 에이전트 간 작업 조정
tools: Task(worker, researcher), Read, Bash
---

worker와 researcher 서브에이전트만 생성할 수 있게된다. 에이전트가 다른 유형을 생성하려고 하면 요청이 실패하고 에이전트는 프롬프트에서 허용된 유형만 볼 수 있다. 다른 모든 것을 허용하면서 특정 에이전트를 차단하려면 대신 permissions.deny를 사용하자.

제한 없이 모든 서브에이전트 생성을 허용하려면 괄호 없이 Task를 사용하자.

tools: Task, Read, Bash

Task가 tools 목록에서 완전히 생략되면 에이전트는 어떤 서브에이전트도 생성할 수 없다. 이 제한은 claude --agent로 메인 스레드로 실행되는 에이전트에만 적용된다. 서브에이전트는 다른 서브에이전트를 생성할 수 없으므로 서브에이전트 정의에서 Task(agent_type)는 효과가 없다.

권한 모드

permissionMode 필드는 서브에이전트가 권한 프롬프트를 처리하는 방법을 제어한다. 서브에이전트는 메인 대화에서 권한 컨텍스트를 상속하지만 모드를 재정의할 수 있다.

모드	동작
default	프롬프트와 함께 표준 권한 확인
acceptEdits	파일 편집 자동 승인
dontAsk	권한 프롬프트 자동 거부 (명시적으로 허용된 도구는 여전히 작동)
delegate	에이전트 팀 리드를 위한 조정 전용 모드. 팀 관리 도구로 제한
bypassPermissions	모든 권한 확인 건너뛰기
plan	플랜 모드 (읽기 전용 탐색)

bypassPermissions는 주의해서 사용하자. 모든 권한 확인을 건너뛰어 서브에이전트가 승인 없이 모든 작업을 실행할 수 있다.

부모가 bypassPermissions를 사용하는 경우 이것이 우선하며 재정의할 수 없다.

서브에이전트에 스킬 미리 로드하기

skills 필드를 사용하여 시작 시 서브에이전트의 컨텍스트에 스킬 콘텐츠를 주입할 수 있다. 이렇게 하면 서브에이전트가 실행 중에 스킬을 발견하고 로드할 필요 없이 도메인 지식을 얻을 수 있다.

---
name: api-developer
description: 팀 규칙을 따라 API 엔드포인트 구현
skills:
  - api-conventions
  - error-handling-patterns
---

API 엔드포인트를 구현하세요. 미리 로드된 스킬의 규칙과 패턴을 따르세요.

각 스킬의 전체 콘텐츠가 서브에이전트의 컨텍스트에 주입되며, 호출만 가능한 것이 아니다. 서브에이전트는 부모 대화에서 스킬을 상속하지 않으므로 명시적으로 나열해야 한다.

이것은 서브에이전트에서 스킬 실행의 반대다. 서브에이전트에서 skills를 사용하면 서브에이전트가 시스템 프롬프트를 제어하고 스킬 콘텐츠를 로드한다. 스킬에서 context: fork를 사용하면 스킬 콘텐츠가 지정한 에이전트에 주입된다.

지속적 메모리 활성화하기

memory 필드는 서브에이전트에게 대화 간에 지속되는 영구 디렉토리를 제공한다. 서브에이전트는 이 디렉토리를 사용하여 코드베이스 패턴, 디버깅 인사이트, 아키텍처 결정과 같은 지식을 시간이 지남에 따라 축적한다.

---
name: code-reviewer
description: 품질과 모범 사례를 위한 코드 검토
memory: user
---

당신은 코드 리뷰어입니다. 코드를 검토하면서 발견한 패턴, 규칙, 반복되는 문제를 에이전트 메모리에 업데이트하세요.

메모리가 적용되어야 하는 범위에 따라 범위를 선택하자.

범위	위치	사용 시기
user	~/.claude/agent-memory/<name-of-agent>/	서브에이전트가 모든 프로젝트에서 학습 내용을 기억해야 할 때
project	.claude/agent-memory/<name-of-agent>/	서브에이전트의 지식이 프로젝트별로 특정하고 버전 관리를 통해 공유 가능할 때
local	.claude/agent-memory-local/<name-of-agent>/	서브에이전트의 지식이 프로젝트별로 특정하지만 버전 관리에 체크인되지 않아야 할 때

메모리가 활성화되면:

• 서브에이전트의 시스템 프롬프트에 메모리 디렉토리 읽기 및 쓰기 지침이 포함된다.
• 서브에이전트의 시스템 프롬프트에는 메모리 디렉토리의 MEMORY.md 처음 200줄도 포함되며, 200줄을 초과하는 경우 MEMORY.md를 큐레이션하라는 지침이 포함된다.
• 서브에이전트가 메모리 파일을 관리할 수 있도록 Read, Write, Edit 도구가 자동으로 활성화된다.

지속적 메모리 팁

• user가 권장되는 기본 범위다. 서브에이전트의 지식이 특정 코드베이스에만 관련이 있을 때 project 또는 local을 사용하자.
• 작업을 시작하기 전에 서브에이전트에게 메모리를 참조하도록 요청하자.

  ...
  이 PR을 검토하고, 이전에 본 패턴이 있는지 메모리를 확인하세요.
  ...

• 작업을 완료한 후 서브에이전트에게 메모리를 업데이트하도록 요청하자. 효과적으로 만드는 지식 베이스를 구축하게 될 것이다.

  ...
  이제 완료했으므로 학습한 내용을 메모리에 저장하세요.
  ...

• 서브에이전트의 마크다운 파일에 메모리 지침을 직접 포함하여 자체 지식 베이스를 적극적으로 유지 관리하도록 하자.

  ...
  코드 경로, 패턴, 라이브러리 위치, 주요 아키텍처 결정을 발견하면서 에이전트 메모리를 업데이트하세요. 이것은 대화 간에 제도적 지식을 축적합니다. 발견한 내용과 위치에 대한 간결한 노트를 작성하세요.
  ...

훅을 사용한 조건부 규칙

도구 사용에 대한 더 동적인 제어를 위해 PreToolUse 훅을 사용하여 작업이 실행되기 전에 유효성을 검사할 수 있다. 이것은 도구의 일부 작업은 허용하고 다른 작업은 차단해야 할 때 유용하다.

읽기 전용 데이터베이스 쿼리만 허용하는 서브에이전트를 예를 들어보자. PreToolUse 훅은 각 Bash 명령이 실행되기 전에 command에 지정된 스크립트를 실행한다.

---
name: db-reader
description: 읽기 전용 데이터베이스 쿼리 실행
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

Claude Code는 훅 입력을 JSON으로 전달하여 훅 명령에 stdin을 통해 전달한다. 유효성 검사 스크립트는 이 JSON을 읽고 Bash 명령을 추출하여 쓰기 작업을 차단하기 위해 코드 2로 종료한다.

#!/bin/bash
# ./scripts/validate-readonly-query.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# SQL 쓰기 작업 차단 (대소문자 무시)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "차단됨: SELECT 쿼리만 허용됩니다" >&2
  exit 2
fi

exit 0

특정 서브에이전트 비활성화하기

설정의 deny 배열에 추가하여 Claude가 특정 서브에이전트를 사용하지 못하도록 할 수 있다. Task(subagent-name) 형식을 사용하자.

{
  "permissions": {
    "deny": ["Task(Explore)", "Task(my-custom-agent)"]
  }
}

서브에이전트를 위한 훅 정의하기

서브에이전트는 서브에이전트의 라이프사이클 중에 실행되는 훅을 정의할 수 있다. 훅을 구성하는 두 가지 방법이 있다:

1. 서브에이전트의 frontmatter에서: 해당 서브에이전트가 활성화된 동안에만 실행되는 훅 정의
2. settings.json에서: 서브에이전트가 시작하거나 중지할 때 메인 세션에서 실행되는 훅 정의

서브에이전트 frontmatter의 훅

서브에이전트의 마크다운 파일에서 직접 훅을 정의하자. 이러한 훅은 해당 특정 서브에이전트가 활성화된 동안에만 실행되며 완료되면 정리된다.

모든 훅 이벤트가 지원된다. 서브에이전트에 대한 가장 일반적인 이벤트는 아래과 같다.

이벤트	매처 입력	발생 시점
PreToolUse	도구 이름	서브에이전트가 도구를 사용하기 전
PostToolUse	도구 이름	서브에이전트가 도구를 사용한 후
Stop	(없음)	서브에이전트가 완료될 때 (런타임에 SubagentStop으로 변환됨)

아래 예제는 PreToolUse 훅으로 Bash 명령을 검증하고 파일 편집 후 PostToolUse로 린터를 실행한다:

---
name: code-reviewer
description: 자동 린팅으로 코드 변경 검토
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh $TOOL_INPUT"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

frontmatter의 Stop 훅은 자동으로 SubagentStop 이벤트로 변환된다.

서브에이전트 이벤트를 위한 프로젝트 수준 훅

메인 세션에서 서브에이전트 라이프사이클 이벤트에 응답하는 settings.json에서 훅을 구성하자.

이벤트	매처 입력	발생 시점
SubagentStart	에이전트 타입 이름	서브에이전트가 실행을 시작할 때
SubagentStop	에이전트 타입 이름	서브에이전트가 완료될 때

두 이벤트 모두 이름으로 특정 에이전트 타입을 대상으로 하는 매처를 지원한다. 아래 예제는 db-agent 서브에이전트가 시작될 때만 설정 스크립트를 실행하고, 모든 서브에이전트가 중지될 때 정리 스크립트를 실행한다.

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
        ]
      }
    ]
  }
}

서브에이전트 작업하기

자동 위임 이해하기

Claude는 요청의 작업 설명, 서브에이전트 구성의 description 필드, 현재 컨텍스트를 기반으로 작업을 자동으로 위임한다. 적극적인 위임을 장려하려면 서브에이전트의 설명 필드에 "적극적으로 사용" 같은 문구를 포함하면 된다.

포그라운드 또는 백그라운드에서 서브에이전트 실행하기

서브에이전트는 포그라운드(블로킹) 또는 백그라운드(동시)에서 실행할 수 있다.

• 포그라운드 서브에이전트는 완료될 때까지 메인 대화를 차단한다. 권한 프롬프트와 명확화 질문(AskUserQuestion) 같은)은 사용자에게 전달된다.
• 백그라운드 서브에이전트는 사용자가 계속 작업하는 동안 동시에 실행된다. 실행하기 전에 Claude Code는 서브에이전트가 필요로 하는 모든 도구 권한을 프롬프트하여 필요한 승인을 미리 받는다. 실행되면 서브에이전트는 이러한 권한을 상속하고 미리 승인되지 않은 모든 것을 자동으로 거부한다. 백그라운드 서브에이전트가 명확화 질문을 해야 하는 경우 해당 도구 호출은 실패하지만 서브에이전트는 계속된다. MCP 도구는 백그라운드 서브에이전트에서 사용할 수 없다.

백그라운드 서브에이전트가 권한 부족으로 실패하면 재개하여 포그라운드에서 대화형 프롬프트로 다시 시도할 수도 있다.

Claude는 작업에 따라 서브에이전트를 포그라운드 또는 백그라운드에서 실행할지 결정한다. 다음과 같이 할 수도 있다.

• Claude에게 "백그라운드에서 실행하세요."라고 요청
• Ctrl+B를 눌러 실행 중인 작업을 백그라운드로 전환

모든 백그라운드 작업 기능을 비활성화하려면 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS 환경 변수를 1로 설정하면 된다. 환경 변수를 참조하자.

일반적인 패턴

대량 출력 작업 격리하기

서브에이전트의 가장 효과적인 사용 중 하나는 많은 양의 출력을 생성하는 작업을 격리하는 것이다. 테스트 실행, 문서 가져오기 또는 로그 파일 처리는 상당한 컨텍스트를 소비할 수 있다. 이를 서브에이전트에 위임하면 장황한 출력은 서브에이전트의 컨텍스트에 남고 관련 요약만 메인 대화로 돌아갈 것이다.

...
서브에이전트를 사용하여 테스트 스위트를 실행하고 오류 메시지와 함께 실패한 테스트만 보고하세요.
...

병렬 분석 실행하기

독립적인 분석의 경우 여러 서브에이전트를 동시에 생성하여 작업하는 것을 권장한다.:

...
별도의 서브에이전트를 사용하여 인증, 데이터베이스, API 모듈을 병렬로 분석하세요.
...

각 서브에이전트는 자신의 영역을 독립적으로 탐색한 다음 Claude가 결과를 종합한다. 이것은 분석 경로가 서로 의존하지 않을 때 가장 잘 작동한다.

서브에이전트가 완료되면 결과가 메인 대화로 돌아간다. 각각 상세한 결과를 반환하는 많은 서브에이전트를 실행하면 상당한 컨텍스트를 소비할 수 있다.

지속적인 병렬성이 필요하거나 컨텍스트 윈도우를 초과하는 작업의 경우 에이전트 팀은 각 작업자에게 자체 독립적인 컨텍스트를 제공한다.

서브에이전트 체인닝

다단계 워크플로우의 경우 Claude에게 서브에이전트를 순차적으로 사용하도록 요청하자. 각 서브에이전트는 작업을 완료하고 결과를 Claude에 반환하면 Claude는 관련 컨텍스트를 다음 서브에이전트에 전달한다.

...
code-reviewer 서브에이전트를 사용하여 성능 문제를 찾은 다음 optimizer 서브에이전트를 사용하여 수정하세요.
...

서브에이전트와 메인 대화 선택하기

다음과 같은 경우 메인 대화를 사용하자.

• 작업에 빈번한 왕복 또는 반복적 개선이 필요한 경우
• 여러 단계가 상당한 컨텍스트를 공유하는 경우 (계획 → 구현 → 테스트)
• 빠르고 대상이 명확한 변경을 하는 경우
• 지연 시간이 중요한 경우, 서브에이전트는 새로 시작하며 컨텍스트를 수집하는 데 시간이 걸릴 수 있다.

다음과 같은 경우 서브에이전트를 사용하자.

• 작업이 메인 컨텍스트에 필요하지 않은 장황한 출력을 생성하는 경우
• 특정 도구 제한 또는 권한을 강제하고 싶은 경우
• 작업이 자체 완결적이고 요약을 반환할 수 있는 경우

격리된 서브에이전트 컨텍스트가 아닌 메인 대화 컨텍스트에서 실행되는 재사용 가능한 프롬프트 또는 워크플로우를 원하는 경우 대신 스킬을 고려해야한다.

워크플로우에 중첩된 위임이 필요한 경우 스킬을 사용하거나 메인 대화에서 서브에이전트를 체인하는 것을 권장한다.

서브에이전트 컨텍스트 관리하기

서브에이전트 재개하기

각 서브에이전트 호출은 새 컨텍스트로 새 인스턴스를 만든다. 처음부터 다시 시작하는 대신 기존 서브에이전트의 작업을 계속하려면 Claude에게 재개하도록 요청해보자.

재개된 서브에이전트는 이전의 모든 도구 호출, 결과, 추론을 포함한 전체 대화 기록을 유지한다. 서브에이전트는 처음부터 다시 시작하는 대신 중단된 지점에서 정확히 이어서 진행한다.

서브에이전트가 완료되면 Claude는 에이전트 ID를 받는다. 서브에이전트를 재개하려면 Claude에게 이전 작업을 계속하도록 요청해보자.

code-reviewer 서브에이전트를 사용하여 인증 모듈을 검토하세요.
[에이전트 완료]

해당 코드 검토를 계속하고 이제 권한 부여 로직을 분석하세요.
[Claude가 이전 대화의 전체 컨텍스트로 서브에이전트를 재개]

명시적으로 참조하려면 Claude에게 에이전트 ID를 요청하거나 ~/.claude/projects/{project}/{sessionId}/subagents/의 트랜스크립트 파일에서 ID를 찾을 수 있다. 각 트랜스크립트는 agent-{agentId}.jsonl로 저장된다.

서브에이전트 트랜스크립트는 메인 대화와 독립적으로 지속된다.

• 메인 대화 압축: 메인 대화가 압축될 때 서브에이전트 트랜스크립트는 영향을 받지 않는다. 별도의 파일에 저장된다.
• 세션 지속성: 서브에이전트 트랜스크립트는 세션 내에서 지속된다. 동일한 세션을 재개하여 Claude Code를 재시작한 후 서브에이전트를 재개할 수 있다.
• 자동 정리: 트랜스크립트는 cleanupPeriodDays 설정(기본값: 30일)에 따라 정리된다.

자동 압축

서브에이전트는 메인 대화와 동일한 로직을 사용하는 자동 압축을 지원한다. 기본적으로 자동 압축은 약 95% 용량에서 트리거된다. 압축을 더 일찍 트리거하려면 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE를 더 낮은 백분율(예: 50)로 설정하면 된다.

참고

서브에이전트