Claude Code의 중첩형 서브 에이전트 입문 — 최대 5계층 설계와 토큰 설계의 핵심

Claude Code의 v2.1.172(2026년 6월 10일 출시)에서, **서브 에이전트(sub-agent)가 자신의 서브 에이전트를 기동할 수 있는 「중첩형 서브 에이전트(nested sub-agents)」**가 추가되었습니다. 공식 릴리스 노트에서는 「서브 에이전트는 최대 5계층까지 중첩할 수 있다」고 설명되어 있습니다.

지금까지의 서브 에이전트는 「부모 에이전트가 자식 에이전트를 1단계만 호출하는」 구조였으나, 중첩(nesting) 대응을 통해 「자식이 손자를, 손자가 증손자를」 호출하며 재귀적으로 처리를 위임할 수 있게 되었습니다. 반면, 계층이 깊어질수록 토큰(token) 소비와 비용이 증가하기 때문에, 설계의 핵심을 파악해 두지 않으면 「작동은 하지만 비용이 비싼」 에이전트가 되기 쉽습니다.

이 기사에서는 중첩형 서브 에이전트의 메커니즘, 정의 방법, 토큰 설계의 사고방식을 공식 문서와 공개된 정보를 바탕으로 정리합니다.

• 중첩형 서브 에이전트란 무엇인가, 어떤 버전에서 무엇이 바뀌었는가

• .claude/agents/에서 서브 에이전트를 정의하는 방법 (name / description / tools / model)

• 5계층의 상한과 토큰 소비의 관계, 비용을 억제하는 설계 패턴

• 중첩해야 하는 케이스와 피해야 하는 케이스의 판단 기준

• Claude Code에서 서브 에이전트를 사용한 자동화를 구축하고 싶은 엔지니어

• 여러 서브 에이전트를 조합했을 때의 비용이 걱정되는 분

• 에이전트 설계의 베스트 프랙티스(best practice)를 알고 싶은 분

• Claude Code (CLI)의 기본 조작

• 서브 에이전트(subagent)의 기본 개념 (부모 에이전트가 특정 태스크를 별도의 컨텍스트(context)로 위임하는 메커니즘)

• Claude Code v2.1.172 (2026-06-10)에서, 서브 에이전트가 최대 5계층까지 중첩 가능해짐. - 각 계층은 독립된 컨텍스트와 model을 가지므로, 깊은 계층일수록 모델을 가볍게 만드는 것이 비용 설계의 기본. - 중첩이 빛을 발하는 것은 「트리 구조(tree structure)」「재귀적 탐색」 태스크. 순차 처리나 가로 방향의 연계가 필요한 태스크에는 부적합.

Claude Code의 서브 에이전트는 특정 역할에 특화된 별도의 컨텍스트 작업자입니다. 공식 문서 「Create custom subagents」에 따르면, 서브 에이전트는 Markdown 파일에 YAML 프론트매터(front matter)를 작성하여 정의하며, 프론트매터에서 에이전트의 이름, 용도, 사용할 수 있는 도구, 실행 모델을 선언합니다.

메인 에이전트가 「이 태스크는 리뷰 담당자에게 맡기자」라고 판단하면, 서브 에이전트가 기동되어 **독립된 컨텍스트 윈도우(context window)**에서 작업하고, 결과의 요약만을 부모에게 반환합니다. 이를 통해 메인 대화 컨텍스트를 더럽히지 않고 무거운 조사나 리뷰를 병행할 수 있습니다.

중첩 대응 전에는 서브 에이전트는 「잎(leaf)」이었습니다. 즉, 메인 에이전트가 자식 서브 에이전트를 호출할 수는 있어도, 그 자식이 다시 손자를 호출할 수는 없었습니다.

v2.1.172에서는 이 제한이 완화되어, 서브 에이전트가 자신의 서브 에이전트를 기동할 수 있게 되었습니다. 릴리스 노트에는 다음과 같이 기재되어 있습니다.

Sub-agents can now spawn their own sub-agents (up to 5 levels deep)

— Claude Code release notes (v2.1.172, Jun 10, 2026)

이 「최대 5계층」이라는 상한은 무한 재귀로 인한 폭주와 비용 폭발을 방지하기 위한 안전장치로서 기능합니다.

공식 문서 「Create custom subagents」에 따르면, 이 깊이 5의 상한이 고정된 천장(hard ceiling)으로 작용하는 것은 백그라운드에서 동작하는 서브 에이전트입니다. 깊이 5의 백그라운드 서브 에이전트는 서브 에이전트 기동용 도구를 받지 않으므로 그 이상 중첩할 수 없습니다. 반면, 포그라운드(foreground)의 서브 에이전트는 원리적으로 깊이 제한이 없으며, 부모가 자식의 완료를 기다리는 자기 제한형(self-limiting) 방식으로 동작합니다. 정확한 조건은 공식 문서를 확인해 주세요.

