요약(TL;DR): 내 API 비용의 68%는 프롬프트나 모델 완성(model completions)이 아닌 도구 결과(tool results)에서 발생합니다. 10억 개 이상의 재사용된 토큰에 대해 96.7%의 캐시 효율성을 보였으며, 휘발성 캐시(ephemeral cache)가 열심히 작동하고 있지만 심각한 누수가 있습니다. Claude Code는 파일을 4,600회 이상 읽습니다. 즉, 세션당 동일한 파일을 여러 번 반복해서 읽는 경우가 빈번합니다. 5분에서 60분 동안 지속되는 유휴 간격(Idle gaps)은 캐시를 떨어뜨리고 비용을 낭비합니다 (내 세션에서 147개의 간격 발견). 이 포스트는 프록시가 어떻게 작동하는지, 무엇을 배웠는지, 그리고 여러분의 에이전트 워크플로우(agent workflows)에서 이러한 숨겨진 비용을 어떻게 찾아내는지 설명합니다.

프록시 작동 방식
네트워크 탭(network tap)이라고 생각하면 됩니다. Claude Code와 Anthropic API 사이의 로컬에 위치합니다:

사용자 → Claude Code → [aap proxy] → Anthropic API
↓ 모든 바이트 기록
↓ SQLite 데이터베이스
↓ 대시보드

설치:
git clone https://github.com/rguiu/ai-agent-profiler.git
cd ai-agent-profiler
npm install && npm run build && npm link

별도의 터미널에서 프록시와 에이전트를 시작하세요:

터미널 1: localhost:3030에서 프록시 + 대시보드 시작

aap serve

터미널 2: 프로젝트 디렉토리에서 Claude Code 실행

aap run claude

프록시는 읽기 전용이며 바이트 단위로 충실합니다:

• 모든 요청을 변경 없이 전달합니다.
• 원시 요청/응답 스트림을 NDJSON으로 기록합니다.
• 백프레셔(backpressure)가 없는 밀리초 미만의 핫패스(hot-path) 오버헤드.
• 모든 비밀 정보(API 키, 인증 헤더)는 저장 전에 삭제(redacted)됩니다.

백그라운드 작업이 트레이스(traces)를 파싱하여 SQLite에 저장하며, 토큰 수, 제공업체 비용, 요청 분류(사용자 턴, 도구 결과, 검색, 압축), 그리고 개별 도구 호출을 추출합니다. 모든 것은 사용자의 로컬 머신에 머뭅니다. 계정, 클라우드 백엔드, 텔레메트리(telemetry)는 없습니다.

내가 발견한 것: 실제 엔지니어링 프로젝트에서 Claude Code를 사용한 243개 세션 이후의 수치:

세션 및 요청 (Sessions & Requests)

토큰 (전체적인 관점) (Tokens (The Big Picture))

캐시 효율성 (Cache efficiency): 캐싱 가능한 토큰의 96.7%가 캐싱되었습니다.

비용 분석: 돈이 어디로 가는가 (Cost Breakdown: Where Your Money Goes)

충격적인 사실: API 비용의 68%는 도구 실행 결과(tool execution outputs)를 컨텍스트 윈도우(context window)에 다시 주입하는 과정에서 발생합니다. git diff, ls -la, 전체 파일 읽기(full file reads), 그리고 bash 실행 로그(bash execution logs)의 가공되지 않은 출력값들이 지속적인 비용 동인(cost drivers)이 됩니다.

도구 사용: Claude Code가 실제로 하는 일 (Tool Usage: What Claude Code Actually Does)

Claude Code는 기본적으로 파일 리더(file reader)이자 셸 실행기(shell executor)입니다. 모든 도구 결과는 이후의 모든 턴에서 당신이 비용을 지불해야 하는 입력 토큰(input tokens)이 됩니다.

캐시 문제: 유휴 시간의 숨겨진 비용 (The Cache Problem: The Hidden Cost of Idle Gaps)
Claude Code는 5분간 유지되는 휘발성 프롬프트 캐싱(ephemeral prompt caching)에 의존합니다. 활발하게 코딩하는 동안에는 96.7%의 캐시 히트율(cache hit rate)이 매우 훌륭해 보이지만, 짧은 커피 휴식을 취하거나 잠깐의 Zoom 회의에 참석하면 5분간의 캐시가 만료됩니다. 내 데이터셋에서는 5분에서 60분 사이의 유휴 시간(idle gaps)이 147번 발견되었습니다.

