Claude Code 서브 에이전트의 대규모 출력으로 인한 사용량 소진 문제와 해결책

커뮤니티 반응

작성자의 경험에 공감하며, 에이전트의 자율적 행동이 의도치 않은 비용이나 사용량 소진으로 이어질 수 있다는 점에 주의를 기울이는 분위기이다.

주요 논점

01찬성다수

대규모 출력물은 파일로 관리하고 참조만 하는 방식이 API 안정성과 비용 효율성 측면에서 필수적이다.

합의점 vs 논쟁점

합의점

에이전트가 생성하는 데이터 크기가 API 제한을 초과할 경우 무한 재시도 루프가 발생할 수 있다.
사용량 캡(Usage Cap) 관리를 위해 에이전트의 출력 방식을 명확히 규정할 필요가 있다.

실용적 조언

claude.md 파일에 'Large outputs (>10KB) must be written to repo files' 지침을 추가하여 에이전트의 행동을 제약하라.
에이전트에게 결과물 전체를 보고하게 하지 말고, 파일 경로와 요약만 보고하도록 프롬프트를 구성하라.

섹션별 상세

작성자는 Claude Code에게 실행 전 계획 작성을 요청했으나, 서브 에이전트가 생성한 계획서가 API 응답 제한을 초과하는 문제가 발생했다. 시스템은 이를 처리하지 못하고 무한 재시도를 반복했으며, 결과적으로 사용자의 5시간 사용량 캡이 결과물 없이 모두 소진됐다. 이는 에이전트가 '도움이 되려는' 의도로 상세한 내용을 생성할 때 발생할 수 있는 전형적인 자원 낭비 사례이다.

문제의 핵심은 서브 에이전트가 대규모 텍스트 데이터를 채팅 메시지로 직접 반환하려고 시도했다는 점이다. API 응답 한도를 넘어서는 데이터가 전송될 경우 통신 오류가 발생하며, 메인 에이전트는 이를 복구하기 위해 동일한 요청을 반복하게 된다. 이러한 루프는 사용자에게 아무런 출력을 보여주지 않으면서 백그라운드에서 토큰과 사용 시간을 급격히 소모한다.

해결책으로 10KB 이상의 대규모 출력은 채팅창에 직접 뿌리는 대신 저장소 내 마크다운 파일로 작성하고 파일 경로만 반환하도록 지침을 설정했다. 메인 에이전트는 서브 에이전트가 생성한 파일의 경로, 요약, 핵심 결론 및 다음 단계만 메시지로 수신하여 컨텍스트 윈도우를 효율적으로 관리한다. 이 방식은 API 제한 문제를 원천 차단하고 모델의 추론 효율성을 높이는 실무적 접근이다.

markdown

## Tool Usage
- Large outputs (>10KB) from subagents or external tools must be written to repo files. Do not return full content directly.
- Messages should only include file paths, summaries, key conclusions, and next steps.

서브 에이전트가 대규모 출력을 생성할 때 파일로 저장하도록 강제하는 claude.md 설정 예시

용어 해설

서브 에이전트(Sub-agent): — 메인 AI 에이전트가 특정 작업을 수행하기 위해 생성하는 하위 에이전트이다. 복잡한 문제를 분할하여 처리할 수 있게 돕지만, 에이전트 간 통신 과정에서 불필요한 토큰 소모나 무한 루프가 발생할 위험이 있다.
사용량 제한(Usage Cap): — 특정 기간 동안 AI 모델이나 도구를 사용할 수 있는 최대 한도이다. Claude Code의 경우 5시간 단위의 사용량 캡이 존재하며, 효율적이지 못한 프롬프트나 에이전트 오류로 인해 이 한도가 빠르게 소진될 수 있다.
API 응답 제한(API Response Limit): — 한 번의 API 호출로 받을 수 있는 데이터의 최대 크기이다. 서브 에이전트의 출력이 이 제한을 초과하면 시스템은 오류를 발생시키거나 무한 재시도를 수행하여 자원을 낭비하게 된다.

언급된 도구

Claude Code중립

터미널 기반 AI 코딩 에이전트