클로드 코드 토큰 경제학 시리즈 7편: 토큰 최적화 실전 가이드 - Tool Search, 캐시, 컴팩션

클로드 코드 토큰 경제학 시리즈 7편: 토큰 최적화 실전 가이드 - Tool Search, 캐시, 컴팩션

💡 시리즈 소개: 이 시리즈는 Claude Code 사용자를 위한 토큰 경제학 가이드입니다. 이번 편에서는 토큰을 구조적으로 줄이는 핵심 기술들을 다룹니다.

---

토큰 최적화의 본질

토큰 최적화는 "프롬프트를 짧게 쓰자" 수준의 조언으로 해결되지 않습니다.

Claude Code에서 토큰이 폭발하는 곳:

1. 도구 정의 (초기 고정비)
2. 파일 컨텍스트 (포맷팅 포함)
3. 도구 결과 로그
4. 반복 루프 누적

비용의 핵심은 모델이 아니라 컨텍스트 엔지니어링입니다.

---

핵심 최적화 레버 6가지

1. Tool Search - 초기 컨텍스트 폭발 방지

문제: 도구 정의 과부하

MCP 도구가 많을수록 도구 정의가 컨텍스트를 차지합니다.

기존 방식: 모든 도구 정의를 upfront 로드
→ 58개 도구 = ~55K tokens (작업 시작 전!)

해결: Tool Search (필요한 도구만 로드)

Tool Search 적용:
→ 필요한 도구만 동적 로드
→ 55K → 8.7K tokens
→ 약 85% 절감!

이것은 미세 최적화가 아니라 "세션 시작부터 큰 프롬프트를 들고 다니는 구조"를 바꾸는 설계 변경입니다.

실제 수치 비교

방식	도구 수	토큰	절감률
전통 (upfront)	58개	~55K	-
Tool Search	필요시만	~8.7K	85%

---

2. Prompt Caching - 반복 세션의 혁명

작동 원리

동일한 큰 프롬프트를 반복 전송하지 않도록 캐시에 저장합니다.

┌────────────────────────────────────────┐
│         Prompt Caching 흐름            │
├────────────────────────────────────────┤
│                                        │
│  첫 번째 요청:                          │
│  [시스템 프롬프트] ──► 캐시에 저장      │
│         ↓                              │
│  캐시 쓰기 비용 발생 (+25%)             │
│                                        │
│  두 번째 이후 요청:                     │
│  [캐시에서 읽기] ──► 재전송 생략        │
│         ↓                              │
│  캐시 읽기 비용만 (10%)                 │
│                                        │
└────────────────────────────────────────┘

비용 구조

항목	비용
일반 입력	100%
캐시 쓰기	125% (입력 단가의 1.25배)
캐시 읽기	10% (입력 단가의 0.1배)

절감 효과

• 애플리케이션에 따라 최대 90% 비용 절감 사례 보고
• 특히 "지침/스타일/레포 개요"가 반복되는 Claude Code에서 효과적

캐싱에 적합한 콘텐츠

적합	부적합
시스템 프롬프트	매번 변하는 사용자 입력
팀 스타일 가이드	동적 생성 콘텐츠
예시/템플릿	실시간 로그
읽기 전용 문서	자주 변경되는 파일

---

3. Compaction - 장기 세션의 방파제

작동 원리

오래된 컨텍스트를 요약본으로 치환해 활성 컨텍스트를 줄입니다.

원본 대화 (50K tokens)
        ↓
   [Compaction]
        ↓
요약본 대화 (5K tokens)

트레이드오프

장점	단점
컨텍스트 초과 방지	요약 과정에서 추가 토큰 사용
장기 세션 가능	세부 정보 손실 위험
누적 비용 절감	디버깅 재현성 저하 가능

💡 Compaction은 "단기 오버헤드 vs 장기 절감"의 트레이드오프입니다.

효과적인 Compaction 설정

1. 보존 우선순위 정의
   - 시스템/핵심 규칙: 항상 보존
   - 상태 요약: 요약 보존
   - 원시 로그: 버리거나 외부 저장

2. Compact Instructions 활용
   - 남길 내용을 지침으로 명시

---

4. 로그 절단/요약 - 누적 과금 차단

문제: 다음 턴 입력으로 재과금

긴 로그는 컨텍스트에 포함되는 순간 다음 호출의 입력 토큰으로 누적됩니다.

턴1: 테스트 로그 10K tokens 생성
턴2: 이전 로그 10K 재전송 + 새 로그 5K
턴3: 이전 로그 15K 재전송 + 새 로그 5K
... 기하급수적 증가

해결 전략

전략	설명
발췌	상위 에러 블록/스택트레이스 일부만 포함
외부 저장	원본 로그는 파일로 보관, 필요시만 참조
요약	"테스트 3개 실패: auth, login, session"

