Claude Code의 subagent는 큰 작업을 나눠 처리할 때 유용합니다. 그런데 실제 작업은 한 단계로만 나뉘지 않습니다. 조사 agent가 다시 세부 파일 조사를 맡기거나, reviewer agent가 특정 모듈 검증을 별도 agent에게 넘기고 싶을 수 있습니다.
Claude Code v2.1.172부터는 이런 구조가 가능합니다. Week 24 문서 ↗에 따르면 subagent가 다시 자신의 subagent를 spawn할 수 있고, subagent panel은 전체 tree를 보여줍니다.
이 글은 작성 시점 2026-06-17 · Claude Code Week 24 문서 ↗, subagents 문서 ↗ 스냅숏 기준으로 정리했습니다.
어떤 구조인가
기존에는 main 세션이 여러 subagent를 띄우는 구조로 이해하면 충분했습니다. nested subagents에서는 subagent도 다시 하위 subagent를 만들 수 있습니다.
flowchart TD
A[main] --> B[researcher]
A --> C[reviewer]
B --> D[file scanner]
B --> E[dependency mapper]
C --> F[test reviewer]
C --> G[security reviewer]subagent panel은 각 row에 descendant 수와 main까지의 경로를 보여줍니다. 작업이 fan-out될 때 어떤 agent가 어떤 하위 작업을 만들었는지 추적하기 위한 장치입니다.
depth cap이 중요한 이유
공식 문서는 background subagents가 5단계 깊이까지만 허용된다고 설명합니다. runaway concurrent tree를 막기 위한 제한입니다. 반면 foreground chain은 임의 깊이로 spawn할 수 있지만, 실행 방식상 self-limiting에 가깝습니다.
이 제한은 중요합니다. agent tree는 강력하지만, 잘못 설계하면 작업이 필요 이상으로 퍼지고 사용량이 커질 수 있습니다.
Dynamic Workflows와의 관계
nested subagents는 Dynamic Workflows와도 이어집니다. Dynamic Workflows가 큰 작업을 동적으로 plan하고 병렬 subagent로 실행하는 상위 기능이라면, nested subagents는 그 내부 실행 구조를 더 유연하게 만드는 기반에 가깝습니다.
Agent Teams는 사람이 역할을 설계하는 방식이고, nested subagents는 실행 중 agent가 하위 작업을 더 잘 분해하게 해주는 방식입니다.
블로그 대표 이미지 콘셉트
Claude Code Agent View 화면을 닮은 tree 다이어그램이 잘 맞습니다. main에서 researcher와 reviewer가 갈라지고, 각 agent 아래로 더 작은 subagent들이 펼쳐지는 구조입니다.
5단계 깊이 제한은 오른쪽에 안전 가드레일처럼 표시하면 좋습니다.
마무리
nested subagents는 Claude Code가 더 복잡한 작업 구조를 다룰 수 있게 해줍니다. 하지만 이 기능의 핵심은 “많이 띄우기”가 아니라 “하위 작업을 어디까지 위임할지 설계하기”입니다.
큰 작업을 맡길수록 agent tree를 관찰하고, 범위를 제한하고, 검증 지점을 분명히 두는 습관이 필요합니다.