Claude Code 토큰 최적화 완전 가이드

Claude Code 토큰 최적화 완전 가이드

토큰이란?

토큰은 AI 모델이 텍스트를 처리하는 기본 단위입니다. Claude Code를 사용할 때 입력과 출력 모두 토큰으로 계산되며, 이는 비용과 직결됩니다. 효율적인 토큰 사용은 비용 절감과 성능 향상을 동시에 달성할 수 있습니다.

토큰 절약의 핵심 전략

1. 컨텍스트 최적화

필요한 파일만 포함

# ❌ 비효율적: 전체 프로젝트 포함
claude-code generate "함수 최적화" --include-all

# ✅ 효율적: 특정 파일만 포함
claude-code generate "함수 최적화" --files src/utils.js

# ✅ 더 효율적: 특정 함수만 포함
claude-code generate "optimize_function" --lines 15-45 --file src/utils.js

컨텍스트 크기 제한

# 컨텍스트 윈도우 크기 설정
claude-code config set context-window 4000

# 최대 파일 크기 제한
claude-code config set max-file-size 50kb

# 포함할 파일 타입 제한
claude-code config set include-patterns "*.js,*.ts,*.py"

2. 프롬프트 최적화

간결하고 명확한 프롬프트

# ❌ 장황한 프롬프트
claude-code generate "이 함수를 더 효율적으로 만들어주세요. 성능을 개선하고 메모리 사용량을 줄이고 가독성도 향상시켜주세요."

# ✅ 간결한 프롬프트
claude-code generate "optimize performance + memory + readability"

# ✅ 구조화된 프롬프트
claude-code generate "optimize: performance,memory,readability"

키워드 기반 명령

# 구체적인 작업 지시
claude-code refactor --target "async/await" --file api.js
claude-code fix --error "memory leak" --file server.js
claude-code add --feature "error handling" --file utils.js

3. 스마트 파일 필터링

.claudeignore 파일 활용

# .claudeignore 파일 생성
cat > .claudeignore << EOF
node_modules/
*.log
*.tmp
build/
dist/
coverage/
.git/
*.md
package-lock.json
yarn.lock
EOF

동적 필터링

# 최근 변경된 파일만 포함
claude-code generate "bug fix" --changed-since "1 day ago"

# 특정 크기 이하 파일만 포함
claude-code analyze --max-size 10kb

# 특정 패턴 제외
claude-code review --exclude "test/*,docs/*"

/compact 명령어 완전 가이드

/compact란?

/compact 명령어는 Claude Code의 핵심 토큰 절약 기능으로, 코드와 컨텍스트를 압축하여 토큰 사용량을 최소화합니다.

기본 사용법

기본 압축

# 전체 프로젝트 압축
claude-code /compact

# 특정 디렉토리 압축
claude-code /compact --dir src/

# 특정 파일들 압축
claude-code /compact --files "*.js,*.ts"

압축 레벨 설정

# 레벨 1: 기본 압축 (주석 제거, 공백 정리)
claude-code /compact --level 1

# 레벨 2: 중간 압축 (변수명 단축, 구조 간소화)
claude-code /compact --level 2

# 레벨 3: 최대 압축 (핵심 로직만 유지)
claude-code /compact --level 3

압축 옵션 상세

1. 주석 및 문서 처리

# 모든 주석 제거
claude-code /compact --remove-comments

# JSDoc/docstring만 유지
claude-code /compact --keep-docs

# 중요 주석만 유지 (TODO, FIXME, HACK 등)
claude-code /compact --keep-important

2. 코드 구조 압축

# 함수 시그니처만 유지
claude-code /compact --signatures-only

# 타입 정의 압축
claude-code /compact --compress-types

# import/export 정리
claude-code /compact --clean-imports

3. 선택적 압축

# 특정 함수만 압축
claude-code /compact --functions "processData,validateInput"

# 특정 클래스만 압축
claude-code /compact --classes "UserManager,ApiClient"

# 테스트 파일 제외
claude-code /compact --exclude-tests

압축 전략별 사용법

1. 코드 리뷰용 압축

# 구조와 로직에 집중
claude-code /compact --level 2 --keep-structure --remove-implementation-details

# 사용 예시
claude-code review --compact-mode --focus "architecture,patterns"

2. 디버깅용 압축

# 에러 관련 코드만 유지
claude-code /compact --error-context --around-lines 5

# 사용 예시
claude-code debug "TypeError in processUser" --compact-context

3. 리팩토링용 압축

