Claude Code를 사용하며 예상치 못한 일을 겪게 되어 이를 공유하고자 합니다. 저는 매일 Claude Code를 사용하며 제 워크플로에 정말 유용하다고 느끼지만, 이번 일은 Claude Code 사용자라면 반드시 알아야 할 내용입니다.

무슨 일이 일어났나
제가 Claude Code에게 제가 구축 중인 기능(AI 조립 UI 컴포넌트)을 위한 오픈 소스 프레임워크를 조사해 달라고 요청했습니다. 몇 가지 라이브러리를 찾아보고, 접근 방식을 비교하며, 조사 결과를 요약하는 아주 단순한 리서치 작업이었습니다.
Claude는 병렬 검색을 위해 2개의 범용 에이전트(general-purpose agents)를 생성했습니다.
제가 깨닫지 못했던 점은 다음과 같습니다: 그 에이전트들이 각각 더 많은 하위 에이전트(sub-agents)를 생성했고, 그 하위 에이전트들이 또 더 많은 에이전트를 생성했다는 것입니다. 무언가 잘못되었다는 것을 알아차렸을 때, 제 MAX 플랜의 5시간 롤링 할당량(rolling quota)은 이미 사라진 상태였습니다.

이후 세션 트랜스크립트(session transcripts)를 확인해 보았습니다:

• 약 10분의 시간 동안 생성된 339개의 하위 에이전트 트랜스크립트 파일

• 메인 모델의 결과 처리 시간을 포함하여 전체 과정은 26분이 소요되었습니다 (26분 25초 동안 처리됨)

• 해당 에이전트들의 토큰 사용량:

  • output_tokens: 846,348
  • cache_creation_input_tokens: 9,942,567
  • cache_read_input_tokens: 64,696,978
  • input_tokens: 699,715

• 339개의 에이전트 중 295개(87%)가 속도 제한(rate limits)에 걸려 아무것도 반환하지 못했습니다. 시스템 프롬프트와 설정에만 토큰이 소모되었습니다.

왜 이런 일이 발생했나
Claude Code v2.1.172 (제 사례 발생 3일 전인 2026년 6월 10일 버전)는 하위 에이전트가 최대 5단계 깊이까지 자체적인 하위 에이전트를 생성할 수 있도록 허용했습니다.
핵심 문제는 범용 에이전트(general-purpose agent) 유형에 있습니다. 이 유형은 에이전트 도구(Agent tool) 자체를 포함한 모든 도구에 접근할 수 있습니다. 따라서 리서치를 요청하면, 에이전트는 자율적으로 더 많은 에이전트를 생성하여 확장(fan out)하기로 결정할 수 있으며, 실제로 그렇게 합니다. 이 자식 에이전트들 또한 에이전트 도구를 가지고 있으므로 똑같이 확장합니다. 설계상 재귀적(recursive)인 구조입니다.

Explore나 Plan과 같은 다른 에이전트 유형은 도구 세트에서 에이전트 도구를 명시적으로 제외하므로 재귀가 불가능합니다. 하지만 범용(general-purpose)은 기본값입니다. 유형을 지정하지 않으면 바로 이 유형이 적용됩니다.

부족한 점
이 부분에 대한 내장된 가드레일(guardrail)이 없습니다:

• 토큰 예산 경고 없음: 작업이 실행되기 전에 "이 작업은 약 ~50개의 에이전트를 생성합니다. 계속하시겠습니까?"와 같은 확인 절차가 없습니다.
• 속도 제한(rate-limit) 인지 능력 없음: 제 에이전트의 87%가 속도 제한에 걸렸지만, 팬아웃(fan-out)을 더 일찍 중단할 수 있는 메커니즘이 없습니다.
• 모델이 팬아웃을 결정함: 재귀적 생성(recursive spawning)에 대한 사용자 확인 단계가 없습니다.
• 재귀적 생성이 기본값으로 설정됨: 이를 끌 수 있는 설정이 없습니다. 아마도 반대로 설정되어야 했을 것입니다.

공정하게 말하자면, 워크플로당 1,000개의 에이전트 제한과 최대 5단계의 깊이 제한이 있기는 합니다. 하지만 1,000개라는 숫자는... 대부분의 MAX 플랜 사용자가 테스트하고 싶어 할 만한 가드레일은 아닙니다.

해결책
저는 Explore나 Plan과 같이 안전한 유형은 허용하면서, (재귀가 가능한 유일한 유형인) 범용(general-purpose) 에이전트를 차단하는 PreToolUse 훅(hook)을 작성했습니다.
Console (API 과금) 사용자들을 위한 참고 사항: 상황은 훨씬 더 나쁠 수 있습니다. 할당량 제한(quota cap)이 없으며, 단지 청구 금액만 계속 늘어날 뿐입니다. 재귀적 에이전트는 1,000개 에이전트 제한이나 5단계 깊이 제한에 도달할 때까지 계속 실행됩니다.

시사점

• 단 하나의 리서치 프롬프트가 확인 절차 없이 수백 개의 재귀적 하위 에이전트를 생성할 수 있으며, 저는 '수정 수락(accept edits)' 모드에서 실행 중이었지 '자동(auto)'이나 '우회(bypass)' 모드가 아니었습니다.

• 범용(general-purpose) 에이전트 유형이 근본 원인입니다. 이것이 기본값이며, 에이전트 도구(Agent tool)에 접근할 수 있어 재귀가 가능하기 때문입니다.

• 중첩된 생성(nested spawning)을 비활성화하거나 최대 깊이를 설정하는 내장 설정이 없습니다. 현재로서는 PreToolUse 훅이 유일한 사용자 측 가드레일입니다.

• 이 기능은 기본 활성화(opt-on-by-default)가 아니라 선택적 활성화(opt-in) 방식이어야 합니다. 대부분의 사용자는 5단계의 재귀적 에이전트 트리가 필요하지 않습니다.

  제출자: /u/cvdaystar
  [link] [comments]