반복 컴팩션 한눈에 보기
- 컴팩션은 컨텍스트 공간을 비우는 자동 요약입니다. 대화가 모델의 창 한도에 가까워지면 Claude Code가 컴팩트합니다(extended context 없는 Sonnet 4.6/Opus 4.6은 200K, 1M 창 모델은 기본 약 967K).
- "계속 컴팩트된다"의 원인은 셋이 보통입니다: 창이 정말 가득 찼거나, 2.1.299에서 추가된 유휴 컴팩션(200K 토큰 이상 대화를 약 54분 방치하면 1시간 프롬프트 캐시가 만료되기 전에 컴팩트)이거나, 2.1.301에서 수정된 게이트웨이 모델명 불일치입니다.
- 이미 보낸 내용은 사라지지 않습니다: 요약에는 핵심 코드와 결정이 남고, resume과 체크포인트가 나머지를 되돌려줍니다. 재개한 세션의 컴팩션 행은 이전 메시지의 저장 위치를 알려줍니다(2.1.301).
- 맞서지 말고 조절하세요: /autocompact 또는 autoCompactWindow 설정으로 창을 바꾸고, CLAUDE_CODE_AUTO_COMPACT_WINDOW가 모든 것에 우선하며, "idleCompaction": false(또는 /config의 Idle compaction 행)로 유휴 컴팩션을 끌 수 있습니다.
- 버전별 루프 두 개에는 수정이 배포됐습니다: 다른 모델명을 응답에 쓰는 LLM 게이트웨이 뒤에서의 반복 컴팩션(2.1.301)과, 아주 큰 중첩 CLAUDE.md 아래 파일을 읽은 뒤의 반복 컴팩션(2.1.309). 조절 전에 먼저 업데이트하세요.
Claude Code: CLAUDE.md, Memory & Session Management
채널David Mahler22:39
Stop Losing Work When You Compact Claude Code
채널The Art of Vibe Coding7:28
Model configuration — Claude Code documentation
문서code.claude.com
메커니즘 프레임은 David Mahler의 세션 관리 워크스루에서 왔습니다 — 애니메이션 컨텍스트 다이어그램, Autocompact buffer 행이 보이는 /context 사용량 그리드, 컴팩션 요약 다이어그램. 임계값과 핸드오프 슬라이드는 The Art of Vibe Coding의 애니메이션 해설에서 왔습니다. 사실 관계는 Claude Code CHANGELOG(2.1.299, 2.1.301, 2.1.302, 2.1.309)와 공식 모델 설정 문서로 대조했습니다. 얼굴 출연 토크 영상과 토큰 절감 가이드에서 이미 쓴 스피너 프레임은 소재에서 제외했습니다.
영상 프레임의 저작권은 원작자에게 있으며, 출처 표기와 딥링크와 함께 단계별 설명 자료로 인용했습니다.
Claude Code 반복 컴팩션 멈추기
1단계 — 컴팩션이 무엇을 하는지 이해
- 1
컴팩션의 실체 알기
컴팩션은 핵심 코드와 결정을 남기면서 오래된 메시지를 요약해 컨텍스트 공간을 비우는 자동 프로세스입니다. 대화가 모델의 창 한도에 가까워지면 Claude Code가 컴팩트합니다 — extended context 없는 Sonnet 4.6과 Opus 4.6은 200K 경계, 네이티브 1M 창 모델은 기본 약 967K 토큰에서요. 긴 세션에서 "Compacting conversation…"이 한 번 뜨는 것은 설계대로 동작하는 것이지 오류가 아닙니다.
컴팩션 정의 슬라이드: 핵심 코드와 결정을 남기며 오래된 메시지를 요약하는 자동 프로세스.10:40에 보기 - 2
창을 채우는 것이 무엇인지 보기
무엇을 바꾸기 전에 /context를 실행합니다. 모델, 창 대비 토큰 수, 항목별 내역 — system prompt, system tools, MCP tools, memory files, Messages, 빈 공간, 확보된 Autocompact buffer — 가 출력됩니다. 녹화된 세션에서는 Messages만으로 149.1k 토큰 중 129.9k(65%)를 차지했고 33k(16.5%)가 버퍼로 확보돼 있었습니다. 컴팩션이 온 이유가 이것이고, 고장이 아니라 대화 자체가 창을 소모하고 있었던 겁니다.
75% 지점의 /context 사용량 그리드: Messages 129.9k 토큰과 하단에 표시된 33k Autocompact buffer(16.5%).10:20에 보기 - 3
비대 루프가 어떤 상태인지 이해하기
긴 출력, 큰 파일 읽기, 방대한 도구 결과가 쌓이면 Messages 블록이 나머지를 밀어냅니다 — skill 설명, MCP tools, 기억된 지시가 눈치채기도 전에 눌립니다. 이 상태에서는 그 이후의 모든 주고받이가 또 다른 컴팩션 사이클을 유발합니다. /context에서 Messages가 지배하고 유용한 지시 행들은 줄어들어 있다면, 처방은 임계값 재조정이 아니라 세션에 넣어주는 입력을 날리는 것입니다.
비대해진 컨텍스트 다이어그램: Messages 블록이 너무 커져 skill 설명, MCP tools, 기억된 지시를 밀어내는 모습.11:26에 보기
2단계 — 작업 복구하고 창 리셋하기
- 4
복구: 요약은 결정을 남기고, resume은 히스토리를 되돌린다
이미 보낸 내용은 사라지지 않습니다. 컴팩션은 Messages 블록을 Conversation Summary로 바꾸고 CLAUDE.md와 Auto Memory 행은 그대로 둡니다. 거기에 Claude Code의 체크포인트와 claude --resume / /resume이 나머지를 되돌려줍니다. 2.1.301부터는 재개한 세션의 컴팩션 행이 불러올 수 없는 히스토리를 제안하는 대신 이전 메시지의 저장 위치를 알려줍니다. 중요한 작업 도중 컴팩트가 끼어들었다면, 다시 설명하기 전에 세션을 재개하고 요약을 읽으세요.
컴팩션 전후 다이어그램: Messages는 Conversation Summary가 되고 빨간 박스의 CLAUDE.md와 Auto Memory 행은 보존됩니다.7:56에 보기 - 5
큰 컴팩트 전에 작업을 디스크에 기록하기
컨텍스트를 잃으면 안 되는 세션은 리셋을 스스로 건너세요: 세션 전체 — 모든 결정, 만진 파일, 남은 과제 — 를 읽어 구조화된 하나의 HANDOFF.md로 디스크에 정리하는 핸드오프 문서를 Claude Code에게 만들게 합니다(/handoff-doc 같은 핸드오프 skill도 가능). 컴팩션 후나 새 세션에서는 다음 프롬프트가 그 파일을 가리키게 하면 요약만으로 출발할 때보다 방향을 더 빨리 되찾습니다.
핸드오프 흐름: /handoff-doc skill이 세션 전체 — 모든 결정, 만진 파일, 남은 과제 — 를 읽어 구조화된 하나의 HANDOFF.md로 정리.1:00에 보기 - 6
두려워하기보다 오토 컴팩트 창 조절하기
발동 지점은 조절할 수 있습니다. /autocompact <value>는 현재 모델에 맞춰 설정하고 사용자 설정에 저장합니다. autoCompactWindow 설정 키(예: ~/.claude/settings.json의 "autoCompactWindow": 200000)는 모든 모델에 적용됩니다. --autocompact는 한 번의 실행만 덮어쓰고, 환경 변수 CLAUDE_CODE_AUTO_COMPACT_WINDOW는 모든 것에 우선합니다(100,000–1,000,000 토큰을 받으며, 2.1.304부터는 200k나 1M로 쓸 수 있습니다). 값은 모델의 실제 창이 상한이고, /autocompact auto로 조정된 기본값으로 돌아갑니다.
임계값 계산: 1M 토큰 Opus 세션의 20%는 약 200,000 토큰 — 실제 작업 약 1시간 분량.2:12에 보기
3단계 — 유휴 컴팩션: 2.1.299의 동작
- 7
유휴 컴팩션 알아보기(Claude Code 2.1.299)
2.1.299부터 창이 가득 찬 것과 무관한 두 번째 발동 조건이 생겼습니다: 유휴 컴팩션입니다. 200K 토큰 이상을 담은 대화를 약 54분 방치하면 1시간 프롬프트 캐시가 만료되기 전에 컴팩트되어, 다음 메시지가 전체 트랜스크립트를 정가로 다시 처리하지 않아도 됩니다. 자리를 비운 사이 Claude Code가 컴팩트했다면 — 돌아오면 트랜스크립트에 알림이 표시됩니다 — 그것은 루프가 아니라 이 기능입니다.
- 8
유휴 컴팩션 끄거나 하한 낮추기
스위치는 둘이고 둘 다 2.1.299 체인지로그에 문서화돼 있습니다: settings.json에 "idleCompaction": false를 설정하면 완전히 꺼지고, CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS를 설정하면 유휴 컴팩션이 절대 발동하지 않는 200K 토큰 하한을 바꿀 수 있습니다(둘 다 v2.1.290 이상 필요). 2.1.302부터는 /config에 Idle compaction 행도 생겼고, 유휴 컴팩션 뒤에 표시되는 알림은 끄는 방법을 알려줍니다. 발동 조건은 200K 토큰 이상을 약 54분 유휴 — 짧은 세션은 절대 건드리지 않습니다.
- 9
정말 꺼야 하는지 판단하기
유휴 컴팩션은 비용을 다른 비용과 바꿉니다. 켜두면 1시간 뒤 돌아왔을 때 정확한 트랜스크립트를 잃고, 꺼두면 다음 메시지가 만료된 캐시로 200K 토큰 이상의 전체 트랜스크립트를 재처리합니다 — 더 느리고 캐시 미스 요율로 과금됩니다. 세션이 길고 자리를 자주 비운다면 끄는 것보다 CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS를 낮추는 편이 보통 이득입니다: 컴팩트가 내 조건으로, 더 작은 블록을 대상으로 일어납니다.
4단계 — 버전별 루프와 예방
- 10
조절 전에 업데이트: 2.1.301 게이트웨이 루프
창이 가득 찬 상태에서 컴팩션이 정말 반복된다면 먼저 버전을 확인합니다. 2.1.301은 "요청한 모델과 다른 모델명을 응답에 쓰는 LLM 게이트웨이 뒤에서, 고르지도 않은 모델로 대화가 계속 컴팩트되는" 문제를 고쳤습니다 — 게이트웨이 응답은 모델 X를, 나는 모델 Y를 요청했고 매 턴 다시 컴팩트됐던 겁니다. 같은 릴리스에서 재개 세션의 컴팩션 행이 불러올 수 없는 히스토리에 ctrl+o를 제안하던 문제도 고쳐졌습니다. 2.1.300 이하 게이트웨이 사용자는 설정을 만지기 전에 업데이트부터.
- 11
CLAUDE.md 날리기 — 2.1.309 중첩 파일 루프
또 하나 기록된 루프: 아주 큰 중첩 CLAUDE.md 아래의 파일을 읽은 뒤 세션이 계속 반복 컴팩션된 문제 — 2.1.309에서 고쳐졌고, 이제 크기 한도를 넘는 중첩 CLAUDE.md는 시작 부분만 불러옵니다. 그래도 메모리 파일을 점검하세요: 사용자 수준 CLAUDE.md는 모든 프로젝트에서, 프로젝트 범위 파일은 작업 디렉터리에서, 온디맨드 하위 디렉터리 파일은 Claude가 방문할 때 불러옵니다. 보편적인 지시가 아닌 것은 항상 불러오는 파일에서 치워내세요.
메모리 범위 다이어그램: 모든 프로젝트의 사용자 수준 CLAUDE.md, 작업 디렉터리의 프로젝트 범위 파일, Claude가 방문할 때 불러오는 온디맨드 파일.4:44에 보기 - 12
다음 루프 예방하기
세 가지 습관이 컴팩션을 이벤트가 아니게 만듭니다. CLAUDE.md를 살 빼 모든 컴팩트에서 지시가 살아남게 하기. 컴팩션을 미루지 말고 임계값에서 일어나게 두기 — 창이 채워질수록 응답 품질이 떨어지고, 남은 20%에서 쓴 요약이 95%에서 쓴 것보다 낫습니다. 그리고 중요한 상태는 파일(핸드오프 문서, 계획, 체크리스트)로 옮겨 모든 리셋이 요약보다 나은 출발점을 갖게 하기.
미루면 손해라는 슬라이드: 컴팩션 임계값을 넘긴 채 컴팩트를 미루면 응답 품질이 떨어집니다.2:20에 보기
유휴 컴팩션, 2.1.299 상세
유휴 컴팩션은 세션이 "컴팩션을 반복"하는 가장 최근 이유이고, 버그로 오해하기 가장 쉬운 것입니다. 2.1.299 체인지로그가 명확한 사유와 함께 터미널에 도입했고, 2.1.301과 2.1.302가 주변 제어를 다듬었습니다. 체인지로그로 확인한 사실:
- 1발동 조건: 200K 토큰 이상의 대화를 약 54분 유휴로 두는 것 — 1시간 프롬프트 캐시가 만료되기 전에 컴팩트가 닿도록 시간이 맞춰져 있습니다.
- 2사유: "so your next message doesn't reprocess it all(다음 메시지가 전부를 재처리하지 않도록)" — 캐시 만료 뒤의 미컴팩트 200K 토큰 이상 트랜스크립트는 캐시 미스 요율로 토큰 하나하나 재처리됩니다.
- 3끄는 스위치: settings.json의 "idleCompaction": false — 또는 2.1.302부터는 /config의 Idle compaction 행.
- 4조절 노브: CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS로 200K 토큰 하한을 변경. 그 미만의 대화는 유휴 컴팩션되지 않습니다.
- 5버전 하한: 환경 변수도 설정도 Claude Code v2.1.290 이상 필요 — 오래된 빌드에는 기능 자체가 없어서, 업데이트 뒤 갑작스러운 동작 변화로 보일 수 있습니다.
- 6가드레일: 짧은 세션은 절대 건드리지 않고, 알림은 돌아왔을 때 트랜스크립트에 표시되며, 2.1.302부터는 알림 자체에 기능을 끄는 방법이 적혀 있습니다.
팀이 세션을 공유한다면 설정은 머신 단위라는 점을 기억하세요: 사용자 설정의 "idleCompaction": false는 저장소를 따라오지 않으므로, 내 세션이 한 번도 컴팩트되지 않아도 팀원의 유휴 세션은 컴팩트될 수 있습니다. 공유하는 장기 세션에는 CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS를 낮추고 누구든 자리를 뜨기 전에 핸드오프 문서를 써 두는 조합이 예측 가능합니다.