실무 정책 예시

로그 포함 정책:
- 에러 메시지: 전체 포함
- 스택트레이스: 상위 10줄
- 전체 로그: file_id로 참조, 필요시만 로드

---

5. Files API - 반복 전송 제거

작동 원리

대용량 컨텐츠를 한 번 업로드 후 file_id로 참조합니다.

❌ 기존: 매 요청마다 파일 내용 전송
   요청1: 파일 100K
   요청2: 파일 100K (다시)
   요청3: 파일 100K (또 다시)

✅ Files API: 한 번 업로드, ID로 참조
   업로드: 파일 100K → file_id 발급
   요청1: file_id 참조 (토큰 미미)
   요청2: file_id 참조 (토큰 미미)

활용 시나리오

• 여러 요청에서 동일 문서 참조
• 대용량 코드베이스 분석
• 반복적인 컨텍스트 필요 시

---

6. Diff/Patch 중심 워크플로

전체 파일 vs Diff 비교 (복습)

방식	4파일×400LOC	토큰
Full files	96,000 chars	~24K
Unified diff	4,800 chars	~1.5K
절감률		94%

적용 가이드

입력 시:
- 전체 파일 대신 변경 관련 부분만
- 필요한 문맥 (변경 주변 3~10줄)

출력 시:
- "전체 파일 재생성" 대신 "diff로만 출력"
- 프롬프트에 명시: "diff 형식으로만 응답해주세요"

---

토큰 절감 베스트 프랙티스 종합

입력 토큰 절감

방법	효과	적용 대상
Tool Search	85% 절감	MCP 도구 다수 환경
Prompt Caching	최대 90%	반복 세션
파일 발췌	파일 크기 비례	대용량 파일
Files API	반복 전송 제거	여러 요청에서 동일 파일

출력 토큰 절감

방법	효과	적용 대상
길이 제한	직접 통제	모든 요청
diff 출력	대폭 감소	코드 수정
max_tokens	상한 설정	장황한 응답 방지
stop sequence	조기 중단	불필요한 생성 차단

누적 토큰 절감

방법	효과	적용 대상
Compaction	장기 절감	긴 세션
로그 발췌	누적 방지	디버깅 루프
턴 최소화	히스토리 감소	반복 질의

---

절감 기술 조합 예시

시나리오: 대규모 코드베이스 분석

Before (최적화 전)

MCP 도구: 58개 upfront → 55K
파일 10개 전체: 100K
로그 재전송: 50K
시스템 프롬프트: 4K
─────────────────────
총: ~209K tokens (200K 초과!)

After (최적화 후)

Tool Search: 필요한 5개만 → 8K
파일 발췌 + Files API: 20K
로그 요약: 2K
Prompt Caching (시스템): ~0.4K (90% 절감)
─────────────────────
총: ~30K tokens (85%+ 절감!)

---

실전 체크리스트

세션 시작 전

• MCP 도구 수 확인 → Tool Search 적용 검토
• 시스템 프롬프트 → Prompt Caching 대상 식별
• 반복 사용 파일 → Files API 업로드

작업 중

• 파일 참조 → 필요한 부분만 발췌
• 코드 수정 → diff/patch 형식 사용
• 로그 포함 → 핵심만 발췌

장기 세션

• 컨텍스트 모니터링 → 200K 경계 확인
• Compaction 설정 → 보존 우선순위 정의
• 히스토리 관리 → 불필요한 누적 제거

---

핵심 정리

기술	타겟	절감 효과
Tool Search	도구 정의 고정비	85%
Prompt Caching	반복 입력	최대 90%
Compaction	장기 누적	상당 (세션 의존)
로그 절단	도구 결과	로그 크기 비례
Files API	반복 전송	반복 횟수 비례
Diff 중심	코드 입출력	94%+

"비용 절감의 핵심은 구조적 접근입니다. 프롬프트를 몇 단어 줄이는 것보다 워크플로를 바꾸는 것이 효과적입니다."

---

다음 편 예고

8편: 운영과 모니터링 - usage 데이터 제대로 활용하기

API의 usage 데이터를 정확하게 집계하고 모니터링하는 방법을 알아봅니다.

---

---

참고 자료

Anthropic 엔지니어링

• Advanced Tool Use - Tool Search (55K→8.7K, 85% 절감)
• Effective Context Engineering - 에이전트 컨텍스트 설계

최적화 기능

• Prompt Caching - 캐시 쓰기 +25%, 읽기 10%, 최대 90% 절감
• Compaction - 컨텍스트 압축/요약
• Files API - 파일 업로드 및 file_id 참조

Claude Code

• Claude Code Costs - 비용 가이드, 로그 절단 권장

---

📚 클로드 코드 토큰 경제학 시리즈 | 2026년 2월