# 변경 대상 함수 주변만 압축
claude-code /compact --focus-function "calculateTotal" --context-lines 10

# 사용 예시
claude-code refactor "optimize calculateTotal" --compact-input

고급 압축 설정

1. 맞춤형 압축 규칙

# 설정 파일 생성
cat > .claude-compact.json << EOF
{
  "removeComments": true,
  "keepDocstrings": true,
  "compressWhitespace": true,
  "shortenVariables": false,
  "preserveStructure": true,
  "excludePatterns": ["*.test.js", "*.spec.ts"],
  "compressionLevel": 2
}
EOF

# 설정 파일 사용
claude-code /compact --config .claude-compact.json

2. 언어별 최적화

# JavaScript/TypeScript 최적화
claude-code /compact --js-optimize --remove-unused-imports

# Python 최적화
claude-code /compact --py-optimize --remove-unused-variables

# 범용 최적화
claude-code /compact --auto-optimize

압축 결과 분석

토큰 사용량 비교

# 압축 전후 토큰 수 비교
claude-code /compact --analyze --show-savings

# 출력 예시:
# Original: 15,432 tokens
# Compressed: 3,847 tokens
# Savings: 75.1% (11,585 tokens)

압축 품질 확인

# 압축된 코드 검증
claude-code /compact --validate --test-syntax

# 중요 정보 손실 확인
claude-code /compact --check-completeness

실용적인 토큰 절약 워크플로우

1. 프로젝트 초기 설정

# 1단계: 프로젝트 분석
claude-code analyze --token-usage --estimate-costs

# 2단계: 압축 프로필 생성
claude-code /compact --create-profile --name "default"

# 3단계: 무시 규칙 설정
claude-code config set-ignore --auto-detect

2. 일상적인 작업 최적화

# 빠른 질문 (최소 컨텍스트)
claude-code ask "함수 시그니처가 맞나?" --minimal-context

# 코드 리뷰 (압축된 컨텍스트)
claude-code review --compact --focus-issues

# 리팩토링 (타겟 압축)
claude-code refactor "optimize loops" --compact-target-only

3. 대용량 프로젝트 처리

# 단계별 처리
claude-code /compact --by-module --max-tokens 2000
claude-code generate "module optimization" --batch-mode

# 점진적 압축
claude-code /compact --incremental --previous-context

토큰 모니터링 및 관리

사용량 추적

# 실시간 토큰 카운터
claude-code config set show-token-count true

# 세션별 사용량 로그
claude-code usage --session --detailed

# 월별 사용량 리포트
claude-code usage --monthly --export csv

비용 최적화 알림

# 토큰 한계 설정
claude-code config set token-limit 10000

# 비용 알림 설정
claude-code config set cost-alert 50

# 자동 압축 트리거
claude-code config set auto-compact-threshold 5000

베스트 프랙티스

1. 작업별 최적화 전략

코드 생성

# 작은 단위로 반복 생성
claude-code generate "add validation" --function-by-function

디버깅

# 에러 컨텍스트만 포함
claude-code debug --error-only --minimal-trace

문서화

# 코드 구조만 포함
claude-code doc --structure-only --no-implementation

2. 팀 차원의 최적화

공통 설정 공유

# 팀 설정 파일 생성
claude-code config export --team > team-claude-config.json

# 팀 설정 적용
claude-code config import team-claude-config.json

압축 프로필 관리

# 프로젝트별 프로필
claude-code /compact --save-profile "frontend"
claude-code /compact --save-profile "backend"
claude-code /compact --save-profile "testing"

고급 최적화 기법

1. 동적 컨텍스트 관리

# 이전 대화 컨텍스트 재사용
claude-code generate --reuse-context --session-id abc123

# 점진적 컨텍스트 구축
claude-code generate --incremental-context --build-on-previous

2. 캐싱 활용

# 압축 결과 캐싱
claude-code /compact --cache-result --cache-key "project-v1"

# 캐시된 압축 사용
claude-code generate --use-compressed-cache "project-v1"

3. 병렬 처리로 효율성 증대

# 파일별 병렬 압축
claude-code /compact --parallel --workers 4

# 배치 작업 최적화
claude-code generate --batch --optimize-tokens

결론

토큰 최적화는 Claude Code를 효율적으로 사용하는 핵심입니다. /compact 명령어와 다양한 최적화 전략을 조합하여 사용하면 비용을 크게 절약하면서도 높은 품질의 결과를 얻을 수 있습니다. 프로젝트 규모와 작업 유형에 맞는 최적화 전략을 선택하여 활용하시기 바랍니다.