Claude Code nested subagents: 큰 작업을 5단계 안에서 안전하게 나누는 법 | DAKER 커뮤니티

Claude Code nested subagents란 subagent가 다시 하위 subagent를 만들어 작업을 나누는 기능입니다. 공식 Week 24 문서와 changelog는 subagent 체인이 최대 5단계로 제한된다고 설명합니다. 큰 리팩터링이나 조사 작업을 맡길 때 /agents로 트리와 상태를 보며 파일 소유권을 정하는 것이 핵심입니다.


클로드 코드 nested subagents 팀 운영 흐름

클로드 코드 nested subagents 팀 운영 흐름


문제 상황: subagent를 많이 쓰면 왜 오히려 느려질까?


병렬 작업은 빠르지만, 기준 없이 늘리면 같은 파일을 동시에 고치거나 검증 없이 결과만 쌓입니다. Claude Code Week 24의 변화는 subagent가 하위 subagent를 만들 수 있게 된 점입니다. 그래서 이제 중요한 질문은 "몇 명을 띄울까?"가 아니라 "어떤 트리 구조와 종료 기준을 둘까?"입니다.


한 줄 요약: nested subagents는 큰 작업을 분해할 때 쓰고, 단순 작업에는 쓰지 않는 편이 낫습니다.


핵심 개념: nested subagents는 어떤 구조로 동작하나?


공식 Week 24 문서는 subagent가 자기 하위 subagent를 만들 수 있고, prompt 아래 subagent 패널에서 전체 트리를 볼 수 있다고 설명합니다. 각 row는 descendant count와 main으로 돌아가는 path를 보여주며, runaway concurrent tree를 막기 위해 체인은 5단계로 제한됩니다.


DAKER의 기존 에이전트 팀 병렬 작업 글은 병렬화 선택 기준을 다뤘습니다. 오늘 글은 그다음 단계인 "하위 subagent가 생기는 상황에서 어떻게 운영 기준을 둘 것인가"에 초점을 둡니다. 사용량이 걱정된다면 Keybindings 글보다 먼저 Statusline 글처럼 모델, 컨텍스트, 비용 표시를 켜 두는 것도 좋습니다.


클로드 코드 nested subagents 실무 판단표

클로드 코드 nested subagents 실무 판단표


단계별 사용법: 큰 작업을 어떻게 맡기면 좋을까?


  1. main에게 전체 목표, 금지 영역, 완료 기준을 먼저 줍니다.


  1. 조사, 구현, 테스트처럼 서로 다른 책임을 나눕니다.


  1. 각 subagent에게 파일 소유권과 읽기/쓰기 범위를 명시합니다.


  1. /agents로 트리, 상태, depth를 확인합니다.


  1. 결과 통합은 main이 맡고, 최종 테스트는 한 번 더 실행합니다.


짧은 예시는 다음과 같습니다.


큰 결제 리팩터링을 세 부분으로 나눠줘.
subagent A는 read-only로 영향 범위를 찾고,
subagent B는 tests/payment만 보강하고,
subagent C는 docs/runbook만 업데이트해.
같은 소스 파일을 동시에 수정하지 말고, main이 통합 판단을 해줘.


팀 적용 체크리스트: 언제 nested subagents를 피해야 할까?


상황

권장 판단

영향 범위가 넓고 조사/테스트/문서가 분리된다

사용해도 좋습니다.

한 파일의 작은 버그 수정이다

main 단독이 더 낫습니다.

토큰 예산이 빡빡하다

subagent 수와 depth를 제한합니다.

파일 소유권을 나눌 수 없다

먼저 계획을 쪼갠 뒤 실행합니다.

결과 검증 명령이 없다

subagent 실행 전에 테스트 기준부터 만듭니다.


실수 방지 포인트는 다음과 같습니다.



FAQ: nested subagents를 팀에서 쓸 때 자주 묻는 질문


nested subagents는 agent teams와 같은 기능인가요?


같지 않습니다. agent teams는 팀 단위 실행/조율 표면이고, nested subagents는 subagent가 다시 하위 subagent를 만들 수 있는 실행 구조입니다. 실제 작업에서는 둘이 함께 보일 수 있지만 운영 기준은 파일 소유권과 검증 명령입니다.


5단계 제한이면 안전하다고 봐도 되나요?


5단계 제한은 무한 확산을 막는 장치입니다. 하지만 비용, 중복 수정, 검증 누락까지 자동으로 해결하지는 않습니다. 팀 규칙이 별도로 필요합니다.


어떤 작업에 가장 잘 맞나요?


대형 코드 조사, 테스트 보강, 문서 업데이트, 다중 모듈 리팩터링처럼 역할이 분리되는 작업에 맞습니다. 단순한 한 줄 수정에는 과합니다.


/agents는 언제 봐야 하나요?


subagent가 여러 개 떠 있거나 중첩 생성이 의심될 때 바로 봅니다. 트리 구조, 완료/대기 상태, 막힌 작업을 확인하는 운영 대시보드로 쓰면 됩니다.


공식 출처



다음 큰 작업을 맡기기 전, 먼저 "subagent가 몇 명인가"보다 "누가 어떤 파일을 책임지고 무엇으로 검증할 것인가"를 한 문장으로 써 보세요.

Redirecting to Claude Code nested subagents: 큰 작업을 5단계 안에서 안전하게 나누는 법 | DAKER 커뮤니티...