누적 토큰에서 회당 평균으로 — 메트릭의 정의가 기능보다 중요했던 순간

기능을 만들면 가치가 따라온다는 착각

소프트웨어 만드는 사람이 흔히 빠지는 함정이 하나 있다. "기능을 추가하면 가치가 자동으로 따라온다" 는 가정. 직관적이지만 틀렸다. 같은 데이터를 다른 메트릭으로 보여주는 것만으로도 사용자 인지가 완전히 바뀐다는 걸 짧은 사이드 프로젝트에서 직접 경험했다.

이 글은 Claude Code Skills Panel 의 토큰 추적 기능을 두 번 만들었던 이야기다. 한 번은 v0.40 에서, 한 번은 v0.44.6 에서. 데이터 수집 코드는 두 번째에도 거의 동일했다. 라벨 한 줄만 바뀌었다. 그런데 첫 번째는 거의 무용지물이었고 두 번째는 사용자 질문에 정확히 답했다.

v0.40 — 일단 만들어보자

토큰 추적 기능은 "있으면 좋을 것 같다" 정도의 막연한 욕구에서 출발했다. Claude Code 사용자가 자기 슬래시 커맨드 중 어떤 게 토큰을 많이 쓰는지 궁금하지 않을까? 답을 위해서가 아니라 답할 수 있을 것 같아서 만들었다.

