이미 API 호출을 통해 usage.input_tokens를 받아볼 수 있습니다. 하지만 여러분이 받을 수 없는 것은 JIRA-1234의 비용입니다. 이는 이틀 동안 세 차례에 걸쳐 진행된, 멀티 턴(multi-turn), 도구 호출(tool-calling), 캐시 집약적(cache-heavy) 에이전트 세션입니다.

이것이 바로 계측(instrumentation)의 공백이며, Claude Meter는 여러분이 실제로 작업하는 계층인 CLI/IDE 코딩 루프에서 이 공백을 메웁니다. 이 포스트는 엔지니어를 위한 버전으로, 452K 토큰 세션의 비용을 34센트로 만드는 비용 모델(cost model), 훅 아키텍처(hook architecture), 그리고 토큰 수학(token math)을 다룹니다.

정확하게 정의된 귀속의 공백 (The attribution gap)

이제 토큰 지출은 주요 항목(first-class line item)이 되었지만, 이에 대한 관측 가능성(observability)은 모델이 호출되는 방식에 따라 계층화되어 있습니다:

사각지대가 존재하는 이유는 구조적입니다. 에이전트 기반 코딩 세션에서 여러분은 API 상위에 위치합니다. 도구가 요청 루프를 소유하므로, 계측을 걸 수 있는 자연스러운 경계(seam)가 없습니다. 그리고 작업은 단일 요청이 아니라 하나의 궤적(trajectory)입니다:

   Prompt
     │
     ▼
...

모든 루프 반복은 누적된 컨텍스트(context)를 다시 전송하고, 도구 호출(tool calls)을 생성하며, 여러 개의 서로 다른 가격 클래스(price classes)에 걸쳐 토큰을 소모합니다. 이 궤적은 티켓(ticket)에 깔끔하게 매핑되지만, 토큰 스트림과 티켓을 연결하는 것은 아무것도 없습니다. 이 연결 고리를 만드는 것이 제품의 핵심입니다.

비용 모델: 토큰이 달러가 되는 방식

단순한 사고 모델인 비용 = 토큰 × 가격은 에이전트 세션의 경우 틀린 방식입니다. 왜냐하면 모든 토큰이 동일한 비율로 청구되지 않기 때문입니다. (적어도) 네 가지 가격 클래스가 존재합니다:

여기서 T_in, T_out, T_cw, T_cr은 각각 입력 (input), 출력 (output), 캐시 쓰기 (cache-write, 생성), 캐시 읽기 (cache-read) 토큰 수입니다. Sonnet급 모델의 경우 가격 벡터는 대략 다음과 같습니다:

마지막 행이 바로 측정 (metering)이 중요한 이유입니다. 긴 코딩 세션 동안 동일한 컨텍스트가 매 턴마다 다시 전송되므로, 프롬프트 캐싱 (prompt caching)이 없다면 입력 비용은 턴 수에 따라 대략 **이차 함수적 (quadratically)**으로 증가합니다. 즉, 1턴에서는 1개의 청크를 다시 보내고, 2턴에서는 2개를 다시 보내며, ..., N턴에서는 N개를 다시 보내게 됩니다:

N번의 턴마다 각각 Δ 토큰의 컨텍스트가 추가되는 경우입니다. 프롬프트 캐싱은 다시 전송되는 접두사 (prefix)를 캐시 읽기 (cache-read) 요율로 압축하여 가격을 10분의 1로 낮춰주므로, **캐시 히트 비율 (cache hit ratio)**이 세션 비용을 결정하는 지배적인 레버가 됩니다:

그리고 캐싱을 통한 **절감액 (savings)**은 정확히 정가로 지불하지 않은 차액(delta)과 같습니다:

일반적인 과금 대시보드는 하나의 혼합된 수치만을 보고합니다. 이 네 가지 클래스를 분리하여 보여주는 측정 도구는 특정 작업이 왜 저렴했는지 혹은 비쌌는지, 그리고 여러분의 컨텍스트 전략이 실제로 캐시에 적중하고 있는지를 알려줍니다. 아래에서 실제 실행을 통해 이 모든 것을 검증해 보겠습니다.

