토큰이 어디로 가는지에 대한 당신의 직관은 아마 틀렸을 것입니다

Nothing Broke. It Just Wasn't There.에서 개인 AI 코딩 설정에 대한 감사를 진행한 결과, 토큰 낭비 문제는 이미 해결되어 있었습니다. 이는 어떤 습관이 비용이 많이 들 것 같다고 추론해서가 아니라, 실제 60일간의 코퍼스 (Corpus)를 측정하고 네 가지 초기 가설 중 세 가지가 틀렸음을 발견함으로써 이루어졌습니다.

이 워크숍은 그 측정 과정의 실습적인 절반을 담당합니다. 만약 companion /doctor 워크숍을 수행했다면, 이 워크숍은 다른 측면을 다룹니다. 즉, 기존의 하네스 (Harness)가 아니라 모델과 나누는 모든 대화 내부에 축적되는 것을 다룹니다.

시작하기 전에 명확히 해둘 아이디어 하나가 있습니다: 에이전트 API (Agent API)는 상태가 없습니다 (Stateless). 모든 개별 도구 호출 (Tool call)은 지금까지의 전체 대화 내용을 처음부터 다시 전송합니다. 한 번 말했다고 해서 공짜인 것은 없습니다. 긴 세션 초반에 등장한 토큰은 그 이후의 모든 턴 (Turn)에서 다시 비용을 지불하게 됩니다. 이것이 바로 특정 비싼 행동이 아니라, 세션 길이 (Session length)가 실제 비용을 유발하는 주된 요인이 되는 이유입니다.

연습 1: 기계적인 절반을 설치하기

5분

이것이 중요한 이유

여기서 언급하는 네 가지 레버 (Lever) 중 두 가지는 일단 설치하고 나면 전혀 신경 쓸 필요가 없습니다. 하나는 특정 낭비를 자동으로 차단하는 훅 (Hook)이고, 다른 하나는 묻지 않아도 컨텍스트 사용량 (Context usage)을 보여주는 상태 표시줄 (Statusline)입니다. 이것들을 먼저 갖춰 놓으세요. 아무것도 측정하기 전부터 즉각적인 효과를 내기 시작할 것입니다.

구조

두 가지 모두 /doctor와 동일한 공개 리포지토리 (Repo)에 있습니다: github.com/nino-chavez/agentic-ways-of-working.

hooks/read-guard.py — 파일 읽기에 대한 PreToolUse 훅 (hook)입니다. 이 훅은 두 가지 특정 패턴을 한 번 거부하며, 동일한 응답 내에서 수정 방법을 제공합니다: 첫째, 너무 큰 이미지 읽기 (긴 쪽이 1400px을 초과하면 1000px 복사본을 대신 제공), 둘째, 지난 10분 동안 변경되지 않은 파일의 재읽기 (이미 컨텍스트 (context)에 있는 내용을 인용하라는 알림을 제공)입니다. 즉각적인 재시도는 항상 성공합니다. 이는 무의식적인 행동에 대한 마찰 (friction)을 만드는 것이지, 벽을 세우는 것이 아닙니다.

statusline.py — 터미널에 모델 | 컨텍스트 토큰 (50%/80%에서 색상 구분) | 현재 작업 디렉토리 (cwd)를 표시합니다. 이를 통해 세션이 합리적인 수준을 넘어 비대해지는 것을 세 번의 도구 호출 (tool call) 후에 발견하는 것이 아니라, 즉시 확인할 수 있습니다.

직접 해보기

이미 /doctor 워크숍을 위해 저장소 (repo)를 클론 (clone)했다면 모든 준비가 끝났습니다. 설치 프로그램을 실행하여 나머지를 연결하기만 하면 됩니다:

전체 설치 (Full install)

훅 (hooks), 상태 표시줄 (statusline), 명령어를 한 번에 연결합니다 — 다시 실행해도 안전합니다.

cd ~/agentic-ways-of-working   # 또는 클론한 위치
./install.sh

처음부터 새로 시작하려면:

신규 클론 + 설치 (Fresh clone + install)

한 번의 명령어로 모든 것을 연결합니다.

git clone https://github.com/nino-chavez/agentic-ways-of-working.git ~/agentic-ways-of-working
cd ~/agentic-ways-of-working
./install.sh

설치 프로그램은 멱등성 (idempotent)을 가집니다. 먼저 settings.json을 백업하고, 이미 존재하는 훅 등록은 추가하지 않으며, 이미 구성된 상태 표시줄을 절대 덮어쓰지 않습니다.

체크포인트 (Checkpoint)