구현은 정직했다. ~/.claude/projects/*.jsonl 의 모든 라인을 incremental 파싱해서, assistant 라인의 message.usage 필드를 모은다. 사용자 라인의 <command-name> 마커와 uuid 체인으로 매칭해서 슬래시 커맨드별로 귀속.

결과는 각 카드 라벨에 누적 토큰을 표시하는 형태였다.

┌──────────────────────┐
│  /full-flow          │
│  203M tokens         │   ← 누적
│  플러그인: ...        │
└──────────────────────┘

만들고 나서 며칠 동안 보면서 이상한 느낌이 들었다. 이게 어떤 정보를 주는 거지? 사용자에게 무슨 결정을 도와주는 거지?

사용자 입장에서 다시 보기

/full-flow 203M tokens 라는 라벨을 마주한 가상의 사용자가 무슨 생각을 할까 시뮬레이션해봤다.

"오, /full-flow 가 무거운가 보네."
"근데 내가 그걸 얼마나 자주 부르더라?"
"많이 부르니까 누적이 많은 거 아닌가?"
"그러면 한 번에 가장 무거운 건 뭐지?"
"...이 라벨로는 답을 못 하네."

진짜 질문은 "어떤 스킬이 한 번 부를 때 가장 비싼가" 였다. 그런데 누적 토큰 라벨은 그 질문에 답하지 못했다. 많이 부른 스킬이 자연스럽게 누적으로 무겁게 보일 뿐이었다.

이 깨달음이 오기까지 며칠 걸렸다. 부끄럽지만 사실이다. 기능을 만들고 나면 그 기능이 정확한 답을 주는지 검증하는 단계를 자주 건너뛴다.

v0.44.6 — 메트릭의 재정의

수정은 라벨 한 줄이었다.

┌──────────────────────┐
│  /full-flow          │
│  22.6M tok/run       │   ← 회당 평균
│  플러그인: ...        │
└──────────────────────┘

계산식: 누적 토큰 ÷ 호출 횟수. 호출 횟수는 <command-name> 마커 카운트로 이미 가지고 있던 숫자다. 데이터 수집 코드는 한 줄도 바뀌지 않았다.

같은 데이터를 다른 메트릭으로 보여주는 것뿐인데 카드를 보는 경험이 완전히 달라졌다.

변경 전:
  /full-flow         203M tokens   ← "많다, 그래서?"
  /commit-prepare     45M tokens   ← "이것도 많다"
  /security-review    12M tokens

변경 후:
  /full-flow          22.6M tok/run (호출 9회)
  /commit-prepare      1.2M tok/run (호출 38회)
  /security-review     3.0M tok/run (호출 4회)

이제 카드를 보면 즉시 알 수 있다. "/full-flow 는 한 번 부를 때 22M 이라 정말 무거운 작업이구나. /commit-prepare 는 자주 부르지만 한 번이 가벼워서 누적이 큰 거였구나."

정렬도 의미를 가졌다. 회당 평균 내림차순으로 정렬하면 위에서부터 "가장 비싼 스킬" 이 나온다. 주간 리포트의 Top 5 도 회당 평균 기준. 툴팁의 보조 정보도 동일.

같은 데이터, 다른 질문

이 경험에서 명확해진 게 있다. 메트릭은 데이터가 아니다. 메트릭은 질문이다.

누적 토큰 → "총량은 얼마인가?"
호출 횟수 → "얼마나 자주 쓰는가?"
회당 평균 → "한 번 부를 때 무게는?"

같은 raw data 에서 여러 질문을 만들 수 있고, 각 질문에 답하는 메트릭은 같은 카드에서도 완전히 다른 인지를 만든다. v0.40 의 라벨은 "총량" 질문에 답했지만 사용자가 원하던 건 "단가" 였다.

일반화 — 다음에는 어떻게 다르게 할까

이 경험 이후 새 기능을 설계할 때 의식적으로 거치는 단계가 생겼다.

1. 사용자가 진짜 답을 얻고 싶은 질문은 무엇인가?

기능 자체를 정의하기 전에 질문을 먼저 정의한다. "토큰 추적 기능" 이 아니라 "한 번 부를 때 가장 비싼 스킬은 무엇인가" 같은 식. 질문이 명확해지면 메트릭이 따라 나온다.

2. 이 메트릭이 그 질문에 정확히 답하는가?

라벨을 결정하기 전에 가상의 사용자를 한 번 시뮬레이션한다. 이 라벨을 처음 보는 사람이 5초 안에 답을 얻을 수 있는가. 아니면 추가 사고가 필요한가. v0.40 라벨은 사고가 필요했다. v0.44.6 라벨은 5초면 충분했다.

3. 데이터 수집 코드 vs 메트릭 정의를 분리한다

수집은 한 번 잘 해두면 여러 메트릭을 파생할 수 있다. v0.40 → v0.44.6 가 가능했던 건 수집 코드가 충분히 raw 했기 때문이었다. 수집 단계에서 미리 가공해두면 나중에 메트릭을 바꾸기 어렵다. 메트릭은 표시 직전에 결정한다.

AI 가 자동 생성하는 메트릭의 함정

여담이지만 LLM 으로 자동 생성된 대시보드나 분석 도구를 보면 비슷한 함정을 자주 본다.

"이 카드는 평균 응답 시간을 표시합니다. 어제 대비 +12ms 입니다."

이런 라벨은 멋있어 보이지만 사용자의 진짜 질문에 답하지 않는다. 진짜 질문은 "이게 우리 SLO 를 깨뜨리는가" 또는 "어떤 endpoint 가 느린가" 같은 것이다. 평균은 모든 outlier 를 숨긴다. p95 / p99 가 답에 더 가까울 수 있다.

기능보다 메트릭의 정의가 중요하다는 원칙은 AI 협업 시대에 더 중요해진다. 코드는 빠르게 생성되지만, 그 코드가 답하는 질문은 사람이 정의해야 한다. AI 가 만든 라벨을 그대로 두지 말고, 가상의 사용자가 그 라벨을 보고 어떤 결정을 할 수 있을지 항상 검증해야 한다.

결론

Claude Code Skills Panel v0.44.6 의 한 줄 라벨 변경은 코드량으로 측정 불가능하다. 그러나 사용자가 카드를 보고 얻는 가치는 그 한 줄로 결정됐다. v0.40 의 토큰 추적은 작동했지만 답하지 않았다. v0.44.6 의 토큰 추적은 답했다.

요약하면 이렇다.

기능을 만든 시점 ≠ 가치를 만든 시점
메트릭은 데이터가 아니라 질문이다
5초 안에 답할 수 있는 라벨인지 항상 검증한다
수집과 표시를 분리하면 메트릭 재정의가 자유롭다

도구 claude-skills-panel 의 회고지만, 모든 데이터 시각화와 대시보드 설계에 적용되는 원칙이라고 생각한다. 다음 기능을 만들기 전에 "사용자가 진짜 답을 얻고 싶은 질문이 무엇인가" 부터 적어보는 습관을 시도해보길 권한다.