50. 비용을 효과적으로 관리하기
토큰 비용 구조·사용량 확인·팀 한도·절감 전략 등 비용 관리 가이드
비용을 효과적으로 관리하기
토큰 사용량을 추적하고, 팀 지출 한도를 설정하며, 컨텍스트 관리, 모델 선택, extended thinking 설정, 전처리 hook을 통해 Claude Code 비용을 절감하세요.
Claude Code는 각 상호작용마다 토큰을 소비합니다. 비용은 코드베이스 크기, 쿼리 복잡도, 대화 길이에 따라 달라집니다. 평균 비용은 개발자 1인당 하루 $6이며, 90%의 사용자에서 일일 비용이 $12 미만으로 유지됩니다.
팀 사용 시 Claude Code는 API 토큰 소비량 기준으로 과금됩니다. 평균적으로 Claude Code는 Sonnet 4.6 기준 개발자 1인당 월 ~$100-200 정도이며, 사용자가 실행하는 인스턴스 수와 자동화에 사용하는지 여부에 따라 큰 차이가 있습니다.
이 페이지에서는 비용 추적 방법, 팀 비용 관리, 토큰 사용량 절감을 다룹니다.
비용 추적하기
/cost 명령어 사용하기
참고:
/cost명령어는 API 토큰 사용량을 표시하며 API 사용자를 위한 것입니다. Claude Max 및 Pro 구독자는 구독에 사용량이 포함되어 있으므로/cost데이터는 청구 목적과 관련이 없습니다. 구독자는/stats를 사용하여 사용 패턴을 확인할 수 있습니다.
/cost 명령어는 현재 세션의 상세한 토큰 사용량 통계를 제공합니다:
Total cost: $0.55
Total duration (API): 6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes: 0 lines added, 0 lines removed
팀 비용 관리하기
Claude API를 사용할 때 Claude Code workspace의 총 지출에 대해 workspace 지출 한도를 설정할 수 있습니다. 관리자는 Console에서 비용 및 사용량 보고서를 확인할 수 있습니다.
참고:
Claude Console 계정으로 Claude Code를 처음 인증하면 "Claude Code"라는 workspace가 자동으로 생성됩니다. 이 workspace는 조직 내 모든 Claude Code 사용에 대한 중앙 집중식 비용 추적 및 관리를 제공합니다. 이 workspace에 대한 API 키는 생성할 수 없으며, Claude Code 인증 및 사용 전용입니다.
Bedrock, Vertex, Foundry에서는 Claude Code가 클라우드에서 메트릭을 전송하지 않습니다. 비용 메트릭을 얻기 위해 여러 대기업이 LiteLLM을 사용한다고 보고했습니다. 이는 기업이 키별 지출을 추적할 수 있도록 도와주는 오픈소스 도구입니다. 이 프로젝트는 Anthropic과 관련이 없으며 보안 감사를 받지 않았습니다.
Rate limit 권장 사항
팀을 위해 Claude Code를 설정할 때, 조직 규모에 따른 사용자별 Token Per Minute(TPM) 및 Request Per Minute(RPM) 권장 사항을 고려하세요:
| 팀 규모 | 사용자별 TPM | 사용자별 RPM |
|---|---|---|
| 1-5 users | 200k-300k | 5-7 |
| 5-20 users | 100k-150k | 2.5-3.5 |
| 20-50 users | 50k-75k | 1.25-1.75 |
| 50-100 users | 25k-35k | 0.62-0.87 |
| 100-500 users | 15k-20k | 0.37-0.47 |
| 500+ users | 10k-15k | 0.25-0.35 |
예를 들어, 200명의 사용자가 있다면 각 사용자에게 20k TPM을 요청하여 총 400만 TPM(200*20,000 = 400만)을 할당할 수 있습니다.
사용자별 TPM은 팀 규모가 커질수록 감소하는데, 대규모 조직에서는 동시에 Claude Code를 사용하는 사용자가 적은 경향이 있기 때문입니다. 이 rate limit은 개별 사용자가 아닌 조직 수준에서 적용되므로, 다른 사용자가 서비스를 활발히 사용하지 않을 때 개별 사용자가 계산된 할당량보다 일시적으로 더 많이 소비할 수 있습니다.
참고:
비정상적으로 높은 동시 사용 시나리오(예: 대규모 그룹을 대상으로 한 라이브 교육 세션)가 예상되는 경우, 사용자별 TPM 할당을 더 높게 설정해야 할 수 있습니다.
Agent team 토큰 비용
Agent team은 각각 자체 컨텍스트 윈도우를 가진 여러 Claude Code 인스턴스를 생성합니다. 토큰 사용량은 활성 팀원 수와 각 팀원의 실행 시간에 따라 확장됩니다.
Agent team 비용을 관리 가능한 수준으로 유지하려면:
- 팀원에게 Sonnet을 사용하세요. 코디네이션 작업에서 성능과 비용의 균형을 잘 맞춥니다.
- 팀 규모를 작게 유지하세요. 각 팀원이 자체 컨텍스트 윈도우를 실행하므로 토큰 사용량은 팀 크기에 대략 비례합니다.
- spawn 프롬프트를 간결하게 유지하세요. 팀원은 CLAUDE.md, MCP 서버, skill을 자동으로 로드하지만, spawn 프롬프트의 모든 내용은 처음부터 컨텍스트에 추가됩니다.
- 작업이 완료되면 팀을 정리하세요. 활성 팀원은 유휴 상태에서도 계속 토큰을 소비합니다.
- Agent team은 기본적으로 비활성화되어 있습니다. 활성화하려면 settings.json 또는 환경에서
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1을 설정하세요. agent team 활성화를 참조하세요.
토큰 사용량 절감하기
토큰 비용은 컨텍스트 크기에 비례합니다: Claude가 처리하는 컨텍스트가 많을수록 더 많은 토큰을 사용합니다. Claude Code는 prompt caching(시스템 프롬프트와 같은 반복 콘텐츠의 비용을 절감)과 auto-compaction(컨텍스트 한도에 도달할 때 대화 기록을 요약)을 통해 자동으로 비용을 최적화합니다.
다음 전략은 컨텍스트를 작게 유지하고 메시지당 비용을 줄이는 데 도움이 됩니다.
컨텍스트를 사전에 관리하기
/cost를 사용하여 현재 토큰 사용량을 확인하거나, 상태 표시줄을 구성하여 지속적으로 표시할 수 있습니다.
- 작업 간 초기화: 관련 없는 작업으로 전환할 때
/clear를 사용하여 새로 시작하세요. 오래된 컨텍스트는 이후 모든 메시지에서 토큰을 낭비합니다. 초기화 전에/rename을 사용하여 나중에 세션을 쉽게 찾을 수 있도록 하고,/resume으로 돌아올 수 있습니다. - 사용자 정의 compaction 지침 추가:
/compact Focus on code samples and API usage는 요약 시 무엇을 보존할지 Claude에게 알려줍니다.
CLAUDE.md에서 compaction 동작을 커스터마이즈할 수도 있습니다:
# Compact instructions
When you are using compact, please focus on test output and code changes
적절한 모델 선택하기
Sonnet은 대부분의 코딩 작업을 잘 처리하며 Opus보다 비용이 적게 듭니다. Opus는 복잡한 아키텍처 결정이나 다단계 추론에 사용하세요. /model을 사용하여 세션 중에 모델을 전환하거나, /config에서 기본값을 설정할 수 있습니다. 단순한 subagent 작업의 경우, subagent 구성에서 model: haiku를 지정하세요.
MCP 서버 오버헤드 줄이기
각 MCP 서버는 유휴 상태에서도 컨텍스트에 tool 정의를 추가합니다. /context를 실행하여 무엇이 공간을 차지하고 있는지 확인하세요.
- CLI 도구가 있으면 CLI 도구를 우선 사용:
gh,aws,gcloud,sentry-cli와 같은 도구는 영구적인 tool 정의를 추가하지 않으므로 MCP 서버보다 컨텍스트 효율적입니다. Claude는 오버헤드 없이 직접 CLI 명령어를 실행할 수 있습니다. - 사용하지 않는 서버 비활성화:
/mcp를 실행하여 구성된 서버를 확인하고 활발히 사용하지 않는 서버를 비활성화하세요. - Tool search는 자동: MCP tool 설명이 컨텍스트 윈도우의 10%를 초과하면, Claude Code가 자동으로 이를 지연시키고 tool search를 통해 필요 시 로드합니다. 지연된 tool은 실제로 사용될 때만 컨텍스트에 진입하므로, 임계값이 낮을수록 유휴 tool 정의가 차지하는 공간이 줄어듭니다.
ENABLE_TOOL_SEARCH=auto:<N>으로 더 낮은 임계값을 설정하세요(예:auto:5는 tool이 컨텍스트 윈도우의 5%를 초과할 때 트리거됩니다).
타입 언어를 위한 code intelligence 플러그인 설치하기
Code intelligence 플러그인은 텍스트 기반 검색 대신 정확한 심볼 탐색을 제공하여, 익숙하지 않은 코드를 탐색할 때 불필요한 파일 읽기를 줄입니다. 단일 "go to definition" 호출이 grep 후 여러 후보 파일을 읽는 것을 대체합니다. 설치된 language server는 편집 후 자동으로 타입 오류를 보고하므로, Claude가 컴파일러를 실행하지 않고도 실수를 잡아냅니다.
처리를 hook과 skill로 오프로드하기
커스텀 hook은 Claude가 데이터를 보기 전에 전처리할 수 있습니다. Claude가 오류를 찾기 위해 10,000줄의 로그 파일을 읽는 대신, hook이 ERROR를 grep하여 일치하는 줄만 반환하면 컨텍스트를 수만 개의 토큰에서 수백 개로 줄일 수 있습니다.
Skill은 Claude에게 도메인 지식을 제공하여 탐색할 필요가 없도록 합니다. 예를 들어, "codebase-overview" skill은 프로젝트의 아키텍처, 주요 디렉토리, 네이밍 규칙을 설명할 수 있습니다. Claude가 skill을 호출하면 구조를 이해하기 위해 여러 파일을 읽는 데 토큰을 소비하는 대신 즉시 이 컨텍스트를 얻습니다.
예를 들어, 이 PreToolUse hook은 테스트 출력을 필터링하여 실패만 표시합니다:
settings.json
모든 Bash 명령어 실행 전에 hook을 실행하려면 settings.json에 다음을 추가하세요:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "~/.claude/hooks/filter-test-output.sh"
}
]
}
]
}
}
filter-test-output.sh
hook은 이 스크립트를 호출하며, 명령어가 테스트 러너인지 확인하고 실패만 표시하도록 수정합니다:
#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')
# If running tests, filter to show only failures
if [[ "$cmd" =~ ^(npm test|pytest|go test) ]]; then
filtered_cmd="$cmd 2>&1 | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100"
echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"updatedInput\":{\"command\":\"$filtered_cmd\"}}}"
else
echo "{}"
fi
CLAUDE.md의 지침을 skill로 이동하기
CLAUDE.md 파일은 세션 시작 시 컨텍스트에 로드됩니다. PR 리뷰나 데이터베이스 마이그레이션과 같은 특정 워크플로우에 대한 상세한 지침이 포함되어 있으면, 관련 없는 작업을 수행할 때도 해당 토큰이 존재합니다. Skill은 호출될 때만 필요 시 로드되므로, 전문 지침을 skill로 이동하면 기본 컨텍스트가 작아집니다. CLAUDE.md는 필수 사항만 포함하여 ~500줄 이하로 유지하는 것을 목표로 하세요.
Extended thinking 조정하기
Extended thinking은 복잡한 계획 수립 및 추론 작업의 성능을 크게 향상시키기 때문에 기본적으로 31,999 토큰 예산으로 활성화되어 있습니다. 그러나 thinking 토큰은 출력 토큰으로 과금되므로, 깊은 추론이 필요하지 않은 단순한 작업의 경우 Opus 4.6의 /model에서 effort level을 낮추거나, /config에서 thinking을 비활성화하거나, 예산을 줄여(예: MAX_THINKING_TOKENS=8000) 비용을 절감할 수 있습니다.
장황한 작업을 subagent에 위임하기
테스트 실행, 문서 가져오기, 로그 파일 처리는 상당한 컨텍스트를 소비할 수 있습니다. 이를 subagent에 위임하면 장황한 출력은 subagent의 컨텍스트에 남고 요약만 메인 대화에 반환됩니다.
Agent team 비용 관리하기
Agent team은 팀원이 plan 모드에서 실행될 때 표준 세션보다 약 7배 더 많은 토큰을 사용합니다. 각 팀원이 자체 컨텍스트 윈도우를 유지하고 별도의 Claude 인스턴스로 실행되기 때문입니다. 팀원별 토큰 사용량을 제한하려면 팀 작업을 작고 자체 완결적으로 유지하세요. 자세한 내용은 agent team을 참조하세요.
구체적인 프롬프트 작성하기
"이 코드베이스를 개선해줘"와 같은 모호한 요청은 광범위한 스캔을 유발합니다. "auth.ts의 로그인 함수에 입력 검증을 추가해줘"와 같은 구체적인 요청은 Claude가 최소한의 파일 읽기로 효율적으로 작업할 수 있게 합니다.
복잡한 작업에서 효율적으로 작업하기
더 길거나 복잡한 작업의 경우, 이러한 습관이 잘못된 방향으로 인한 토큰 낭비를 방지하는 데 도움이 됩니다:
- 복잡한 작업에 plan 모드 사용: 구현 전에 Shift+Tab을 눌러 plan 모드로 진입하세요. Claude가 코드베이스를 탐색하고 승인을 위한 접근 방식을 제안하여, 초기 방향이 잘못되었을 때의 비용이 큰 재작업을 방지합니다.
- 빠른 방향 수정: Claude가 잘못된 방향으로 가기 시작하면 즉시 Escape를 눌러 중지하세요.
/rewind를 사용하거나 Escape를 두 번 눌러 대화와 코드를 이전 체크포인트로 복원하세요. - 검증 대상 제공: 프롬프트에 테스트 케이스를 포함하거나, 스크린샷을 붙여넣거나, 예상 출력을 정의하세요. Claude가 자체적으로 작업을 검증할 수 있으면 수정을 요청하기 전에 문제를 잡아냅니다.
- 점진적 테스트: 파일 하나를 작성하고 테스트한 후 계속하세요. 이렇게 하면 수정 비용이 적을 때 문제를 조기에 발견합니다.
백그라운드 토큰 사용량
Claude Code는 유휴 상태에서도 일부 백그라운드 기능에 토큰을 사용합니다:
- 대화 요약:
claude --resume기능을 위해 이전 대화를 요약하는 백그라운드 작업 - 명령어 처리:
/cost와 같은 일부 명령어는 상태를 확인하기 위한 요청을 생성할 수 있음
이러한 백그라운드 프로세스는 활성 상호작용 없이도 소량의 토큰(일반적으로 세션당 $0.04 미만)을 소비합니다.
Claude Code 동작 변경 이해하기
Claude Code는 비용 보고를 포함하여 기능 작동 방식을 변경할 수 있는 업데이트를 정기적으로 받습니다. claude --version을 실행하여 현재 버전을 확인하세요. 구체적인 청구 관련 질문은 Console 계정을 통해 Anthropic 지원팀에 문의하세요. 팀 배포의 경우, 광범위한 배포 전에 소규모 파일럿 그룹으로 사용 패턴을 확인하세요.