컨텍스트 압축

Claude Code의 컨텍스트 압축 시스템은 제한된 컨텍스트 윈도우를 효율적으로 활용하기 위해 4단계 전략을 사용합니다. 무료 로컬 변환부터 LLM 기반 요약까지, 비용과 품질의 균형을 맞추는 계층적 접근 방식입니다.

컨텍스트 윈도우의 유효 크기는 원시 윈도우보다 작습니다. 시스템 프롬프트(약 20K 토큰)와 압축 요약 출력용 예약 공간(약 20K 토큰)을 제외한 나머지가 실제 대화에 사용됩니다.

압축 전략은 비용이 낮은 순서대로 적용됩니다:

1. Microcompact (무료): API 호출 없이 로컬에서 메시지를 변환
2. Session Memory (무료): 세션 메모리에서 요약을 생성 (API 호출 없음)
3. Full LLM Compaction (유료): LLM에게 대화를 요약하도록 요청
4. Reactive Compaction (유료): API 413 에러 시 긴급 압축

임계값

컨텍스트 사용량에 따라 세 가지 임계값이 압축을 트리거합니다:

• Warning (20K 남음): 사용자에게 컨텍스트 사용량 경고 표시
• AutoCompact (13K 남음): 자동으로 전체 LLM 압축 시작
• Blocking (3K 남음): 응답 생성 전에 압축 완료를 기다림

마이크로컴팩트는 API 호출 없이 로컬에서 메시지를 변환하여 토큰을 절약합니다. 세 가지 경로가 있습니다:

1. 시간 기반 마이크로컴팩트

오래된 메시지의 도구 결과를 축약합니다. 예를 들어 긴 파일 읽기 결과가 "파일 내용이 읽혔습니다 (4,230 토큰)" 같은 짧은 요약으로 대체됩니다.

2. 캐시 마이크로컴팩트

일반 마이크로컴팩트와 달리, 서버 측 cache_edits를 큐잉하여 프롬프트 캐시를 보존합니다. 로컬에서 메시지를 직접 수정하면 캐시된 프롬프트 접두사가 무효화되므로, 캐시 마이크로컴팩트는 서버에 변경을 지시하여 캐시 히트율을 유지합니다.

3. 미변경 마이크로컴팩트

이전에 읽은 파일이 변경되지 않았을 때, 도구 결과를 "파일이 이전 읽기 이후 변경되지 않았습니다"로 대체합니다.

// microCompact.ts — 캐시 보존 마이크로컴팩트
if (shouldUseCacheMicroCompact) {
  // 서버 측 cache_edits 큐잉 — 프롬프트 캐시 보존
  queueCacheEdit({
    type: 'replace_content',
    messageId: entry.uuid,
    newContent: summary,
  })
} else {
  // 로컬 메시지 직접 변경 — 캐시 무효화 감수
  entry.content = summary
}

세션 메모리 압축은 추가 API 호출 없이 기존 세션 메모리에서 요약 정보를 활용합니다. 세션 동안 축적된 메모리 파일의 내용을 압축된 컨텍스트의 일부로 포함하여, 이전 대화의 핵심 결정 사항과 컨텍스트를 보존합니다.

마이크로컴팩트와 세션 메모리로 충분하지 않을 때, LLM에게 대화 전체를 요약하도록 요청합니다. 9개 섹션으로 구성된 요약 프롬프트를 사용합니다:

1. 현재 작업 상태 — 진행 중인 작업과 다음 단계
2. 완료된 작업 — 성공적으로 끝난 작업 목록
3. 핵심 결정 사항 — 사용자와 합의한 설계 결정
4. 중요 파일 경로 — 작업에 관련된 파일 목록
5. 도구 사용 히스토리 — 실행된 도구와 결과 요약
6. 모든 사용자 메시지 — 사용자의 전체 지시 사항
7. 에러 및 해결 — 발생한 오류와 해결 방법
8. 환경 컨텍스트 — 프로젝트 구조, 기술 스택 등
9. 제약 사항 — 사용자가 설정한 제한 조건

analysis 스크래치패드 패턴

요약 프롬프트에는 <analysis> 스크래치패드가 포함됩니다. 모델이 먼저 대화를 분석한 후 구조화된 요약을 생성하도록 유도하여 요약 품질을 높입니다.

반응형 압축은 API에서 413 (Payload Too Large) 에러가 반환될 때 트리거됩니다. 이는 마이크로컴팩트와 자동 압축으로도 충분히 줄이지 못한 극단적 상황에서의 비상 조치입니다.

API 라운드별 메시지 그루핑

압축 대상 메시지를 선택할 때, API 호출 라운드 단위로 그룹화합니다. 단일 메시지를 임의로 자르는 대신, 완전한 요청-응답 쌍을 유지하여 압축 후에도 대화의 논리적 일관성을 보장합니다.

adjustIndexToPreserveAPIInvariants

압축 경계를 결정할 때, API 불변식 2가지를 보호합니다:

• tool_use / tool_result 쌍: 도구 호출과 결과를 분리하지 않음
• thinking 블록: 사고 과정 블록의 중간에서 자르지 않음

압축 완료 후 runPostCompactCleanup()이 캐시와 상태를 정리합니다:

• CLAUDE.md 관련 캐시 초기화
• MCP 스키마 캐시 리셋
• 첨부 파일 캐시 정리
• getUserContext() 캐시 리셋 (메인 스레드에서만)

/context 커맨드

사용자가 수동으로 /context 커맨드를 입력하면 즉시 전체 LLM 압축이 트리거됩니다. 자동 임계값에 도달하기 전에 사용자가 능동적으로 컨텍스트를 관리할 수 있는 인터페이스입니다.