아키텍처: Stop hook, 상태 파일, 명령 (command)

Claude Meter는 마켓플레이스(marketplace)에서 설치하는 Claude Code 플러그인(JavaScript, Node ≥ 18)입니다. 혼동을 피하기 위해 명칭을 정리하자면: claude-meter는 **마켓플레이스/리포지토리(marketplace/repo)**이며, 설치하는 **플러그인(plugin)**은 session-manager이고, 이는 /session-manager:meter를 노출합니다. 세 가지 구성 요소는 다음과 같습니다:

 ┌──────────────────────────── Claude Code session ────────────────────────────┐
 │                                                                              │
 │   every turn ──► Stop hook (hooks.json)                                       │
...

1. Stop 훅 (hook) — hooks/hooks.json을 통해 등록되며, 매 턴(turn)이 끝날 때마다 실행됩니다. 로컬 트랜스크립트(transcript)를 읽어 네 가지 토큰 클래스(token classes)와 활동 카운터(activity counters)를 활성 세션(active session)에 누적합니다. 이것이 트래킹 설정이 필요 없는 이유입니다. 훅이 수집기(collector) 역할을 하며 이미 연결되어 있기 때문입니다.
2. 세션 상태 (Session state) — 실시간 집계 데이터는 .claude/sessions/active.json에 저장됩니다. end/clear 명령을 통해 .claude/sessions/name-id.json으로 아카이브(archive)되므로, 히스토리가 보존되고 쿼리(query)가 가능합니다.
3. 명령(Command) + 스킬(skill) — /session-manager:meter 슬래시 명령어를 사용하거나, 자연어 스킬(natural-language skill)을 통해 동일한 로직을 트리거할 수 있습니다.

가격(Pricing) 정보는 LiteLLM 모델 가격 목록에서 가져오며, 한 번 가져오면 24시간 동안 로컬에 캐시(cache)됩니다. 만약 가져오기가 차단되면(기업 방화벽 등), 하드코딩된 가격표로 대체됩니다. 이 과정에서 트래킹 기능은 점진적으로 저하될 뿐, 세션 데이터는 절대로 외부로 전송되지 않습니다. 위의 모든 과정은 로컬 트랜스크립트를 바탕으로 로컬에서 계산됩니다.

데이터 모델: 세션에 실제로 저장되는 것

아카이브된 세션은 사용자가 소유하는 일반 JSON 파일입니다. 블랙박스(black box)는 없으며, 외부로 유출되는 데이터도 없습니다. 보고서에 출력되는 모든 숫자는 사용자가 직접 검사할 수 있는 필드입니다:

