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가 어떤 하위 작업을 만들었는지 이 정보로 추적합니다.
background subagent는 5단계까지만 내려갑니다
공식 문서에 따르면 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가 하위 작업을 직접 분해합니다.
마무리
nested subagents로 Claude Code는 더 복잡한 작업 구조를 다룹니다. 이 기능을 쓸 때는 agent를 많이 띄우기보다, 하위 작업을 어디까지 위임할지 먼저 설계합니다.
큰 작업을 맡길수록 agent tree를 관찰하고, 범위를 제한하고, 검증 지점을 정합니다.