Claude Code Task Budgets, 왜 안 될까 — API 비용 폭주 진짜로 막는 법 (2026)

Claude Code 쓰다가 "이거 토큰을 너무 많이 먹는데, Task Budgets라는 게 있다던데 그거 설정하면 되나?" 싶어서 찾아본 분 꽤 있을 겁니다. 저도 처음엔 그렇게 생각했는데, 공식 문서를 열어보니 마지막 줄에 이렇게 딱 적혀 있더라고요. "Task budgets are not supported on Claude Code or Cowork surfaces." 그러니까 Claude Code나 Cowork에서는 이 기능 자체가 안 됩니다. 근데 그럼 대체 Claude Code에서 진짜 비용 폭주는 뭘로 막아야 하나 — 이게 이 글의 진짜 질문입니다.

Claude Platform Docs의 Task budgets 문서 중 "Not supported on Claude Code or Cowork surfaces" 문구가 있는 Feature support 섹션 캡처

 

Task Budgets가 Claude Code에서 안 되는 이유

결론부터 말하면 Task Budgets는 Claude API의 output_config.task_budget 파라미터입니다. Messages API를 직접 호출하는 개발자용 기능이지, Claude Code CLI 안에 노출되는 설정값이 아니에요. 공식 문서 Feature support 섹션에 "지원 모델에서 Messages API를 통해 직접 사용하라"고 명시돼 있으니, Claude Code 설정 파일 어디를 뒤져도 이 옵션은 나오지 않습니다. 검색해서 여기 들어온 분이라면 이 부분부터 확실히 짚고 넘어가는 게 맞다고 봅니다 — 없는 기능을 찾느라 시간 쓸 필요는 없으니까요.

 

그래서 Task Budgets는 정확히 뭔가

간단히만 짚고 넘어가겠습니다. Task budgets는 Claude에게 "이번 에이전틱 루프(사고+툴콜+툴결과+출력 전체)에서 쓸 수 있는 토큰이 이 정도"라고 미리 알려주는 기능입니다. output_config.task_budget = {"type": "tokens", "total": 64000} 형태로 설정하고 anthropic-beta: task-budgets-2026-03-13 헤더를 붙여야 하는데, 여기서 중요한 건 이게 하드 캡이 아니라는 점이에요. 공식 문서 표현 그대로 "advisory, not enforced" — 권고일 뿐 강제가 아닙니다. Claude는 예산을 넘겨서라도 작업을 계속할 수 있고, 진짜 절대 상한이 필요하면 max_tokens를 같이 걸어야 합니다. 최소 설정값도 20,000토큰이라 이보다 작게 잡으면 400 에러가 나고, 너무 낮게 잡으면 오히려 Claude가 작업을 거절하거나 대충 끝내버리는 부작용이 생길 수 있다고 문서는 경고합니다. 지원 모델도 아직 Claude Fable 5·Mythos 5·Opus 4.8·Opus 4.7 정도로 베타 단계고, 정작 많이 쓰는 Sonnet 5나 Opus 4.6, Haiku 4.5에서는 아예 지원하지 않습니다.

task_budget 파라미터 구조도 - total, remaining, type 필드 설명

 

Claude Code에서 진짜 비용 폭주를 막는 법

Task Budgets는 못 쓰지만, Claude Code 자체 비용 관리 문서를 보면 이미 쓸 수 있는 도구가 여럿 있습니다. 사실 이쪽이 진짜 실전 정보입니다.

• /usage: 현재 세션 토큰 사용량과 로컬 추정 비용을 바로 보여줍니다. Pro/Max/Team/Enterprise 플랜이면 스킬·서브에이전트·플러그인·MCP 서버별로 어디서 얼마나 썼는지 24시간/7일 단위로 쪼개서 볼 수 있어요.
• /usage-credits: Pro·Max 플랜에서 월간 지출 한도를 직접 걸 수 있습니다. 한도에 닿으면 CLI 안에서 올릴지 말지 물어보는데, 결제 권한이 있어야 변경 가능합니다.
• 워크스페이스 지출 한도: Claude API로 쓰는 경우 Claude Code 전용 워크스페이스 전체에 지출 한도를 걸 수 있고, 관리자는 콘솔에서 비용 리포트를 확인합니다.
• 조직 레이트리밋: 팀 규모별 권장치가 따로 있습니다. 1~5명 팀이면 사용자당 200k~300k TPM에 5~7 RPM 정도, 500명 넘는 조직이면 오히려 사용자당 10k~15k TPM, 0.25~0.35 RPM으로 낮춥니다.

