Claude Code Compaction 가이드

이 글은 Claude Opus 4.5 을 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.

Claude Code를 하루 종일 사용하다 보면 어느 순간 “Compacting our conversation…” 메시지와 함께 작업 흐름이 끊기는 경험을 하게 됩니다. 이 글에서는 Compaction이 무엇인지, 왜 자주 발생하는지, 그리고 어떻게 줄일 수 있는지 실전 전략을 공유합니다.

Compaction이란?#

Claude Code는 대화 내용, 읽은 파일, 명령어 출력 등을 Context Window라는 제한된 공간에 저장합니다. 이 공간이 가득 차면 Claude는 더 이상 새로운 정보를 처리할 수 없게 됩니다.

Compaction은 이 문제를 해결하기 위해 기존 대화를 요약하고 압축하는 과정입니다. Auto-compact는 보통 Context Window의 75-95% 지점에서 자동으로 트리거됩니다.

flowchart TD
    A["🟢 시작 (0%)"] -->|"대화, 파일 읽기, 명령어 실행"| B["🔵 작업 (40%)"]
    B -->|"계속 작업"| C["🟡 경고 (70%)<br/>⚠️ 최적 compact 시점"]
    C -->|"계속 작업"| D["🔴 위험 (90%)<br/>성능 저하 시작"]
    D -->|"Auto-compact 트리거"| E["🟢 압축 완료 (40%)<br/>요약 후"]
    E -->|"작업 재개"| B

    style A fill:#90EE90,color:#000000
    style B fill:#87CEEB,color:#000000
    style C fill:#FFD700,color:#000000
    style D fill:#FF6B6B,color:#000000
    style E fill:#90EE90,color:#000000

Compaction의 문제점#

Compaction 자체는 필요한 기능이지만, 몇 가지 문제가 있습니다:

작업 흐름 중단: 복잡한 디버깅 중에 갑자기 트리거되면 맥락을 잃을 수 있음
정보 손실: 요약 과정에서 중요한 세부사항이 누락될 수 있음
성능 저하: 80% 이상에서는 Compaction 전에도 이미 품질이 떨어지기 시작

일반적인 Compaction 빈도는?#

하루 8시간 Claude Code 사용 기준으로 예상되는 Compaction 횟수입니다:

작업 유형	예상 횟수	특징
가벼운 작업	1-2회	코드 리뷰, 간단한 수정, 짧은 대화
일반적인 개발	2-4회	기능 구현, 버그 픽스, 일반적인 PR 작업
집중적인 작업	4-6회	대규모 리팩토링, 여러 파일 수정
탐색 위주 작업	6회 이상	코드베이스 분석, 복잡한 디버깅, 레거시 코드 파악

하루 5-6회 이상 Compaction이 발생한다면, 작업 패턴을 점검해볼 필요가 있습니다. 아래 전략들을 적용하면 2-3회 수준으로 줄일 수 있습니다.

Compaction 줄이기 전략#

난이도별로 정리했습니다. 쉬운 것부터 적용해보세요.

🟢 Level 1: 즉시 적용 (5분)#

1.1 작업 단위로 세션 분리하기#

하나의 세션에서 모든 작업을 처리하려 하지 마세요. 논리적 단위로 세션을 분리하면 Context가 깔끔하게 유지됩니다.

# 기능 A 구현 완료 후
/clear

# 기능 B 시작 (새로운 깨끗한 Context)
"UserService에 이메일 검증 로직 추가해줘"

적용 시점:

PR의 각 커밋 단위 작업 완료 후
관련 없는 새 작업 시작 시
디버깅 → 구현 → 테스트 단계 전환 시

1.2 범위를 명확하게 지정하기#

Claude에게 전체를 보여주지 말고, 필요한 부분만 요청하세요.

# ❌ 피해야 할 요청
"이 프로젝트 구조 분석해줘"
"전체 코드베이스에서 결제 관련 코드 찾아줘"

# ✅ 권장하는 요청
"src/payment/PaymentService.kt의 processPayment 메서드만 봐줘"
"build.gradle.kts의 dependencies 블록만 확인해줘"

1.3 현재 상태 모니터링 습관화#

/context  # Context 사용량 확인 (% 표시)
/status   # 전체 상태 확인

