Claude Code /deep-research 검증 단계가 API 레이트리밋에 걸리는 이유와 queue 방식 해결

요약

목차

상황: Verify 단계에서 갑자기 막혔다

최근 Claude Code에서 /deep-research를 사용하다가 마지막 검증, 즉 Verify 단계에서 API 레이트리밋에 걸렸다. 앞의 조사 단계는 어느 정도 진행됐는데, 결과를 검증하는 시점에 갑자기 한도 초과가 발생한 것이다.

처음 보면 “검증 단계가 왜 이렇게 무겁지?”라고 생각하기 쉽다. 하지만 실제 원인은 Verify 자체라기보다, 그 전까지 쌓인 조사량과 에이전트 수, 그리고 그 에이전트들이 사용하는 토큰 총량이었다.

왜 레이트리밋이 발생했나

Anthropic 공식 문서 기준으로 API 한도는 단순 요청 횟수만 보지 않는다. Messages API의 rate limit은 RPM(requests per minute), ITPM(input tokens per minute), OTPM(output tokens per minute) 같은 단위로 측정된다. 이 중 하나라도 넘으면 429 오류가 발생할 수 있다.

구분	의미	deep-research에서 문제가 되는 지점
RPM	분당 요청 수	여러 에이전트가 병렬로 호출하면 빠르게 증가
ITPM	분당 입력 토큰 수	조사 자료, 이전 결과, 파일 내용, 중간 요약이 계속 프롬프트에 포함됨
OTPM	분당 출력 토큰 수	각 에이전트가 긴 분석과 검증 결과를 생성
Acceleration limit	짧은 시간에 사용량이 급증할 때 걸릴 수 있는 제한	한 번에 많은 조사 작업을 던졌을 때 발생 가능

여기서 중요한 부분은 “요청 수가 많다”만이 아니다. 요청은 몇 번 안 되는 것처럼 보여도, 각 요청이 매우 긴 입력과 출력을 포함하면 토큰 한도에 먼저 걸릴 수 있다. deep-research는 바로 이 패턴에 가깝다.

deep-research에서 특히 흔한 이유

Claude Code의 subagent 구조는 작업을 별도 컨텍스트에서 나눠 처리할 수 있다는 장점이 있다. 공식 문서에서도 subagent는 탐색 출력이 메인 대화 컨텍스트를 오염시키지 않도록 별도 context window에서 작업할 수 있다고 설명한다. 이 구조는 복잡한 조사에는 매우 유용하다.

문제는 deep-research가 보통 다음 흐름을 갖는다는 점이다.

1. 여러 하위 주제를 동시에 탐색한다.
2. 각 에이전트가 문서, 코드, 이슈, 웹 자료를 넓게 읽는다.
3. 각 에이전트가 중간 요약을 만든다.
4. 메인 에이전트가 그 결과를 다시 합친다.
5. 마지막 Verify 단계에서 근거, 누락, 충돌, 재현 가능성을 다시 확인한다.

이 과정은 품질 측면에서는 좋다. 하지만 토큰 비용 측면에서는 상당히 비싸다. 특히 Verify 단계는 “최종 답을 한 번 더 검증한다”는 가벼운 작업이 아니라, 이미 생산된 여러 조사 결과를 다시 읽고 비교하는 단계가 되기 쉽다.

queue 방식으로 쪼개서 처리하기

이번에 만족스러웠던 해결 방식은 deep-research의 전체 작업을 queue 방식으로 나누는 것이었다. 한 번에 “전부 조사하고 검증해줘”가 아니라, 조사 단위를 작게 쪼개고 하나씩 처리하게 만드는 방식이다.

방식	장점	위험
한 번에 전체 deep-research	빠르게 전체 그림을 볼 수 있음	병렬 에이전트와 Verify 단계에서 토큰 사용량 폭증
queue 방식 deep-research	주제별로 토큰 사용량을 제어하기 쉬움	총 시간은 조금 늘어날 수 있음
완전 수동 조사	한도 제어가 가장 쉬움	AI 에이전트의 장점을 덜 활용함

queue 방식의 핵심은 다음 네 가지다.

• 조사 범위를 작은 항목으로 분리한다. 예: 공식 문서, GitHub 이슈, 가격/한도, 실제 실패 사례, 대안 비교.
• 동시에 너무 많은 에이전트를 돌리지 않는다. 병렬성보다 안정성을 우선한다.
• 각 단계가 끝날 때 짧은 요약만 남긴다. 원문 전체를 다음 단계에 계속 끌고 가지 않는다.
• Verify도 항목별로 나눈다. 마지막에 전체를 한꺼번에 검증하지 않는다.

내가 실제로 바꾼 실행 구조

이번 케이스에서는 단순히 “천천히 해줘”라고 한 것이 아니라, 실행 구조 자체를 바꿨다. 핵심은 피크 동시성과 분당 토큰 사용량을 동시에 낮추는 것이었다.

구간	기존 방식	변경한 방식	효과
Verify	parallel로 전체 75개 claim을 한 번에 검증	3개 claim씩 배치로 나누고 순차 await	피크 동시성이 약 9개까지 치솟던 흐름을 낮춰 TPM 천장 아래로 내림
Fetch	pipeline 안에서 중첩 parallel 실행	Search를 먼저 끝내는 barrier를 둔 뒤, Fetch를 4개씩 순차 배치 처리	Fetch와 Verify가 겹치지 않아 순간 토큰 사용량이 줄어듦
총 작업량	claim 25개, fetch 15개	claim 18개, fetch 12개	총량은 줄였지만 핵심 검증 품질은 유지
검증 기준	넓은 범위를 한꺼번에 검증	3표 검증 품질은 유지	품질을 포기하지 않고 병목만 줄임
실행 상태	이전 실패의 Fetch 캐시가 남을 수 있음	fresh 실행으로 깨끗하게 재수집	지난 실패 상태를 물고 가지 않음