중첩형 서브 에이전트는 2026년 6월 Claude Code 강화의 일부입니다. 같은 시기에 다음 사항도 추가되었습니다.

버전	날짜	주요 추가 사항
v2.1.169	2026-06-08	Safe Mode (--safe-mode), /cd 명령
...

특히, 뒤에서 설명할 토큰 설계와 궁합이 좋은 것이 /usage 명령입니다. /usage는 플러그인이나 MCP 서버 단위로 토큰 소비 내역을 표시하므로, 중첩된 에이전트 중 어디에서 비용이 발생하는지 파악하는 데 도움이 됩니다.

서브 에이전트는 프로젝트의 .claude/agents/ 하위(또는 사용자 레벨의 ~/.claude/agents/)에 Markdown 파일로 배치합니다. 공식 문서에 따르면, 주요 프론트매터 (Frontmatter) 필드는 다음 4가지입니다.

---
name: log-summariser
description: 컨테이너의 원시 로그를 읽고 구조화된 요약을 반환한다. 로그 조사가 필요할 때 사용한다.
...

각 필드의 역할은 다음과 같습니다.

필드	역할
name	서브 에이전트의 고유한 이름
description	위임 (Delegation)의 트리거. Claude는 사용자의 요청과 이 설명을 대조하여 자동으로 서브 에이전트에게 위임할지 판단한다
tools	서브 에이전트가 사용할 수 있는 도구를 물리적으로 제한한다. Read, Grep, Glob만 있다면 쓰기 작업은 일절 할 수 없다
model	실행 모델 (haiku / sonnet / opus). 태스크의 무게에 따라 구분하여 사용한다

프론트매터 직후의 본문이 시스템 프롬프트 (에이전트의 행동을 정의하는 지시 사항)가 됩니다.

description은 '라벨'이 아니라 '라우팅 규칙 (Routing Rule)'으로서 작성하는 것이 중요합니다. '어떤 상황·어떤 문구일 때 이 에이전트를 호출해야 하는가'를 구체적으로 적을수록 자동 위임의 정밀도가 높아집니다.

중첩 (Nest)은 특정 서브 에이전트가 다른 서브 에이전트를 호출할 수 있는 도구 권한을 가짐으로써 성립됩니다. 즉, 자식 에이전트의 tools에 서브 에이전트 실행 권한을 포함하면, 그 자식은 손자를 호출할 수 있게 됩니다.

예를 들어, 로그 조사를 3계층으로 나눈 버그 트리아지 (Bug Triage) 워크플로우는 다음과 같이 구성할 수 있습니다.

계층	에이전트	역할	권장 모델
루트 (깊이 0)	triage-lead	전체 총괄 및 최종 판단	opus
중간 (깊이 1)	repro-runner	재현 절차 실행	sonnet
잎 (깊이 2)	log-summariser	원시 로그 요약	haiku

루트인 triage-lead가 repro-runner를 호출하고, repro-runner가 log-summariser를 호출하는—위임 체인 (Delegation Chain)입니다. 각 계층은 독립된 컨텍스트 (Context)에서 동작하며, 결과의 요약본만이 상위 계층으로 반환됩니다.

서브 에이전트 실행을 허용하는 도구 권한을 무제한으로 부여하면, 모델이 의도하지 않은 체인을 끊임없이 만들어 비용이 팽창할 우려가 있습니다. '어떤 자식을 호출할 수 있는지'를 명시적으로 열거하는 설계(후술)가 안전합니다. 또한, 중첩용 정확한 도구 지정 형식은 업데이트가 빠르므로, 반드시 공식 문서에서 최신 표기법을 확인하시기 바랍니다.

중첩형 서브 에이전트에서 가장 주의해야 할 점은 토큰 소비입니다. 각 계층은 독립된 컨텍스트 윈도우 (Context Window)와 시스템 프롬프트를 가지기 때문에, 계층이 늘어날수록 '시스템 프롬프트 작성'이 누적됩니다.

1단계뿐인 서브 에이전트라면 추가 비용은 '자식의 시스템 프롬프트 + 자식의 작업 토큰'뿐입니다. 하지만 중첩될 경우, 중간 계층의 컨텍스트는 최종적으로 부모에게는 요약본만 반환됨에도 불구하고, 그 중간 과정의 토큰은 소비됩니다. 다분기(하나의 부모가 여러 자식을, 그 자식이 다시 여러 손자를 호출하는 구조)가 되면 소비량은 계층적으로 불어납니다.