70%를 넘기 전에 다음 레벨의 전략을 적용하세요.

🟡 Level 2: 설정 최적화 (15분)#

2.1 CLAUDE.md 다이어트#

CLAUDE.md는 매 대화마다 로드됩니다. 크기가 클수록 사용 가능한 Context가 줄어듭니다.

# 현재 크기 확인
cat ~/.claude/CLAUDE.md ./CLAUDE.md ./.claude/CLAUDE.md 2>/dev/null | wc -w

크기	상태	권장 조치
~1000 words	✅ 최적	유지
1000-2500 words	⚠️ 주의	정리 권장
2500-4000 words	🔴 과다	반드시 정리
4000+ words	💀 위험	20-30% 성능 저하 보고됨

정리 원칙:

빌드/테스트 명령어만 유지
절대적인 규칙만 남기기
상세 가이드는 Skills로 분리

# CLAUDE.md (권장 예시 - 50줄 이내)

## 빌드 & 테스트
- 빌드: `./gradlew build`
- 테스트: `./gradlew test`
- 린트: `./gradlew ktlintCheck`

## 핵심 규칙
- 결제 금액: BigDecimal 필수 (Double 금지)
- API 응답: CommonResponse<T> 래퍼 사용
- 로깅: SLF4J + 구조화된 로깅