Claude Code 세션을 재시작하세요. 터미널 하단에 모델, 현재 컨텍스트 사용량, 작업 디렉토리를 보여주는 상태 표시줄이 나타나야 합니다. 지난 몇 분 동안 건드리지 않은 파일을 다시 읽은 다음, 파일 내용이 변하지 않은 상태에서 즉시 똑같은 파일을 다시 읽어보세요. 두 번째 읽기는 알림과 함께 한 번 거부되어야 하며, 바로 뒤의 재시도는 문제없이 통과해야 합니다. 그것이 설계된 대로 훅 (hook)이 작동하는 방식입니다.

연습 2: 추측하지 말고 측정하라

5분 소요

이것이 중요한 이유

어떤 도구 호출 (tool call)이 비용이 많이 드는지에 대한 직관은 일상적으로 틀립니다. 이것은 단순히 조심스럽게 말하는 것이 아니라, 2,335개의 파일과 529개의 세션으로 구성된 실제 코퍼스 (corpus)를 대상으로 실행하여 얻은 실제 결과입니다. 그 과정에서 시작 단계의 가설 네 개 중 세 개가 틀렸습니다. 당신의 설정은 그 사례와 다를 것입니다. 당신의 환경에서 실제로 어떤 일이 일어나고 있는지 알 수 있는 유일한 방법은, 무엇이 무겁게 느껴지는지에 대해 추론하는 것이 아니라 직접 측정을 실행하는 것입니다.

구조

tools/token-audit.py는 ~/.claude/projects/**/*.jsonl 하위의 모든 세션 로그를 읽고, 이를 스트리밍 처리하며 (수 기가바이트 규모의 코퍼스도 1~2분 내에 완료됩니다), 토큰이 당신의 추측이 아닌 실제로 어디에 사용되었는지를 보고합니다.

python3 tools/token-audit.py [--days 60] [--projects-dir ~/.claude/projects] [--top 20]

--days는 조회 기간 (기본값 60 — 도구 사용이 최근이라면 더 적은 값을 사용하세요)을 제어하며, --projects-dir은 Claude Code 데이터가 기본 위치에 있지 않은 경우 다른 곳을 지정할 수 있게 해줍니다. --top은 카테고리별로 상위 위반 항목을 몇 개까지 나열할지 제어합니다.

직접 해보기

당신의 기록을 대상으로 실행해 보세요:

감사 (audit) 실행

Python 3 외의 의존성 없음

cd ~/agentic-ways-of-working
python3 tools/token-audit.py --days 60

Claude Code를 처음 사용하여 아직 60일 치의 기록이 없다면, 기간을 줄이세요: --days 14 또는 실제로 보유한 기간만큼 설정합니다. 짧은 기간이라도 무언가를 알려주기는 하지만, 결과가 안정적이지는 않을 것입니다.

체크포인트

도구 자체 문서에 나온 참조 숫자가 아니라, 당신의 세션에 특화된 몇 가지 명명된 지표와 숫자가 포함된 보고서가 보여야 합니다. 만약 보고서가 사실상 비어 있다면, --projects-dir이 Claude Code 세션 로그가 실제로 저장된 위치(기본값은 ~/.claude/projects)를 가리키고 있는지 확인하세요.

연습 3: 다섯 가지 숫자 읽기

6분 소요

이것이 중요한 이유

각 숫자가 당신에게 무엇을 하라고 말하는지 알기 전까지는 보고서가 유용하지 않습니다. 다섯 가지 지표가 전체 이야기를 담고 있습니다.

구조

Replay multiplier (재생 배수) — 캐시 읽기(cache reads) ÷ 기록된 토큰(tokens written). 이것이 가장 중요한 지표입니다. API는 상태를 유지하지 않으므로 (stateless), 페이로드의 실제 비용은 해당 페이로드의 크기에 세션 내에서 뒤따르는 모든 API 호출 횟수를 곱한 값입니다. 이로 인해 세션 비용은 턴(turn) 횟수에 따라 대략 이차 함수적(quadratic)으로 증가합니다. 참조 코퍼스(reference corpus)에서 이 수치는 41배로 측정되었습니다. 이 수치가 높다면, 해결책은 당신이 보내는 내용을 줄이는 것이 거의 아닙니다. 대신 세션을 짧게 유지하고, 탐색(exploration) 작업을 당신의 컨텍스트에 계속 쌓이는 대신 해당 컨텍스트가 소멸되는 서브에이전트(subagents)에게 위임하는 것이 해결책입니다.

Redundant re-read rate (중복 재읽기율) — 동일한 파일, 동일한 세션, 변경되지 않은 콘텐츠를 한 번 이상 읽는 경우입니다. 높은 재읽기율은 대개 긴 세션의 증상입니다. 압축(compaction)이 도구(tool)의 결과물을 떨어뜨리면, 에이전트는 잃어버린 내용을 다시 읽게 되고, 컨텍스트는 커지며, 다시 압축이 실행됩니다. 연습 1에서 설치한 read-guard 훅(hook)이 안전장치 역할을 하지만, 실제 해결책은 세션을 단축하는 것입니다.