비용을 억제하는 기본 원칙은 역할과 계층에 따라 모델을 구분하여 사용하는 것입니다.

깊이	전형적인 역할	모델 전략
0 (메인)	총괄·최종 합성	Opus (고급 추론)
...

잎(Leaf)에 가까운 단순 작업(로그 읽기·grep·요약)에 Opus를 사용하는 것은 전형적인 낭비입니다. 잎은 Haiku, 추론이 필요한 중간 단계는 Sonnet, 최종 합성만 Opus를 사용하는 것처럼, 아래로 내려갈수록 가벼운 모델을 사용하는 것이 정석입니다.

환경 변수 CLAUDE_CODE_SUBAGENT_MODEL을 통해 서브 에이전트의 기본 모델을 일괄 지정할 수 있습니다. 예를 들어, 전체 기본값을 Haiku로 설정해 두고 능력이 필요한 계층만 각 에이전트의 model 필드에서 개별적으로 업그레이드하는 방식이 비용 관리에 용이합니다.

# 서브 에이전트의 기본 모델을 경량 모델로 고정
export CLAUDE_CODE_SUBAGENT_MODEL=haiku
claude

어느 계층과 어느 컴포넌트가 토큰을 소비하고 있는지는 /usage 명령어로 확인할 수 있습니다. 여러 플러그인이나 MCP 서버, 중첩된 에이전트를 병용할수록 내역 시각화의 효과가 나타납니다. 비용이 예상보다 높을 때는 먼저 /usage로 "어디서 소비되고 있는지"를 특정한 후 모델 전략을 재검토하는 것이 효율적입니다.

중첩(Nesting)이 만능은 아닙니다. 태스크의 형태에 따라 구분하여 사용해야 합니다.

• 트리 구조 태스크: 하나의 부모가 역할이 다른 여러 전문 리뷰어(보안·성능·스타일)로 분기시키는 경우

• 재귀적 탐색: 모노레포(Monorepo)를 디렉터리 단위로 스코프를 전환하며 깊이 파고드는 경우

• 순차 처리: "A 다음에 B, 그 다음에 C"와 같이 일직선으로 진행되는 태스크는 중첩하지 않고 하나의 에이전트에서 maxTurns를 넉넉하게 설정하는 것이 더 단순하고 저렴합니다.

• 가로 협력이 필요한 병렬 작업: 병렬 워커(Worker)들끼리 정보를 공유하며 진행해야 한다면, 중첩(세로 방향 위임)이 아니라 병렬 실행에 적합한 메커니즘(agent teams 등)이 적합합니다.

중첩은 "세로 방향의 위임"이고, agent teams와 같은 병렬 실행은 "가로 방향의 협업"이라고 정리하면 판단하기 쉽습니다. 태스크가 분기·재귀적이라면 세로, 협업·공유가 필요하다면 가로입니다.

• Claude Code v2.1.172 (2026-06-10)에서 서브 에이전트가 최대 5계층까지 중첩될 수 있게 되었습니다.
• 서브 에이전트는 .claude/agents/에 name / description / tools / model을 프론트매터(Frontmatter)로 정의합니다. description은 라우팅 규칙으로서, tools는 권한의 물리적 제한으로서 작성하는 것이 핵심입니다.
• 각 계층은 독립적인 컨텍스트를 가지므로, 깊은 계층일수록 가벼운 모델을 사용하는 것이 토큰 설계의 기본입니다. CLAUDE_CODE_SUBAGENT_MODEL로 기본값을 가볍게 설정하고, 필요한 계층만 업그레이드합니다.
• 중첩은 트리 구조 및 재귀 탐색 태스크에서 빛을 발합니다. 순차 처리나 가로 협업에는 부적합하며, 각각 단일 에이전트나 Agent Teams가 적합합니다.

중첩형 서브 에이전트는 강력하지만, 설계를 잘못하면 "작동은 하지만 비용이 비싼" 에이전트가 됩니다. 우선 작은 2~3계층부터 시작하여, /usage로 비용을 관찰하며 계층과 모델을 조정해 나가는 것을 권장합니다.

• Create custom subagents — Claude Code Docs — 서브 에이전트 정의 방법 및 프론트매터 사양
• Claude Code release notes — Releasebot — v2.1.172의 중첩형 서브 에이전트 추가
• Claude Code Subagents: A 2026 Practical Guide — Tembo.io — 서브 에이전트 설계 실전 가이드