## 브랜치 전략
- feature/* → develop → main

2.2 MCP 서버 정리#

MCP(Model Context Protocol) 서버의 도구 정의는 40-55K 토큰을 소비할 수 있습니다.

# 활성화된 MCP 서버 확인
/mcp

# 사용하지 않는 서버 비활성화
/mcp disable postgres
/mcp disable slack

2.3 MCP Tool Search 활성화 (v2.1.7+)#

모든 MCP 도구를 미리 로드하는 대신, 필요할 때만 로드하도록 설정합니다.

// .claude/settings.json
{
  "mcpToolSearch": true
}

효과: MCP 오버헤드 55K → 8.7K 토큰 (85% 감소)

🟠 Level 3: 워크플로우 개선 (30분)#

3.1 선제적 수동 Compact#

Auto-compact를 기다리지 마세요. 70%에 도달하기 전, 논리적 구간에서 직접 compact하세요.

# 기능 구현 완료 후
/compact 수정한 파일 목록과 현재 TODO만 유지해줘

# 디버깅 완료 후
/compact 해결한 버그와 적용한 수정사항만 유지해줘

# 일반적인 정리
/compact 핵심 결정사항과 다음 작업만 유지해줘

권장 주기:

60-90분마다, 또는
25-30개 메시지마다, 또는
각 기능/버그 완료 시점

3.2 Compaction 규칙을 CLAUDE.md에 명시#

# CLAUDE.md

## Compaction 규칙
When compacting, always preserve:
- 수정한 파일 전체 목록
- 현재 진행 중인 작업과 TODO
- 중요한 기술적 결정사항
- 테스트 실행 명령어

3.3 단계별 요청으로 Context 효율화#

한 번에 큰 작업을 요청하면 Claude가 많은 파일을 읽게 됩니다.

# ❌ 비효율적
"이 PR 전체 리뷰해줘"

# ✅ 효율적 (단계별)
"이 PR의 변경된 파일 목록만 보여줘"
# → 결과 확인 후
"그 중에서 PaymentService.kt만 자세히 봐줘"
# → 리뷰 후
"다음으로 PaymentRepositoryTest.kt 봐줘"

🔴 Level 4: 고급 아키텍처 (1시간+)#

4.1 Subagent로 탐색 작업 위임#

Subagent는 별도의 Context Window를 사용합니다. 대규모 탐색 작업을 위임하면 메인 Context가 오염되지 않습니다.

# 메인 Context를 사용하지 않고 탐색
"Explore subagent를 사용해서 결제 관련 코드를 모두 찾아줘"

# 결과만 메인 Context로 전달됨

┌─────────────────────────────────────────────────────────────────┐
│                    Subagent 아키텍처                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────────┐         ┌─────────────────┐              │
│  │   Main Claude   │         │ Explore Subagent│              │
│  │   (작업 수행)    │ ──────▶ │  (탐색 전담)     │              │
│  │                 │         │                 │              │
│  │  Context: 40%   │         │  Context: 80%   │              │
│  │  (깨끗하게 유지) │ ◀────── │  (요약만 반환)   │              │
│  └─────────────────┘         └─────────────────┘              │
│                                                                 │
│  장점: 메인 Context 오염 방지                                    │
│  적합: 코드베이스 분석, 패턴 검색, 영향 범위 파악                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

4.2 Phase 기반 세션 분리#

복잡한 작업은 여러 세션으로 나누어 진행합니다.

Phase 1: 분석 (Session 1)
├── 요구사항 파악
├── 영향 받는 코드 탐색
├── 설계 결정
└── 📝 progress.md에 요약 저장 → /quit

Phase 2: 구현 (Session 2)
├── progress.md 읽고 시작
├── 코드 작성
├── 커밋
└── 📝 progress.md 업데이트 → /quit

Phase 3: 테스트 & 리뷰 (Session 3)
├── progress.md 읽고 시작
├── 테스트 작성
├── 셀프 리뷰
└── PR 생성

4.3 외부 상태 파일 활용#

Context 외부에 진행 상황을 저장하면, 새 세션에서도 이어서 작업할 수 있습니다.

.claude/progress.md (Claude가 직접 관리):

# 현재 작업: 결제 시스템 리팩토링

## 완료된 작업
- [x] PaymentService 인터페이스 분리
- [x] CardPaymentProcessor 구현

## 진행 중
- [ ] BankTransferProcessor 구현
- [ ] 테스트 코드 작성

## 수정한 파일
- src/payment/PaymentService.kt
- src/payment/CardPaymentProcessor.kt
- src/payment/PaymentProcessor.kt (신규)

## 기술적 결정
- Circuit Breaker: Resilience4j 사용
- 타임아웃: 외부 API 호출 5초

# 새 세션에서 이어서 작업
"@.claude/progress.md 읽고 BankTransferProcessor 구현 이어서 해줘"

4.4 Git 기반 Context 복원#

Git 히스토리를 활용하면 별도 파일 없이도 맥락을 복원할 수 있습니다.

# 세션 종료 전: 진행 상황 커밋
git add -A && git commit -m "WIP: Payment 리팩토링 - CardProcessor 완료"

# 새 세션 시작 시
"git log --oneline -5와 git diff HEAD~1 확인하고,
 마지막 작업 이어서 진행해줘"

즉시 적용 체크리스트#

오늘 바로 적용할 수 있는 액션 아이템입니다:

# 1. 현재 상태 확인
/context

# 2. CLAUDE.md 크기 확인 (4000 words 이하로 유지)
cat ~/.claude/CLAUDE.md ./CLAUDE.md ./.claude/CLAUDE.md 2>/dev/null | wc -w

# 3. MCP 서버 확인 및 정리
/mcp
/mcp disable <사용하지않는서버>

# 4. Tool Search 활성화 확인
cat .claude/settings.json | grep mcpToolSearch

핵심 정리#

전략	효과	적용 난이도
작업 단위 `/clear`	⭐⭐⭐⭐⭐	🟢 쉬움
70%에서 선제적 `/compact`	⭐⭐⭐⭐⭐	🟢 쉬움
CLAUDE.md 다이어트	⭐⭐⭐⭐	🟡 보통
MCP 서버 정리	⭐⭐⭐⭐	🟡 보통
Subagent 활용	⭐⭐⭐⭐⭐	🔴 어려움
Phase 기반 세션 분리	⭐⭐⭐⭐	🔴 어려움

가장 효과적인 조합:

작업 완료마다 /clear
70%에서 선제적 /compact
CLAUDE.md 4000 words 이하 유지
사용하지 않는 MCP 비활성화

이 네 가지만 적용해도 Compaction 빈도를 절반 이하로 줄일 수 있습니다.

참고 자료#

Claude Code Best Practices - 공식 문서
Context Editing API - API 레벨 컨텍스트 관리
Claude Code Changelog - 버전별 변경사항

이 글은 Claude Code 2.1.x 버전 기준으로 작성되었습니다. 버전에 따라 일부 기능이나 설정이 다를 수 있습니다.