여기서 가장 효과가 컸던 부분은 Verify를 75개 전체 병렬 검증에서 3 claim 단위 순차 검증으로 바꾼 것이다. 검증 품질을 낮춘 것이 아니라, 검증이 몰리는 순간을 잘게 나눴다. Fetch도 마찬가지다. 검색과 수집과 검증이 동시에 겹치면 토큰 사용량이 순간적으로 튀기 때문에, Search를 먼저 끝낸 뒤 Fetch를 4개씩 처리하도록 barrier를 둔 것이 안정성에 도움이 됐다.

실제로 쓸 수 있는 요청 문장

다음처럼 요청하면 Claude Code가 무리하게 전체 deep-research를 한 번에 밀어붙이는 것을 줄일 수 있다.

/deep-research 하되, 전체 작업을 queue 방식으로 나눠서 진행해줘.

규칙:
1. Verify는 전체 claim을 한 번에 parallel로 검증하지 말고, 3 claim씩 배치로 나누어 순차 await한다.
2. Fetch는 pipeline 중첩 parallel로 돌리지 말고, Search를 먼저 끝낸 뒤 4개씩 순차 배치 처리한다.
3. Fetch 단계와 Verify 단계가 동시에 겹치지 않게 barrier를 둔다.
4. claim과 fetch 총량은 줄이되, 핵심 검증 기준은 유지한다. 예: claim 25→18, fetch 15→12.
5. 이전 실패의 Fetch 캐시를 물고 가지 않도록 fresh 실행으로 다시 수집한다.
6. 토큰 사용량이 커질 것 같으면 멈추고 현재 queue 상태를 보고한다.

조사 대상이 더 크다면 queue를 명시적으로 만들어 달라고 하는 편이 좋다.

먼저 조사 queue를 만들어줘.
각 queue item은 다음 형식으로 작성해줘.

- id
- 조사 질문
- 필요한 자료 유형
- 완료 조건
- Verify 조건

그리고 queue item을 순서대로 하나씩 처리해줘.

이러면 정상적인 흐름은 “조사 목록 생성 → 1번 처리 → 1번 검증 → 요약 압축 → 2번 처리”가 된다. 한 번에 모든 자료를 읽고 마지막에 Verify를 몰아치는 방식보다 훨씬 안정적이다.

실제로 막히는 부분과 해결

사례 1. Verify 단계에서 429 또는 rate limit 오류가 난다

이 경우 재시도만 반복하면 다시 막힐 가능성이 높다. 이미 컨텍스트와 중간 결과가 커진 상태이기 때문이다. 먼저 현재까지의 결과를 짧게 압축하고, 남은 검증 항목을 queue로 분리하는 편이 낫다.

지금까지 조사한 내용을 15줄 이내로 압축해줘.
남은 Verify 항목을 queue로 나누고, 가장 중요한 항목부터 하나씩 검증해줘.

사례 2. 에이전트들이 비슷한 자료를 반복해서 읽는다

deep-research에서는 여러 에이전트가 독립적으로 움직이면서 같은 문서나 같은 이슈를 반복해서 읽을 수 있다. 이러면 품질은 크게 늘지 않는데 토큰은 빠르게 늘어난다.

중복 조사를 피하기 위해, 각 queue item마다 이미 확인한 자료 목록을 유지해줘.
같은 URL이나 같은 파일을 다시 읽기 전에 왜 다시 읽어야 하는지 설명해줘.

사례 3. 마지막 종합 보고서가 너무 길어진다

최종 보고서가 길어질수록 Verify도 다시 무거워진다. 이때는 “최종 보고서”와 “검증 로그”를 분리하는 것이 좋다. 독자나 의사결정자에게 필요한 것은 대부분 짧은 결론이고, 전체 검증 로그는 필요할 때만 보면 된다.

최종 답변은 의사결정용 1페이지로 작성해줘.
검증 로그는 별도 섹션으로 분리하고, 핵심 근거 링크만 남겨줘.

결론

Claude Code /deep-research의 Verify 단계에서 API 레이트리밋이 발생했다면, Verify 기능 하나만 문제라고 보기 어렵다. 실제로는 여러 에이전트가 넓은 범위를 조사하면서 입력 토큰과 출력 토큰을 많이 사용했고, 마지막 검증 단계에서 그 비용이 한꺼번에 드러난 경우가 많다.

내가 얻은 결론은 간단하다. deep-research가 필요한 작업일수록 처음부터 queue 방식으로 쪼개는 것이 좋다. 병렬 에이전트를 많이 돌리는 대신, 조사 항목을 작게 나누고, 각 항목마다 짧게 요약하고, Verify도 단계별로 수행한다. 속도는 조금 느려질 수 있지만, 레이트리밋에 막혀 전체 작업이 중단되는 것보다 훨씬 낫다.

참고 자료

• 🔗 Anthropic API Docs: Rate limits
• 🔗 Claude Code Docs: Create custom subagents
• 🔗 Claude Code Docs: Troubleshooting performance and stability
• 🔗 Claude Code Docs: Slash commands