Claude Code · Token Optimization Audit
공식 메커니즘 · RTK · 커뮤니티 발견을 전수 조사하고, icheolhui 의 실제 설정(스킬 54개·CLAUDE.md 10KB·메모리·rules)을 실측해 적용 가능한 액션으로 정리했습니다.
/clear·/compact·subagent) ③ 모델 라우팅(Haiku 입력비 ≈ Opus의 1/5).rtk read 래퍼 라우팅 덕(passive hook 기준 일반론 10–30% 상회). 단 지금 hook 이 빠져(No hook installed) 신규 명령은 fallback -0%, 버전도 0.34.3→0.42.3 뒤처짐 → rtk init -g + 업그레이드 필요.rtk init -g)+업그레이드 · CLAUDE.md 10KB 다이어트 · 스킬 54개 중 상시 미사용분 skillOverrides:off · dynamic-workflow 중복 제거. claudeMdExcludes·token-efficient tools 는 이미 적용 ✓.일반론보다 먼저, 실제 파일을 측정한 결과입니다. 매 턴/매 세션 로드되는 상수 비용이 최우선 타깃입니다.
| 항목 | 현황 | 판정 | 액션 |
|---|---|---|---|
| CLAUDE.md (10,069B) | DB 마이그레이션 인시던트 히스토리 등 장문 규칙이 본문에 상주. 매 턴 로드. | 과대 | 인시던트 서사는 docs/ 로 이관, 본문엔 한 줄 규칙 + 포인터만. 10KB→3–4KB 목표. |
| 스킬 54개 | 설명이 매 세션 시스템 리마인더로 주입. 8개는 이미 skillOverrides:off. | 누적 | 상시 미사용 스킬(예 insta·code2·zed2·gpt-image-2·nano-banana2)을 프로젝트 skillOverrides:off. 2026 업데이트로 설명 250자 cap 적용됨. |
dynamic-workflow | 글로벌+프로젝트 양쪽 등록 → 스킬 목록에 2번 노출(설명 582B ×2). | 중복 | 한쪽만 유지(프로젝트 버전 우선), 다른 쪽 제거. |
| claudeMdExcludes | CONTRIBUTING.md·frontend-design.md(32KB)·CLAUDE.local.md 차단. | 완료 | 유지. 레포 실측 ~75% 베이스 절감 효과. |
| 자동로드 rules | backend-architecture(2KB)+frontend-architecture(2.5KB) 매 턴. | 허용 | CI/런타임 버그 방지용 — 유지. copywriting-ux.md(5KB)는 자동로드 아님 ✓. |
| 메모리 | 인덱스(MEMORY.md 1KB)만 매 세션, 개별 파일은 recall 시에만. 대부분 활성/최근. | 양호 | 거의 손댈 것 없음. masked-email(미해결)·reportportal(오늘 갱신)은 유지. 정리할 stale 거의 없음. |
| RTK | 0.34.3 설치, 누적 13.4M 절약(63.1%). 단 rtk gain 이 "No hook installed" 경고 — 현재 자동 rewrite 비활성, 최근 로그에 fallback … -0% 다수. | 미동작 | rtk init -g 로 hook 재설치 + 0.34.3→0.42.3 업그레이드. 상세 §2.5. |
요점: "메모리 제거" 의 실익은 적다(인덱스만 로드, 대부분 활성). 진짜 레버는 CLAUDE.md 다이어트 + 스킬 목록 정리다. 둘 다 매 세션/매 턴 상수 비용이라 일회 작업으로 영구 절감된다.
| 방법 | 무엇을 | 절약폭 | 적용법 | 주의 / Trade-off |
|---|---|---|---|---|
/clear | 대화 히스토리 완전 리셋 | 스레드 누적분 전부 회수 | 무관한 작업 전환 시 | 맥락 전부 소실 — 같은 작업 중 금지 |
/compact | 대화를 구조화 요약으로 치환 | 누적 메시지 대폭 축소 | 60%에서 선제 실행. /compact focus on X | Lossy — 95%에서 하면 요약 품질 저하 |
| microcompact | 오래된 tool result 내용만 비움(구조 유지, 모델 호출 X) | tool result 누적분 회수 | 자동 | 자동이라 제어 약함 |
| prompt caching | system·CLAUDE.md·툴정의 캐시 재사용 | Opus 100턴 입력비 $50–100→$10–19 | 기본 ON. ENABLE_PROMPT_CACHING_1H=1 로 TTL 5분→1h | 무효화 위계 tools→system→CLAUDE.md/skills→messages. 세션 중 모델 전환·MCP 추가 = 캐시 통째 무효화 → 그 턴 5x |
| CLAUDE.md 다이어트 | 매 턴 상수 비용 파일 | 저자 주장 최대 ~92% 컨텍스트↓ | <500토큰 목표, 규칙+포인터만 | 과도히 줄이면 관습 못 따름. 편집 시 캐시 무효화 |
claudeMdExcludes | 자동로드 추가 MD 제외 | 본 레포 실측 베이스 ~75%↓ (+14.5K 규칙 로드시) | picomatch 절대경로 "**/CONTRIBUTING.md" | 글로벌 아님 — 프로젝트별 |
| token-efficient tool use | 툴콜 직렬화 효율화 | 출력 평균 14%, 최대 70%↓ | Claude 4+ 기본 내장(헤더 불필요) | 4+엔 헤더 무효과(이미 적용) |
| 모델 라우팅 | 난이도별 Opus/Sonnet/Haiku | Haiku 입력비 ≈ Opus 1/5 | Sonnet=일상, Haiku=기계작업, Opus=난도↑ | Haiku는 판단형서 "틀린 답을 빨리". 애매하면 Sonnet |
| subagent 격리 | verbose 탐색을 별도 컨텍스트로 | 메인 클러터 회수(가변) | 대량 읽기·분석 위임 | 자동으로 싸지 않음 — 기동 오버헤드. 짧은 작업엔 낭비 |
| MCP / 툴 정의 | 스키마가 매 요청 상주 | 서버당 1.5–4K, 다수면 세션 10–20K 무음 | 미사용 MCP 비활성. ENABLE_TOOL_SEARCH(deferred) 50–70K 회수 | MCP 변경 = 캐시 무효화 |
CLI 프록시. dev 명령 출력을 모델 진입 전 압축하는 단일 Rust 바이너리(API키·텔레메트리 없음). Apache 2.0.
| 항목 | 내용 |
|---|---|
| 연동 | rtk init -g → PreToolUse hook → git status 가 rtk git status 로 자동 rewrite |
| 공식 주장 | cargo test 91.8% · git status 80.8% · find 78.3% · grep 49.5% (편향 벤치) |
| 핵심 한계 | 네이티브 Read/Grep/Glob 은 hook 우회 → RTK 미적용. 효과는 에이전트가 Bash 로 탐색하는 비율에 비례 |
| 정직 추정 | 광고 60–90% 는 find/ls 편향. 혼합 워크로드 10–30%. 비용 지배 영역(Read·코드 생성)은 미커버 |
| 주의 | 이미 짧은 출력(git status)은 오히려 inflate 가능. Windows 네이티브는 auto-rewrite 없음 → WSL 권장 |
| 대안 | Caveman(출력측 축소) · Context-mode MCP(툴출력 샌드박스 인덱싱) |
일반론의 "10–30%" 는 hook 수동·passive 기준이다. 내 실측은 63.1% — rtk read/grep/find 래퍼로 적극 라우팅하기 때문(특히 rtk read 가 전체 절약의 68% 차지). 단 현재 hook 이 빠져 신규 명령은 절약이 안 되고 있다.
| # | 명령 | 횟수 | 절약 | 평균% | 해석 |
|---|---|---|---|---|---|
| 1 | rtk read | 644 | 9.2M | 20.5% | per-call 은 작지만 전체 절약의 68% — read 를 rtk 로 라우팅하는 게 최대 레버 |
| 2 | rtk grep | 813 | 354.8K | 29.7% | 고빈도 누적 |
| 3 | rtk find | 258 | 120.5K | 69.2% | 탐색 압축 효율 높음 |
| 4 | playwright test | 10 | 533.5K | ~100% | 장문 테스트 출력 — 저빈도·초고효율 |
| 5 | lint eslint / docker compose logs / ps aux | — | ~490K | 98–100% | 장문 로그류 — 래핑 시 거의 전량 압축 |
정정: 이전 추정 "RTK 가 네이티브 Read/Grep/Glob 미커버, 혼합 10–30%" 는 passive hook 기준. 셸 rtk read/grep/find 로 능동 라우팅하면 실측처럼 60%+ 도달. 단 지금은 hook 이 빠져 신규 세션에서 자동 적용 안 됨 → 아래 액션 참고.
| 도구 | 설치됨 | 최신 | 판정 |
|---|---|---|---|
| Claude Code | 2.1.170 | 2.1.170 | 최신 ✓ |
| RTK | 0.34.3 | 0.42.3 | 8 마이너 뒤처짐 — 업그레이드 |
| RTK hook | 미설치 | — | rtk init -g 필요 |
| wrangler | 4.93.0 | 4.99.0 | 선택적 |
| 팁 | 적용법 | Trade-off |
|---|---|---|
| 파일 읽기 offset/limit | 큰 파일 범위 지정, 특정 파일 지목(대부분 2–3파일) | 범위 잘못 잡으면 재읽기 |
| CLI > MCP | 셸 10줄(≈10토큰) vs MCP JSON(최대 100x) | 출력 비구조화·수동 파싱 |
.claudeignore | 거대·무용 파일 읽기 차단(.gitignore 문법) | 필요 파일 잘못 넣으면 못 읽음 |
| 세션 분할 (1토픽=1채팅) | 무관 맥락 누적 제거 | 맥락 수동 재구성 |
| plan mode / "코드 말고 계획만" | 영어 계획 수정은 싸고 깨진 코드 수정은 비쌈 | 단계 추가 |
| thinking 예산 cap | /effort low 또는 MAX_THINKING_TOKENS=8000 | 다단계 분해엔 thinking 필요 |
| 측정 | /cost · /context · claude-hud 플러그인 | — |
| terse 출력 강제 | CLAUDE.md drop-in 으로 verbosity↓ | 가독성 trade |
| 기능 | 내용 |
|---|---|
| Read 툴 compact 포맷 | line-number 압축 + 변경없는 재read 중복제거 |
| @mention 오버헤드 감소 | raw string 콘텐츠 JSON-escape 안 함 |
| skill 설명 250자 cap | /skills 목록 설명 길이 제한 |
ENABLE_TOOL_SEARCH | MCP/툴 스키마 사용 시점까지 지연 → 헤비셋업 50–70K 회수 |
ENABLE_PROMPT_CACHING_1H | 캐시 TTL 5분→1h (대형 코드베이스·장세션 유리) |
| Claude 4+ 토큰효율 툴 기본화 | 헤더 불필요, 출력 14–70%↓ |
| hooks 플랫폼화 (2026.03) | 21 lifecycle event·4 handler·async·JSON 구조출력 → 출력압축 자동화 |
docs/db-migrations.md 로 이관하고 본문엔 "절차 3줄 + 포인터" 만 남김. 매 턴 절감. git 추적이라 안전·되돌리기 쉬움..claude/settings.local.json 의 skillOverrides 에 insta·code2·zed2·gpt-image-2·nano-banana2 등 이 프로젝트와 무관한 스킬을 "off" 추가. 매 세션 설명 주입 절감.dynamic-workflow 중복 제거/clear · /compact 습관화/clear, 컨텍스트 60%에서 /compact. 무료·최대 레버.rtk gain 이 "No hook installed" 경고 — 신규 명령이 fallback(-0%)으로 빠지는 중. rtk init -g 로 hook 재설치하고 0.34.3→0.42.3 업그레이드(cargo install --git … rtk 또는 brew upgrade rtk). 누적 63.1% 실적을 신규 세션에도 자동 적용.claudeMdExcludes(32KB frontend-design 차단) · token-efficient tools(Claude 4+ 기본) · 메모리 인덱스 구조 · Claude Code 2.1.170 최신.
검증된 사실 — microcompact 동작, token-efficient tool use 14–70%·Claude 4+ 기본화, 캐시 무효화 위계, Read 중복제거, skill 250자 cap, RTK 가 네이티브 Read/Grep/Glob 미커버(저자 명시)·Apache 2.0.
단일 블로그 추정치 — CLAUDE.md "~92%", "$50–100→$10–19", Haiku "5x", MCP "10–20K". 방향성은 신뢰하되 정확한 % 는 출처별 상이.
마케팅·일화 — RTK "60–90%"(편향 벤치), "138M 토큰 절감" 개인사례 → 혼합 워크로드 10–30% 로 할인 필요.