여기서 진짜 조심해야 할 부분이 에이전트 팀(Agent teams)입니다. 여러 Claude Code 인스턴스를 동시에 띄우는 기능이라 팀원 수만큼 토큰 소비가 배로 늘어나는데, 플랜 모드로 돌리는 에이전트 팀은 표준 세션 대비 무려 7배 더 많은 토큰을 씁니다. 기본적으로 꺼져 있고 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 환경변수를 켜야 활성화되는데, 켤 거면 팀 규모를 작게, spawn 프롬프트는 간결하게, 작업 끝난 팀원은 바로 종료하는 게 낫습니다. 이 프로젝트도 오케스트레이터-서브에이전트 구조를 쓰고 있는데, 서브에이전트가 늘어날수록 토큰이 배로 불어난다는 걸 체감하고 나서는 spawn 프롬프트를 최대한 짧게 쓰려고 신경 쓰게 됐습니다.

이 외에도 컨텍스트 관리(/clear, /compact), 서브에이전트에 Haiku 지정하기, CLAUDE.md는 200줄 이하로 유지하고 나머지는 skills로 옮기기 같은 절감 전략이 있습니다. 참고로 엔터프라이즈 평균은 개발자 1인당 활성일 기준 약 $13, 월 $150~250 수준이고 상위 90% 사용자는 활성일당 $30 미만이라고 하니, 이 범위를 크게 벗어난다면 뭔가 새고 있다는 신호로 봐도 됩니다.

Claude Code /usage 명령어 실행 화면 - 스킬/서브에이전트별 사용량 분류 예시

 

Uber도 못 피한 비용 폭주, 그래서 나온 Spend-Threshold Alerts

이 기능들이 왜 이렇게 촘촘해졌는지 배경을 보면 이해가 빠릅니다. 보도에 따르면 Uber는 2025년 12월 약 5,000명 엔지니어에게 Claude Code를 배포했고, 넉 달 만인 2026년 4월에 그해 AI 예산 전체를 에이전틱 코딩 세션으로 다 써버렸습니다. 더 극단적인 사례도 있는데, 어떤 기업은 사용량 상한을 아예 걸지 않은 채 배포했다가 한 달 만에 약 5억 달러를 지출했다고 Axios가 보도했어요. 5억 달러, 숫자만 봐도 아찔합니다. Microsoft는 2026 회계연도 마감을 앞두고 한 사업부 내부 Claude Code 라이선스를 취소하기 시작했다는 얘기까지 나왔고요.

이런 배경 속에서 Anthropic은 2026년 7월 2일 Claude Enterprise용 관리자 도구를 새로 공개했습니다. 그룹·사용자별 분석 대시보드, Claude Code 전용 "Usage"·"Value" 탭(활성 개발자 수, 세션 수, 커밋당 비용까지 보여줌), 자연어로 질의하는 Analytics Chat, 그리고 핵심인 Spend-Threshold Alerts — 조직 지출 한도의 75%·90%에 도달하면, 개인 사용자는 75%·95%에 도달하면 알림을 보내는 기능입니다. 에이전틱 AI 툴이 단순 챗 질의보다 최대 1000배 많은 토큰을 소비할 수 있다는데, 이 정도면 클라우드 컴퓨팅 시대의 FinOps(재무 운영) 개념이 에이전틱 AI에도 그대로 옮겨올 만하지 않을까요?

 

3rd party 가이드와 공식 문서가 다르게 말하는 부분

찾아보다 보면 헷갈릴 수 있는 부분이 하나 있습니다. Verdent라는 곳의 가이드(2026-04-27 발행)는 "task budgets를 API 파라미터나 Claude Code 설정으로 구성한다"고 서술하고 있어요. 근데 이건 공식 문서의 "Claude Code 미지원" 명시와 정면으로 충돌합니다. 이런 경우엔 1차 소스, 그러니까 Anthropic 공식 문서 쪽을 믿는 게 맞습니다. Verdent 쪽 서술은 베타 초기에 나온 부정확한 정보이거나, 이후 문서가 갱신되기 전 스냅샷일 가능성이 커 보입니다. 이 글 쓰면서 느낀 건데, AI 관련 기능은 베타 딱지 붙은 채로 몇 달씩 가는 경우가 많아서 3rd party 가이드보다는 항상 공식 문서의 "Feature support" 같은 섹션을 마지막에 한 번 더 확인하는 습관이 필요합니다.

 

지금 바로 확인해볼 것

API를 직접 호출하는 개발자가 아니라면 Task Budgets는 신경 쓸 필요도 없어요. 대신 /usage로 지금 얼마나 쓰고 있는지부터 확인하고, /usage-credits로 상한을 걸고, 팀 단위라면 관리자에게 Spend-Threshold Alerts가 켜져 있는지 물어보는 쪽이 훨씬 현실적인 대응입니다. 에이전트 팀 같은 실험적 기능을 켜뒀다면, 지금 바로 사용량부터 한번 확인해 보세요!