클라우드 코드 API 요금 폭탄을 막는 토큰 예산 관리 스크립트
1. 토큰 상한선 설정으로 과금 차단하기
소형 프로젝트를 돌리다 API 요금 고지서를 보고 깜짝 놀란 적이 있다면 예산 제한이 없었기 때문이다. 에이전트는 생각보다 대화 맥락을 길게 유지하고 불필요한 파일 내용을 반복해서 읽어들인다. 방치하면 하루 만에 몇십만 토큰이 사라진다. ~/.claude/settings.json 파일을 열어 세션과 일일 사용량을 직접 제한해야 한다.
사용자 전역 설정 파일에 budget 객체를 추가하는 방법은 다음과 같다.
- 터미널을 열고 편집기로 ~/.claude/settings.json 파일을 연다.
- JSON 블록 내부에 sessionLimit 값을 500000으로, dailyLimit 값을 2000000으로 입력한다.
- warningThreshold를 0.75로 지정하고 autoCompactAt을 0.60으로 설정해 저장한다.
컨텍스트 용량이 60퍼센트에 도달하면 대화 이력이 자동으로 압축되면서 불필요한 토큰 낭비가 사라진다. 일일 한도에 도달하기 전에 세션이 차단되므로 예산 초과 걱정에서 벗어날 수 있다.
2. 3회 연속 에러 시 강제 중단하는 루프 브레이커 구축
에이전트가 문법 오류나 파일 경로 문제로 같은 훅에서 막히면 해결하지 못한 채 무한 루프를 돈다. 이 상태를 방치하면 수 분 만에 세션 토큰이 바닥난다. 프롬프트에 조심하라고 적어두는 것만으로는 소용이 없다. 쉘 스크립트 기반의 훅 시스템을 묶어 물리적으로 차단해야 한다.
동일한 에러를 3번 연속 감지하면 프로세스를 즉시 끝내는 훅 스크립트를 만든다.
- 프로젝트 디렉토리에 .claude/hooks/loop-breaker.sh 파일을 만들고 실행 권한을 부여한다.
- 스크립트 안에서 임시 상태 파일을 참조해 에러 카운터를 1씩 올리고, 누적 횟수가 3 이상이면 표준 에러를 뱉고 종료 코드 2를 반환해 작업을 강제 중단한다.
- .claude/settings.json 파일의 PostToolUseFailure 항목에 해당 스크립트 경로를 등록해 실시간으로 감시하게 만든다.
이 장치를 걸어두면 에이전트가 엉뚱한 코드를 무한정 고치며 토큰을 태우는 현상이 사라진다. 디버깅 지옥에서 낭비하던 시간을 아낄 수 있다.
3. 작업 성격에 따른 모델 루팅과 수동 승인 구간 분리
모든 코딩 작업을 Claude에게 전적으로 맡기면 예산이 버티지 못한다. 단순 포맷팅이나 보일러플레이트 작성은 가벼운 모델에 넘기고, 데이터베이스 마이그레이션처럼 되돌릴 수 없는 작업은 개발자가 직접 승인해야 한다. 쉘 앨리어스를 활용해 과업 난이도에 맞는 실행 환경을 구축한다.
작업 성격별로 에이전트 위임 명령어를 분리하는 설정은 다음과 같다.
- ~/.bashrc 또는 ~/.zshrc 파일을 연다.
- 단순 문서화 작업용으로
alias cc-quick='claude --model claude-haiku-3-20250307 --token-budget 100000' 명령어를 등록한다.
- 일반 기능 개발용으로
alias cc-dev='claude --model claude-sonnet-4-20250514 --token-budget 500000 --thinking-budget 8000' 명령어를 추가하고 터미널을 재시작한다.
이 방식을 적용하면 단순 반복 코딩의 90퍼센트를 에이전트가 안전하게 처리하고, 100만 토큰당 완성되는 PR 비율이 눈에 띄게 올라간다. 불필요한 API 비용을 확실하게 반으로 줄이는 가장 현실적인 방법이다.