[

스키마는 본질적으로 비용 모델 (cost-model) 입력값에 출처 (provenance)가 더해진 형태입니다:

{
  "label": "xyz",
  "inputTokens": 0,            // T_in
...

시작 시점에 gitBranch + gitCommit을 캡처하는 것은 세션을 단순히 라벨로 구분하는 것이 아니라, 커밋 앵커 (commit anchor)를 통해 비용을 할당함으로써 세션을 _당신의 레포지토리 역사 속 특정 순간에 진정으로 결합_시키는 디테일입니다.

계측기 읽기: 실제 사례

다음은 /session-manager:meter stat xyz로부터 수집된 실제 보고서입니다:

실제 수치를 모델에 대입하여 확인해 보겠습니다.

즉, 신규 입력 (fresh-input) 비용인 $3/M보다 4배 낮은 혼합 요율 (blended rate)을 보입니다. 이는 당신의 컨텍스트 전략 (context strategy)이 제 역할을 하고 있음을 알려주는 단일 스칼라 (scalar) 값입니다. 이것이 바로 청구서와 진단 도구의 차이입니다. 계측기는 단순히 작업이 저렴했다고 말하는 것이 아니라, 그것을 저렴하게 만든 메커니즘 (ρ ≈ 0.91)을 보여줍니다.

모드 및 작업 단위 생명주기 (work-unit lifecycle)

메뉴를 보려면 인자 없이 /session-manager:meter를 호출하거나, 모드를 직접 전달하십시오:

전형적인 루프:

/session-manager:meter start "JIRA-1234"   # 시작 (kickoff)
/session-manager:meter show                # 실시간 ρ 및 비용 확인
/session-manager:meter end                 # 최종 보고서
...

두 가지 설계 선택이 중요한 비중을 차지합니다:

• **resume + stats**는 작업 단위(work unit)를 지속 가능하게(durable) 만듭니다. 이틀에 걸쳐 세 번의 세션 동안 진행된 티켓이라도, 동일한 라벨을 공유하는 모든 실행에 대해 C_ticket = Σ C_session_i로 계산되어 하나의 수치로 합산됩니다.
• **token-breakdown**은 미터기(meter)를 프로파일러(profiler)로 변환합니다. 특정 작업이 예산을 사고(thinking) 토큰에 썼는지 아니면 도구(tool) 소모에 썼는지 아는 것은, 플레임 그래프(flame graph)가 CPU가 어디에 사용되었는지 알려주는 것과 마찬가지로 작업이 어떻게 구조화되었는지에 대한 실행 가능한 정보를 제공합니다.

정량화가 복리 효과를 내는 이유

측정은 행동을 변화시킵니다. 작업당 비용이 가시화되면, 가치는 두 가지 시간 척도에서 복리로 증가합니다.

단기적 관점 (Short term)

• 즉각적인 작업당 비용. end가 실행되는 즉시 해당 티켓에 대한 토큰, 비용(dollars), 실제 소요 시간(wall-clock)을 확인할 수 있습니다. 월간 인보이스를 기다릴 필요가 없습니다.

• 실시간 경로 수정. 세션 중간에 show를 사용하면 제어 불능 상태가 된 작업을 실행 중인 상태에서 포착할 수 있습니다. 만약

• 작업 클래스별 기준선 (Baselines per task class). 충분한 세션을 집계하여 버그 수정 트렌드가 X 토큰에서 나타나는지, 마이그레이션이 Y 토큰에서 나타나는지 확인하세요. 추측이 아닌 분포(distributions)로서의 추정치를 얻을 수 있습니다.

• 방어 가능한 ROI (Defensible ROI). 세션 비용(C_session)을 경과 시간과 결합하세요: "이 작업은 $C의 비용이 들었으며 H시간을 절약했습니다." 이것이 재무 부서가 실제로 원하는 문장입니다.

• 실질적인 최적화 목표 (Real optimization targets). 기여도 분석(Attribution) → 공격: 토큰 소모가 많은 작업 클래스를 식별하고, 프롬프트/컨텍스트 전략을 조정하여(ρ를 높임) 수치가 실제로 움직였는지 측정(measure) 하세요.

• 예측 (Forecasting). 작업 단위별 이력은 "다음 분기에 AI 지원 개발 비용이 얼마나 들 것인가?"라는 질문을 귀사의 티켓(tickets)에 기반한 투영(projection)으로 바꿔줍니다.

• 문화적 변화 (Cultural shift). 엔지니어가 계량기를 볼 수 있게 되면, 가시적인 지연 시간(latency) 대시보드가 팀의 성능 인식을 높였던 것처럼 토큰 효율성도 작업 범위(scope)에 포함됩니다.

측정할 수 없는 것은 최적화할 수 없습니다. Claude Meter의 기여는 좁지만 근본적입니다. 이는 토큰 비용이 보이지 않았던 유일한 곳인 CLI/IDE 코딩 세션에서 토큰 비용을 측정 가능하게 만들며, 그 측정값을 조직의 나머지 구성원들이 이미 사용 중인 작업 단위(unit of work)에 고정시킵니다.

사용해 보기

Claude Meter는 MIT 라이선스 하에 오픈 소스로 제공됩니다. 다음 티켓의 이름을 딴 세션을 시작하고, 작업이 끝나면 종료한 뒤 영수증을 확인하세요.

리포지토리(Repo), 설치 안내 및 문서 → github.com/ankan4445/claude-meter

이 내용이 유용했다면 ❤️ 또는 🦄를 눌러주세요. 작업별 계량(per-task metering)이 여러분의 작업 범위 산정 방식을 어떻게 바꾸는지 듣고 싶습니다.