Claude Code가 스스로 사용량 제한을 인지하게 만드는 방법
I made Claude Code aware of its own usage limits
핵심 요약
Claude Code가 API 사용량 제한을 스스로 파악하고 작업 강도를 조절할 수 있도록 로컬 프록시를 구축한 사례.
- 사용량 제한 인지 — Claude Code가 API 할당량을 알 수 있도록 로컬 프록시를 통해 헤더 정보를 추출함.
- 자동 조절 기능 — 사용량 상태를 파일로 기록해 Claude가 스스로 작업 강도를 조절하도록 설정함.
- 통합 할당량 발견 — Sonnet과 Opus가 별도의 제한이 아닌 하나의 통합된 할당량을 공유한다는 사실을 확인함.
- 구현 방식 — Node.js 기반의 가벼운 프록시로 별도 의존성 없이 로컬에서 구동 가능함.
한동안 나를 짜증나게 했던 문제가 있었는데, Claude Code는 자기가 할당량을 얼마나 썼는지 전혀 모른다는 거야. UI에서 사용량 막대를 볼 수는 있지만, 모델 자체는 그걸 전혀 알지 못해. 대화 중에 현재 속도 제한 상태를 알려주는 API나 도구, 훅 같은 게 전혀 없거든.
알고 보니 Anthropic은 모든 추론 응답에 속도 제한 헤더(anthropic-ratelimit-unified-5h-utilization, anthropic-ratelimit-unified-7d-utilization 등)를 반환하더라고. Claude Code는 UI 막대를 렌더링하기 위해 내부적으로 이 헤더를 받지만, 모델이 볼 수 있는 곳으로는 전혀 전달하지 않아.
그래서 Claude Code와 api.anthropic.com 사이에 위치하는 작은 로컬 HTTP 프록시를 만들었어. Claude Code는 이미 ANTHROPIC_BASE_URL을 따르기 때문에, 이걸 http://127.0.0.1:4080으로 설정하면 모든 트래픽이 프록시를 거치게 돼. 프록시는 응답 헤더를 가로채서 ~/.claude/usage-status.md 파일에 한 줄짜리 상태를 기록해.
5h=9% 7d=99%! overage=0% bottleneck=seven_day (10/05/2026, 16:19:04)
Claude는 필요할 때 이 파일을 읽을 수도 있고, UserPromptSubmit 훅을 통해 모든 프롬프트에 자동으로 주입할 수도 있어. CLAUDE.md에 규칙을 추가하면, Claude는 할당량이 거의 다 찼을 때 큰 작업을 시작하기 전에 경고를 해주거나, 90% 이상일 때 경량 모드로 전환하거나, 98%일 때 새로운 구현 작업을 거부하게 할 수 있지.
참고: 이건 Claude Code(CLI)에서만 작동해. 웹 채팅과 브라우저 확장 프로그램은 Anthropic 자체 인프라를 통해 요청을 보내기 때문에 가로챌 로컬 프록시가 없어.
흥미로운 발견: 테스트하는 동안 Opus와 Sonnet 요청 모두에서 모든 anthropic-ratelimit-* 헤더를 덤프해봤어. 모델별 헤더는 없더라고. 하나의 통합된 풀이 모든 걸 커버해. Claude Code UI의 별도 Sonnet 사용량 막대는 실제 별도의 제한을 반영하는 게 아니야. GitHub 이슈 #57050에 따르면, Anthropic은 (2025년 11월에 발표된 대로) Sonnet에 자체 버킷을 주려고 했지만 백엔드에 적용되지 않았어. Sonnet을 사용하는 것도 Opus와 같은 통합 풀을 소모해.
이 프록시는 npm 의존성이 없는 순수 Node.js 표준 라이브러리야. 윈도우에서는 NSSM을 통해 서비스로 설치돼. macOS와 Linux 설정(launchd/systemd)은 README에 있어.
https://github.com/InertiaUK/claude-quota-proxy
README에는 Claude가 사용량 수준에 따라 자동으로 행동을 조정하게 만들고 싶을 때 사용할 수 있는 몇 가지 CLAUDE.md 규칙 예시도 있어.
