Claude Code는 Anthropic의 자율형 코딩 어시스턴트로, 코드베이스를 읽고 파일을 편집하며 명령을 실행하고 터미널, IDE, 데스크톱 앱, 브라우저 워크플로우 전반의 도구들과 통합할 수 있습니다. 공유된 컨텍스트 윈도우 안에서 작동하기 때문에, 긴 세션은 결국 채팅 기록, 파일 출력, 도구 로그로 가득 차게 됩니다. Claude Code는 한계에 접근할 때 대화 기록을 자동으로 압축해 관리하며, 초반 지시사항이 채팅 기록에만 있으면 사라질 수 있습니다.
이 점은 2026년에 더욱 중요해졌습니다. Anthropic은 Claude Code를 더 길고 자율적인 작업으로 계속 밀고 있기 때문입니다. 2026년 3월 25일, Anthropic은 “Claude Code auto mode: a safer way to skip permissions”를 발표하며, 사용자가 권한 요청의 93%를 승인하고 자동 모드를 수동 승인과 위험한 권한 생략 사이의 분류기 기반 중간지대로 설명했습니다. 2026년 2월 5일에는 Claude Opus 4.6을 출시하여 더 강한 코딩, 개선된 디버깅, 더 긴 자율형 세션을 강조했습니다. 이러한 업데이트는 auto compact와 동일하지 않지만, 제품 방향성을 명확히 보여줍니다: 중단 감소, 더 긴 세션, 더 안정적인 연속성.
CometAPI는 현재 공식 API보다 낮은 가격으로 Claude API에 대한 액세스를 제공합니다. 예: Claude Sonnet 4.6, Claude Opus 4.6, 그리고 Claude 5.
What auto-compact actually means in Claude Code
Auto Compact는 Claude Code(Anthropic의 CLI/데스크톱 도구)와 더 넓은 Claude API 생태계에 내장된 컨텍스트 최적화 메커니즘입니다. 대화가 모델의 컨텍스트 윈도우 상한에 가까워질 때—일반적으로 Claude Opus 4나 Sonnet 4 같은 플래그십 모델의 경우 약 200,000 토큰—자동으로 개입합니다. 훅 문서는 명시적입니다: PreCompact는 압축 작업 전에 발동되며, auto 매처는 “컨텍스트 윈도우가 꽉 찼을 때 자동 압축”을 의미합니다. 대응되는 PostCompact 훅은 압축 완료 후 발동되며, 생성된 compact_summary를 전달받습니다.
이는 컴팩션이 “memory”와 동일하지 않기 때문에 중요합니다. Auto memory는 Claude의 자체 노트 기록 시스템이고, 컴팩션은 라이브 대화 상태를 압축하는 세션 관리 메커니즘입니다. 메모리 문서는 CLAUDE.md가 지속적이며, auto memory는 Claude가 작성하고, 컴팩션은 모델이 계속 작업할 수 있도록 세션의 대화 기록을 줄이는 순간이라고 명확히 설명합니다.
새 채팅을 강제(역사 손실)하거나 모델이 중요한 세부사항을 “잊게” 만드는 대신, Auto Compact는 다음을 수행합니다:
- 핵심 요소를 식별하기 위해 전체 기록을 분석합니다.
- 결정 사항, 코드 아키텍처, 해결된 버그, 파일 상태, 다음 단계의 간결한 요약을 생성합니다.
- 이전 메시지를 이 요약(“compaction block”이라는 API 용어)으로 대체합니다.
- 보존된 컨텍스트로 매끄럽게 이어서 진행합니다.
Key Data Points (2026):
- Trigger threshold: 기본값은 용량의 약 95%(또는 약 25% 남음)입니다. 일부 사용자는 컴팩션 자체를 위해 20–45k 토큰(컨텍스트의 약 22.5%)을 예약하는 내부 버퍼를 보고합니다.
- Performance improvement: Claude Code v2.0.64 이후로 컴팩션은 “즉시” 수행되며, 몇 분이 걸리던 과거보다 크게 개선되었습니다.
- Token savings example(Claude Agent SDK 벤치마크 기준): 5-티켓 워크플로우가 두 번의 컴팩션 이벤트로 입력 토큰이 204k에서 82k로 감소(58.6% 절감)했습니다.
Auto Compact는 /clear(모두 삭제)나 단순 잘라내기와 동일하지 않습니다. 중요 요소—최근 코드 diff, 아키텍처 결정, 네이밍 규칙—를 지능적으로 보존하면서, 해결된 디버깅 루프와 탐색적 여담을 응축합니다.
Why Use Auto Compact in Claude Code?
긴 코딩 세션은 일반적입니다. 단일 기능 구현이 50회 이상의 턴을 포함할 수 있습니다: 계획, 디버깅, 리팩토링, 테스트. 컴팩션이 없다면 토큰 사용량은 선형으로 증가하고, 응답 품질은 저하되며, 비용이 급증합니다.
개발자에게 보상은 재시작 피로의 감소입니다. 새 세션으로 요약을 수동 복사하는 대신, Claude가 세션을 압축하도록 두고 계속 진행합니다. 이는 특히 버그 수정, 다중 파일 리팩토링, 테스트 주도 변경, 리뷰 중심 워크플로우에서 대화가 매우 길어질 때 유용합니다. Claude Code 세션은 새로운 컨텍스트 윈도우로 시작하므로, 컴팩션은 장시간 작업을 실용적으로 만드는 핵심 메커니즘 중 하나입니다.
Core Benefits
- 무제한에 가까운 세션 길이: 처음부터 다시 시작하지 않고 계속 진행합니다.
- 비용 및 성능 효율: 입력 토큰을 크게 줄입니다. 실제 보고에서는 다단계 워크플로우에서 50–60% 절감이 관찰됩니다.
- 더 나은 집중과 안정성: “컨텍스트 과부하”로 인한 환각이나 초기 제약의 망각을 방지합니다.
- 조직 지식 보존: 수백 개 메시지 이후에도 핵심 결정이 컨텍스트에 남습니다.
- 에이전틱 워크플로우에 매끄럽게 적합: 도구 사용, MCP 서버, 멀티 에이전트 설정에서 중요합니다.
When should you rely on auto compact?
작업이 자연스럽게 장시간 진행될 때 Auto Compact를 사용하세요: 다중 파일 리팩토링, 로그와 소스 사이를 오가는 디버깅 세션, 반복적 검증을 포함한 기능 구현, 다수의 도구 호출이 필요한 리서치. Anthropic 문서는 컨텍스트 윈도우가 관련 없는 대화, 파일 내용, 명령으로 채워지는 긴 세션을 명시적으로 지목하며, Auto Compact가 핵심 코드와 결정을 보존하는 동시에 공간을 확보한다고 말합니다.
작업이 짧고, 고립되어 있거나, 정확하고 영구적으로 유지되어야 하는 지시사항이 필요한 경우에는 덜 적합합니다. 대화 초반의 지시사항은 컴팩션 이후에 사라질 수 있으므로, 프로젝트 규칙은 CLAUDE.md에 포함되어야 하며, 나중에 압축될 수 있는 일회성 프롬프트에만 두지 마세요.
When to use (or enable) it:
- 대부분 사용자에게 기본적으로 항상 켜짐 — 일상적인 코딩, 대규모 리팩토링, 탐색적 프로젝트에 이상적입니다.
- 장시간 작업 — 큐 처리, 데이터 파이프라인, 다중 파일 코드베이스.
- 팀/엔터프라이즈 환경 — 세션 간 컨텍스트 연속성이 중요한 경우.
- 고위험 프로젝트 — 단 하나의 아키텍처 결정 손실이 수 시간 비용을 초래할 수 있는 경우.
When to consider disabling (via /config):
- 극도로 정밀한 제어를 위해 컨텍스트의 모든 토큰을 사용하고 싶을 때.
- 파일을 통해 계획을 저장/복원하는 완전 수동 관리를 선호할 때(파워 유저).
Latest news (2025–2026): 2025년 3월, Anthropic은 Auto Compact의 보존 로직을 개선하여 “중요 정보를 유지하면서 토큰 사용량을 줄이는” 더 스마트한 요약을 제공했습니다. 2025년 말에는 트리거가 정교화되어(컴팩션 실패를 피하기 위해 때로는 64–75% 사용량에서 더 일찍) 발동했습니다. 2026년 초에는 웹/데스크톱 인터페이스에서 일시적 버그가 있었고(1월 중순에 수정되었으나 일부 보고 지속), CLI는 안정적이었습니다. 2.0.64 버전(2026년 2월)에서는 컴팩션이 즉시로 바뀌어 개발자 경험이 크게 개선되었습니다.
How to Use Auto Compact in Claude Code: Step-by-Step Guide
Claude Code는 각 세션이 새로운 컨텍스트 윈도우로 시작되도록 설계되었습니다. 이는 모든 새 작업이 깨끗하게 시작되게 하며, 세션이 시끄러워질 때를 파악하기 쉽게 해줍니다. 관련 없는 작업 사이에서는 /clear를 권장하여 오래된 컨텍스트가 공간을 계속 차지하지 않도록 하세요.
Step 1: Check Current Context Status
/context를 사용해 현재 컨텍스트 사용량을 시각화하세요. Claude Code의 내장 명령 목록은 /context가 색상 그리드를 보여주고, 메모리 팽창, 최적화 제안, 용량 경고를 하이라이트한다고 설명합니다. 이는 자동 컴팩션 발동 시점에 가까워졌는지 파악하는 가장 빠른 방법입니다.
Claude Code 세션에서 다음을 입력하세요:
/context
“Context left until auto-compact: XX%” — 실시간 진행 바를 확인할 수 있습니다.
Step 2: Configure Auto-Compact (Optional)
컨텍스트 윈도우가 가득 차면, Claude Code는 대화를 자동으로 압축합니다. 훅 참조는 이 이벤트를 auto로 레이블하며, 컨텍스트 윈도우가 가득 찼을 때 발동됩니다. 실제로 Auto Compact를 “켜는” 것이 아니라, 필요할 때 Claude Code가 수행하도록 두는 것입니다.
/config
“Auto-compact enabled”로 이동해 true/false를 토글하세요. 기본값은 enabled입니다. MCP 서버 사용 같은 관련 설정을 조정하여 미리 토큰을 확보할 수도 있습니다.
Step 3: Let Auto-Compact Run Automatically
약 95%에 도달하면:
- Claude가 “Compacting our conversation so we can keep chatting…”(또는 유사한 메시지)을 표시합니다.
- 백그라운드에서 실행되고 곧 재개됩니다.
- 컨텍스트 상단에 새로운 요약을 볼 수 있습니다.
Pro tip: 0%까지 기다리지 마세요. 더 나은 결과를 위해 더 일찍 수동 컴팩션을 수행하세요(아래 모범 사례 참조).
Step 4: Use hooks if you want to automate what happens around compaction
Claude Code는 PreCompact와 PostCompact 훅을 모두 노출합니다. 훅 참조에 따르면 PreCompact는 컴팩션이 수동인지 자동인지 감지할 수 있으며, PostCompact는 생성된 compact_summary를 전달받습니다. 따라서 훅은 로깅, 감사 추적, 컴팩션 이후 노트, 외부 자동화에 적합합니다.
간단한 훅 패턴은 다음과 같습니다:
{ "hooks": { "PostCompact": [ { "matcher": "auto", "hooks": [ { "type": "command", "command": "./scripts/save-compact-summary.sh" } ] } ] }}
매칭되는 셸 스크립트는 stdin에서 JSON 입력을 읽을 수 있습니다. Claude Code 커맨드 훅은 JSON을 그 방식으로 전달하기 때문입니다:
#!/usr/bin/env bashset -euo pipefailjq -r '.compact_summary // empty' \ | sed 's/^/[compact] /' \ >> .claude/compact-log.txt
문서는 커맨드 훅이 stdin을 통해 JSON을 수신하고, PostCompact에 compact_summary가 포함된다고 확인하므로, 이 패턴은 현재 훅 모델과 일치합니다.
Step 5: Manual Compact with Precision (Recommended)
지금 스레드를 압축하고 싶을 때 /compact를 사용하세요. 보존하고 싶은 요약의 형태를 지정하는 지시사항을 포함할 수 있습니다. Anthropic의 내장 명령 페이지는 /compact [instructions]를 “옵션 포커스 지시사항과 함께 대화를 압축”이라고 설명합니다,
/compact keep the auth flow decisions, the current test plan, and the open TODOs
이 패턴은 인수인계 직전, 브랜치 전환 전, Claude에게 작업의 새 단계를 시작하도록 요청하기 전에 유용합니다.
Examples from real usage:
- After debugging: /compact keep the solution we found, remove debugging steps
- Project milestone: /compact focus on the new feature requirements
API-Level Compaction (Advanced – Python SDK & Messages API)
커스텀 에이전트나 스크립트에서는 공식 컴팩션 도구를 사용하세요.
Claude Agent Python SDK example(도구 사용 워크플로우에 자동 적용):
from anthropic import Anthropic
client = Anthropic()
runner = client.beta.messages.tool_runner(
model="claude-opus-4-6",
max_tokens=4096,
tools=your_tools,
messages=messages,
compaction_control={
"enabled": True,
"context_token_threshold": 100000, # or lower for aggressive compaction
"model": "claude-haiku-4-5", # cheaper summarizer
"summary_prompt": """Create a focused summary preserving:
1. COMPLETED TASKS and key outcomes
2. CURRENT STATE and open items
3. NEXT STEPS
Wrap in <summary></summary> tags."""
}
)
Detect compaction events:
if curr_msg_count < prev_msg_count:
print(f"Compaction occurred! Messages reduced from {prev_msg_count} to {curr_msg_count}")
```<grok-card data-id="f4afb5" data-type="citation_card" data-plain-type="render_inline_citation" ></grok-card>
Full Messages API (beta, 2026) – requires header:
```bash
curl https://api.anthropic.com/v1/messages \
--header "anthropic-beta: compact-2026-01-12" \
--data '{
"model": "claude-opus-4-6",
"messages": [...],
"context_management": {
"edits": [{
"type": "compact_20260112",
"trigger": {"type": "input_tokens", "value": 150000},
"pause_after_compaction": true
}]
}
}'
API는 향후 호출에서 전달해야 하는 컴팩션 블록을 반환합니다. 사용자 지정 지시사항과 일시중지는 예산 관리에 대한 완전한 제어를 제공합니다(예: 세션 전체에서 총 300만 토큰 상한을 강제).
If you are using the Claude API of CometAPI, change the message header to "https://api.cometapi.com/v1/messages\\".
Auto-Compact vs Manual Compact vs Clear: Comparison Table
| Feature | Auto-Compact | Manual /compact | /clear |
|---|---|---|---|
| Trigger | Automatic (~95% context) | User-initiated | User-initiated |
| Control | Low (system decides) | High (custom instructions) | None (full reset) |
| Context Preservation | Good (recent + key items) | Excellent (you guide exactly) | None |
| Token Savings | High (58%+ in benchmarks) | High + predictable | Maximum (but loses history) |
| Workflow Disruption | Minimal if instant; can be jarring | None (you choose timing) | Complete reset |
| Best For | Hands-off long sessions | Strategic milestones & power users | Starting fresh projects |
| Risk | Occasional loss of nuance (early bugs) | None | Total loss of prior work |
| 2026 Maturity | Stable & instant (v2.0.64+) | Highly recommended by community | Always available |
Best Practices for Claude Code Auto Compact (Pro Tips from Developers)
Compact proactively
세 번째 규칙은 컴팩션을 지팡이가 아닌 리셋으로 사용하라는 것입니다. 스레드가 막다른 길로 가득 차 있다면, Claude에게 현재 목표, 선택한 접근법, 실패하는 테스트, 미해결 질문에 대해 무엇이 중요한지 명확히 지시하며 압축을 요청하세요. 실제로 이렇게 하면 시스템이 맹목적으로 자동 압축을 수행하고 좋은 결과를 바라기만 하는 것보다 훨씬 유용한 요약을 얻을 수 있습니다.
Keep your durable instructions short.
Anthropic은 200라인을 넘는 파일이 준수도를 떨어뜨릴 수 있다고 말합니다. 따라서 큰 정책 블랍은 간결하고 범위가 잘 정의된 규칙보다 대체로 좋지 않습니다. 파일 유형이나 경로별 동작에는 .claude/rules/를 사용하고, 메인 지시 파일을 비대하게 만들지 않고도 풍부한 보조 세부사항이 필요할 때는 @path 임포트를 사용하세요.
Free tokens first — 컴팩션 전에 /mcp로 사용하지 않는 MCP 서버를 비활성화하거나 @server-name disable로 토큰을 선제적으로 확보하세요.
Combine with CLAUDE.md
CLAUDE.md를 장시간 세션에서 유지하고 싶은 모든 것의 소스 오브 트루스로 취급하세요CLAUDE.md는 /compact 후 다시 읽히므로, 빌드 명령, 코딩 컨벤션, 결코 잃고 싶지 않은 지속적 규칙을 담기에 적합합니다. Auto memory도 유용하지만, 목적이 다른 별개 시스템입니다.
Other tips
/context로 모니터링 — 가능하다면 사용량을 70–80% 이하로 유지하세요.
API 사용자 — 더 낮은 임계값(예: 50k–100k)을 설정하고 Haiku 같은 더 저렴한 요약 모델을 사용하세요.
필요할 때만 비활성화 — 대부분의 개발자는 2025년 개선 이후 Auto-Compact를 켜두는 것을 권장합니다.
컴팩션 테스트 — 중요하지 않은 세션에서 먼저 테스트하여 특정 워크플로우가 어떻게 요약되는지 확인하세요.
Real-world impact: 개발자들은 생산적인 세션이 2–3배 길어지고 “Claude가 우리가 하던 일을 잊었다”는 순간이 줄어들었다고 보고합니다.
Common Issues & Troubleshooting (2026 Edition)
- Auto-compact가 발동하지 않음: 웹/데스크톱 vs CLI를 확인하세요. 2026년 1월 일부 버그가 수정되었지만, 버전을 검증하세요.
- 컴팩션 후 컨텍스트 손실: 다음에는 명시적 지시사항을 포함한 수동
/compact를 사용하세요. - 무한 루프 또는 102% 사용량: 드뭅니다. 세션을 재시작하거나 최후 수단으로
/clear를 사용하세요. - 느린 컴팩션: v2.0.64 이전 이슈입니다 — Claude Code를 업데이트하세요.
- API 컴팩션 블록 오류: 후속 호출에 항상 전체 컴팩션 콘텐츠 블록을 추가하세요.
Conclusion
Auto compact는 Claude Code의 가장 중요한 숨은 메커니즘 중 하나입니다. 컨텍스트 윈도우가 가득 찔 때마다 매번 재시작하지 않고도 긴 코딩 세션을 사용 가능하게 만들어 줍니다. 실용적인 규칙은 간단합니다: 초과분은 Auto Compact에 맡기고, 통제가 필요할 때는 /compact를 사용하며, 지속적인 지침은 CLAUDE.md에 저장하고, 세션 구조가 바뀌면 /clear나 /rewind를 사용하세요. 이 조합은 긴 Claude Code 워크플로우에서 연속성, 통제, 속도의 최적 균형을 제공합니다.
Claude Code의 Auto Compact는 200k 토큰 컨텍스트 윈도우를 지능적으로 관리함으로써 장시간 코딩의 가장 큰 마찰점인 “메모리 부족”을 제거합니다. 즉시 수행(2026), 풍부한 구성 옵션, 강력한 API 확장으로, 이제 매일 수천 명의 개발자가 사용하는 성숙하고 실전 검증된 기능이 되었습니다.
Action steps today:
- Claude Code에서
/config를 실행해 Auto-Compact가 활성화되어 있는지 확인하세요. - 현재 프로젝트에서 지시사항을 포함한 수동
/compact를 시도해 보세요. - CometAPI.에서 자동화 에이전트를 위한 Python SDK 또는 Messages API를 탐색하세요.