이러한 공백이 손해를 끼치는 이유는 다음과 같습니다. Anthropic 모델의 경우, 프롬프트 캐시(prompt cache)에 쓰는 비용은 기본 입력 토큰 가격의 1.25배인 반면, 따뜻한 캐시(warm cache)에서 읽는 비용은 기본 가격의 0.10배에 불과합니다 (따뜻한 히트(warm hit)와 차가운 쓰기(cold write) 사이에는 12.5배의 비용 배수 차이가 있습니다!). 다른 제공업체의 경우, 캐시 쓰기 페널티(cache write penalty)는 이보다 훨씬 더 높을 수 있습니다.

간격(gap)이 발생할 때마다 다음 프롬프트는 콜드 캐시(cold cache)를 타격하게 되며, 이로 인해 API는 전체 컨텍스트 접두사(context prefix)를 다시 인덱싱하고 재작성해야만 했습니다. (참고: 이제 여러분의 커피 휴식 시간이 API 토큰 비용으로 실제로 얼마나 지불되는지 정확히 알게 되셨을 겁니다...)

간단한 현실 점검: 운영 환경에서의 Haiku vs. Opus
이 데이터셋의 지표 기준선(metric baseline) 대부분은 경량 모델(Haiku 및 DeepSeek 등)을 사용한 개인 사이드 프로젝트에서 수집되었습니다. 그렇기에 243개 세션의 총비용이 단 31.45달러에 불과했던 것입니다. 하지만 직장에서 Claude 4.6/4.8 Opus 및 더 발전된 모델들을 사용하여 동일한 프록시 설정을 테스트한 결과, 수치만 훨씬 더 클 뿐 정확히 동일한 구조적 패턴이 드러났습니다. 깊은 컨텍스트 윈도우(context window)를 사용하는 장기적인 엔터프라이즈 작업 세션에서는, 유휴 간격(idle gap) 이후 단 한 번의 콜드 캐시 새로고침(cold cache refresh)이 단일 요청에 3.00달러 이상을 소모했습니다. 컨텍스트 윈도우가 200K+ 토큰을 향해 커짐에 따라, 플래그십 모델에서 발생하는 이 조용한 5분간의 캐시 만료는 진정으로 고통스러운 문제가 됩니다.

대시보드(The Dashboard)
세션을 캡처한 후 http://localhost:3030/ui 를 여세요:

• Main 탭: 요청 횟수, 총비용, 시간에 따른 컨텍스트 윈도우 확장, 유휴 간격 분포.
• Tools 탭: 도구 호출(tool call)당 토큰 수, 에러율, 반복적인 파일 읽기(3회 이상), 비효율적인 읽기-검색-읽기(read-search-read) 루프.
• Search 탭: 캡처된 모든 대화에 대한 전체 텍스트 검색.

관측 가능성(Observability)에서 에이전트 구축으로: stackpilot
Claude Code의 243개 세션을 프로파일링(profiling)한 결과, 터미널 에이전트가 토큰을 낭비하는 방식에서 일관되고 반복적인 패턴이 발견되었습니다: 중복된 파일 읽기, 끝이 없는 도구 루프(tool loops), 그리고 불안정한 컨텍스트 구조입니다. 이러한 추적 데이터(trace data)는 ai-agent-profiler의 텔레메트리(telemetry) 통찰력을 기반으로 설계된 커스텀 작업 오케스트레이터(task orchestrator)인 stackpilot로 직접 이어졌습니다:

• 다단계 전략적 계획: 중복된 파일 읽기를 제거하기 위해 단계들이 순차적으로 실행됩니다 (읽기 → 분석 → 계획 → 실행 → 검증).
• 최소한의 컨텍스트 노이즈: 구조화된 스키마(structured schemas)와 필터링된 도구 출력을 사용하여 컨텍스트를 타이트하게 유지합니다.

결정론적 복구 (Deterministic recovery): 작업이 실패했을 때, 단순히 실패한 동일한 도구 호출 (tool call)을 맹목적으로 다시 실행하는 대신 실행 전략을 변경합니다. 캐시 최적화 구조 (Cache-optimized structure): 안정적인 프롬프트 서문 (prompt preambles)을 유지하며, 프롬프트 캐시 키 (prompt cache keys)가 깨지지 않도록 도구 출력 (tool outputs)을 구조화합니다. 링크 및 코드 두 프로젝트 모두 MIT 라이선스 하에 오픈 소스로 공개되어 있습니다: ai-agent-profiler (GitHub): github.com/rguiu/ai-agent-profiler ai-agent-profiler (라이브 데모): rguiu.github.io/ai-agent-profiler stackpilot (GitHub): github.com/rguiu/stackpilot 프록시 내부 구조, NDJSON 트레이스 파싱 (trace parsing), 또는 컨텍스트 텔레메트리 (context telemetry)에 대해 궁금한 점이 있다면 댓글로 언제든 질문해 주세요! /u/Muttawakkil 제출 [link] [comments]