Image reads (이미지 읽기) — 파일 크기가 아닌 픽셀 차원(pixel dimensions)에 따라 비용이 청구됩니다. 전체 해상도의 스크린샷은 동일한 콘텐츠를 크롭(crop)하고 크기를 조절한 복사본보다 몇 배 더 많은 비용이 들 수 있습니다. 참조 코퍼스에서 이미지는 전체 읽기 바이트의 78%를 차지했으며, 대부분은 디자인 루프(design-loop) 세션에서 수십 번 재읽기된 전체 페이지 캡처였습니다.

Cache-write ratio (캐시 쓰기 비율) — 캐시 쓰기(cache writes) ÷ 새로운 입력(fresh input). 쓰기 비용은 입력 가격의 약 1.25배이며, 캐시 TTL 만료(약 5분의 유휴 시간) 시점과 모든 서브에이전트 생성 시점에 발생합니다. 높은 비율은 대개 유휴 상태로 있다가 재개되는 비대한 세션을 의미합니다. 가벼운 재개(resume)가 일어날 때마다 전체 컨텍스트를 프리미엄 요율로 다시 쓰게 됩니다.

Per-model spread (모델별 분산) — 캐시는 모델별로 관리됩니다. 세션 중간에 모델을 전환하면, 전환한 모델에 대해 콜드 캐시(cold cache)가 시작됩니다.

직접 해보기

자신의 리포트로 돌아가세요. 먼저 리플레이 배수(replay multiplier)를 찾으세요. 대개 이것이 가장 큰 단일 숫자이며 시작하기에 가장 좋은 지점입니다. 그런 다음 중복 읽기 비율(redundant-read rate)과 이미지 읽기(image reads)를 확인하세요. 이 두 가지는 훅(hook)이 부분적으로 잡아낼 수 있는 요소들이므로, 연습 1(Exercise 1) 이후에도 이 수치들이 높게 유지된다면 특정 상황(훅이 설치되기 전의 오래된 기록인지, 아니면 현재도 여전히 발생하고 있는 패턴인지)을 시사합니다.

체크포인트 (Checkpoint)

이 페이지의 참조 숫자가 아니라, 본인의 리플레이 배수와 중복 읽기 비율을 구체적으로 적어보세요. 도구를 실행하기 전 예상했던 값과 비교하여 두 숫자 중 어느 하나라도 놀랍다면, 그것이 바로 추측하는 대신 측정하는 실제 이유입니다.

연습 4: 하나의 숫자를 하나의 변화로 바꾸기

4분 소요

이것이 중요한 이유

단 하나의 습관도 바꾸지 못하는 측정은 감사가 아니라 연구 연습에 불과합니다. 핵심은 리포트 그 자체가 아니라, 다음 세션에서 당신이 무엇을 다르게 행동하느냐에 있습니다.

구조

발견한 내용과 이를 실제로 해결할 방법을 매칭하세요:

당신의 차례

연습 3에서 발견한 가장 큰 숫자와 일치하는 '단 하나의' 행을 선택하세요. 다섯 개 모두가 아니라, 딱 하나입니다. 다음 세션부터 당신이 바꿀 구체적인 습관을 한 문장으로 적어보세요.

체크포인트 (Checkpoint)

당신의 한 가지 변화를 소리 내어 말하거나 글로 적으세요: 언제부터 무엇을 다르게 할 것인지 말입니다. 몇 주 후에 감사를 다시 실행하여 해당 숫자가 움직였는지 확인하세요. 만약 움직이지 않았다면, 해결 방법이 실제 원인과 일치하지 않은 것입니다. 연습 3으로 돌아가 숫자를 더 주의 깊게 다시 읽어보세요.

당신이 측정한 것

동일한 메커니즘의 서로 다른 절반씩을 다루는 네 가지 연습:

이것이 지향하는 방향 (Where This Is Heading)

상태 표시줄 (statusline)은 이 중 유일하게 실시간으로 작동하는 부분이며, 현재 진행 중인 세션에 대한 정보를 제공합니다. 그 외의 모든 것은 과거를 돌아보는 것입니다. token-audit.py는 지금 이 순간 일어나고 있는 일이 아니라, 이미 일어난 일을 알려줍니다.

/doctor 워크숍에서 해당 명령어를 다시 실행할 것을 권장하는 것과 마찬가지로, 몇 주 후에 다시 실행해 보세요. 단 한 번의 측정은 스냅샷(snapshot)일 뿐입니다. 실제로 당신의 토큰 비용을 변화시키는 것은, 두 번째 확인했을 때도 연습 4 (Exercise 4)에서 얻은 습관이 여전히 유효한지 여부입니다.