Claude Code subagent cap: 병렬 에이전트 폭주를 예산 안에서 멈추는 법 | DAKER 커뮤니티
Claude Code subagent cap은 병렬 작업의 속도를 유지하되 한 메시지가 예산과 세션을 모두 소모하는 일을 막기 위한 팀 안전장치입니다. 2026년 7월 21일 공식 changelog에는 동시 실행 subagent 기본 cap, nested subagent 기본 차단, background subagent 예산 cap 적용 개선이 함께 포함됐습니다. 당신이 오늘 확인할 곳은 DAKER 클로드 코드 디렉터리와 관련 실무 글입니다.
Claude Code subagent cap이란, 한 메시지가 너무 많은 하위 에이전트를 만들지 않도록 동시 실행과 spawn depth를 제한하는 운영 기준입니다.
Claude Code subagent cap는 무엇이 달라졌나요?
Claude Code subagent cap은 병렬 작업의 속도를 유지하되 한 메시지가 예산과 세션을 모두 소모하는 일을 막기 위한 팀 안전장치입니다. 작성 기준일 현재 공식 문서와 changelog로 확인했지만, 공개 본문에는 DAKER 정책에 맞춰 DAKER 내부 링크만 남깁니다. 그래서 이 글은 기능 자체보다 팀이 바로 실행할 검증 루틴에 초점을 둡니다.
왜 지금 팀 루틴으로 정리해야 하나요?
2026년 7월 21일 공식 changelog에는 동시 실행 subagent 기본 cap, nested subagent 기본 차단, background subagent 예산 cap 적용 개선이 함께 포함됐습니다. 새 기능을 도입할 때 가장 흔한 실수는 도구 이름만 공유하고 완료 기준을 공유하지 않는 것입니다. 오늘은 확인할 화면, 산출물, 로그, 한계를 같은 문장으로 묶어야 합니다.
단계별 사용법은 어떻게 잡으면 좋을까요?
아래 순서는 처음 도입하는 팀이 바로 실행할 수 있는 최소 루틴입니다. 각 단계는 도구 설명이 아니라 팀 작업의 확인 기준으로 쓰는 편이 좋습니다.
- 작업을 쪼개기 전에 동시에 돌릴 이유가 있는 하위 작업만 골라냅니다.
- 한 메시지에서 만들 수 있는 subagent 수와 nested spawn 허용 여부를 팀 기본값으로 정합니다.
- 예산 cap에 도달했을 때 새 spawn이 거절되고 실행 중 작업이 멈추는지 작은 작업으로 시험합니다.
- background agent를 시작할 때 owner, 목표, 중단 조건을 같은 줄에 남깁니다.
- 완료 보고에는 실행한 subagent 수, 멈춘 이유, 남은 수동 확인 항목을 적습니다.
짧은 예시는 어떻게 쓰면 되나요?
작업 요청에는 먼저 목표 화면이나 산출물을 쓰고, 다음 줄에 확인 기준을 적습니다. 마지막 줄에는 확인하지 못한 범위를 남깁니다. 이 세 줄만 있어도 Claude Code 세션의 결과 보고가 훨씬 덜 흐려집니다.
| 구분 | 무제한 병렬 실행 | cap이 있는 병렬 실행 |
|---|---|---|
| 작업 속도 | 초반에는 빨라 보입니다 | 필요한 작업만 안정적으로 병렬화합니다 |
| 예산 관리 | 한 메시지가 비용을 크게 키울 수 있습니다 | cap 도달 시 새 spawn과 실행 작업을 제어합니다 |
| 팀 검증 | 어떤 하위 작업이 결론을 만들었는지 흐려집니다 | owner와 중단 조건을 남겨 재검토가 쉽습니다 |
이미지 워크플로는 무엇을 보여주나요?
팀장이 큰 작업을 무작정 나누기 전에 병렬화할 항목만 고릅니다. subagent 수 제한 카드와 nested spawn 금지 카드가 작업 보드 옆에 붙습니다. 예산 cap에 닿자 새 background agent 생성이 멈추고 진행 중 작업도 정리됩니다.
- 팀장이 큰 작업을 무작정 나누기 전에 병렬화할 항목만 고릅니다.
- subagent 수 제한 카드와 nested spawn 금지 카드가 작업 보드 옆에 붙습니다.
- 예산 cap에 닿자 새 background agent 생성이 멈추고 진행 중 작업도 정리됩니다.
- 각 agent row에는 owner, 목표, 중단 조건이 짧게 표시됩니다.
- 마지막 컷에서 팀은 빠른 실행보다 검증 증거를 먼저 확인합니다.
팀 적용 체크리스트는 무엇인가요?
체크리스트의 목적은 더 많은 자동화를 켜는 것이 아니라, 작업이 끝났다고 말할 수 있는 증거를 남기는 것입니다.
- 병렬화할 작업과 순차로 해야 할 작업을 구분했나요?
- nested subagent가 필요한 예외 상황을 팀 문서에만 좁게 남겼나요?
- 예산 cap 도달 시 새 작업 생성과 실행 중 작업 중단을 따로 확인했나요?
- background agent가 끝난 뒤 같은 결과를 중복 게시하지 않게 했나요?
- 성공 속도보다 검증 증거를 먼저 보고했나요?
공식 출처와 내부 링크는 어디에서 확인하나요?
작성 기준일 현재 기능 사실은 공식 공개 문서로 비공개 검증했고, 공개 본문에는 DAKER 정책에 맞는 내부 링크만 남깁니다. 이어서 볼 글은 아래 DAKER 글입니다.
FAQ: 실무자가 자주 묻는 질문은 무엇인가요?
subagent cap은 병렬 작업을 못 쓰게 하는 설정인가요?
아니요. 병렬 작업을 금지하는 것이 아니라 한 메시지가 통제 없이 하위 작업을 늘리는 상황을 줄이는 기준입니다.
nested subagent를 항상 막아야 하나요?
대부분의 팀 작업은 막는 편이 단순합니다. 꼭 필요한 경우에는 owner와 중단 조건을 명확히 둔 예외로만 열어야 합니다.
예산 cap은 완료된 작업에도 영향을 주나요?
공식 개선 내용은 cap 도달 뒤 새 spawn을 거절하고 실행 중 background agent도 멈추는 방향을 포함합니다. 팀에서는 작은 작업으로 동작을 확인해야 합니다.
보고서에는 어떤 숫자를 남기면 좋나요?
실행한 subagent 수, 중단된 subagent 수, 예산 cap 도달 여부, 남은 수동 확인 항목을 남기면 됩니다.
오늘은 팀의 Claude Code 작업 요청 한 개를 골라, 목표, 확인 기준, 남은 한계를 세 줄로 다시 써 보세요.