Claude Code subagent depth: 백그라운드 에이전트 폭주를 막는 운영법 | DAKER 커뮤니티
Claude Code subagent depth: 백그라운드 에이전트 폭주를 막는 운영법
Claude Code subagent를 여러 단계로 나누면 큰 작업이 빨라지지만, 깊이와 배경 실행 규칙을 모르면 작업이 어디서 멈췄는지 놓치기 쉽습니다. Subagent depth란 메인 대화 아래에 중첩된 subagent 단계 수를 의미합니다. 2026년 6월 30일 기준 공식 문서와 v2.1.187 릴리스 확인 후, 팀이 바로 적용할 깊이 제한과 background 실행 기준을 정리했습니다.
한 줄 요약: subagent는 많이 띄우는 기능이 아니라, 깊이 5단계 안에서 맥락과 권한을 분리하는 운영 도구입니다.
먼저 읽어볼 내부 글은 nested subagents와 subagent hooks입니다.
_이미지: 클로드 코드 subagent depth와 background 실행 기준을 설명하는 대표 카드._
문제 상황: 왜 subagent가 많을수록 오히려 느려질까?
테스트, 로그, 코드 검색, 리뷰를 모두 메인 대화에 쌓으면 컨텍스트가 빨리 지저분해집니다. 그래서 Claude Code는 subagent를 별도 context window에서 실행하고 요약만 돌려받게 합니다.
문제는 subagent가 다시 subagent를 부르는 순간입니다. 중첩 작업은 강력하지만, 누가 어떤 깊이에서 실행 중인지 모르면 결과 요약이 늦고 권한 프롬프트도 놓치기 쉽습니다.
핵심 개념: foreground와 background subagent는 무엇이 다른가?
공식 문서 기준 foreground subagent는 끝날 때까지 메인 대화를 막습니다. background subagent는 동시에 실행되며 사용자는 계속 작업할 수 있습니다. v2.1.186 이후에는 background subagent가 권한이 필요한 tool call에 도달하면 메인 세션에 어느 subagent가 묻는지 표시됩니다.
중첩 깊이는 foreground인지 background인지와 무관하게 계산됩니다. 공식 문서 기준 깊이 5의 subagent는 더 이상 Agent tool을 받지 못하며, 이 제한은 고정이고 설정으로 바꿀 수 없습니다.
선택지 | 좋은 상황 | 주의할 점 |
|---|---|---|
foreground subagent | 결과가 다음 단계 입력일 때 | 메인 대화가 기다립니다 |
background subagent | 독립 조사나 긴 테스트일 때 | 권한 프롬프트 위치를 확인합니다 |
nested subagent | 리뷰가 검증자를 다시 나눌 때 | 깊이 5단계 안에서 멈춥니다 |
_이미지: foreground, background, nested subagent를 팀 작업에 배치하는 워크플로._
단계별 사용법: 팀 작업을 어떻게 나눌까?
메인 대화에는 목표, 파일 소유권, 완료 조건만 둡니다.
검색·로그·문서 확인처럼 출력이 큰 일은 read-only subagent로 보냅니다.
구현과 검증이 서로 독립이면 background로 실행합니다.
subagent가 다시 작업을 나눌 수 있다면 최대 깊이를 3단계 정도로 설계해 여유를 둡니다.
중단 후 재개가 필요하면 새 subagent를 만들지 말고 기존 subagent resume을 요청합니다.
짧은 예시: background subagent를 안전하게 쓰는 요청
다음처럼 깊이와 반환 형식을 같이 제한하세요.
인증 모듈 로그 조사는 background subagent로 실행해줘. 하위 subagent는 최대 1단계만 쓰고, 최종 답변에는 실패 원인 후보 3개와 확인 명령만 남겨줘.
이 방식은 병렬 실행을 허용하지만, 하위 작업이 무한히 늘어나지 않게 합니다.
팀 적용 체크리스트: subagent 폭주를 어떻게 막을까?
작업을 나누기 전에 메인 대화의 완료 조건을 한 문장으로 썼습니다.
subagent별 도구 권한을 read-only, edit, test 실행으로 나눴습니다.
background 실행이 필요한 이유가 "기다림 단축"인지 "맥락 분리"인지 구분했습니다.
깊이 5 제한을 넘기지 않도록 중첩은 최대 3단계로 설계했습니다.
결과 요약이 길어질 작업은 Dynamic Workflows나 agent teams와 비교했습니다.
공식 출처: 어떤 기준으로 확인했나?
이 글은 2026년 6월 30일 기준 Claude Code Create custom subagents, Agent view, Environment variables 문서와 Anthropic Claude Code GitHub Releases v2.1.187·v2.1.193·v2.1.195를 확인해 작성했습니다. 공개 본문에는 DAKER/DACON 정책에 따라 외부 URL을 노출하지 않았습니다.
자주 묻는 질문
subagent depth 제한은 설정으로 늘릴 수 있나요?
공식 문서 기준 늘릴 수 없습니다. 깊이 5의 subagent는 Agent tool을 받지 못하므로 더 깊게 나누는 대신 작업 단위를 다시 쪼개야 합니다.
background subagent가 권한을 물으면 어디에 표시되나요?
v2.1.186 이후에는 메인 세션에 어떤 background subagent가 권한을 요청하는지 표시됩니다. 승인하면 계속 진행하고, Esc로 해당 tool call만 거부할 수 있습니다.
subagent와 background agent는 같은가요?
같지 않습니다. subagent는 단일 세션 안의 별도 context window이고, agent view의 background session은 독립 Claude Code 대화입니다.
작업이 많으면 무조건 subagent를 쓰면 되나요?
아닙니다. 잦은 왕복, 공유 맥락이 많은 구현, 빠른 단일 수정은 메인 대화가 낫습니다. 출력이 큰 조사나 독립 검증일 때 subagent가 유리합니다.
다음 큰 리팩터링을 시작하기 전, 먼저 "메인 대화에 남길 것"과 "subagent로 격리할 것"을 두 줄로 나눠 보세요.