요약
- 대화가 컨텍스트 한도에 가까워지면 auto compact가 오래된 기록을 요약합니다. v2.1.288부터 auto 모드도 긴 대화에서 도구 호출을 실패 처리하는 대신 압축합니다.
- /autocompact 500k로 트리거 창을 설정합니다(100K–1M 토큰). v2.1.288부터 모델별로 저장되며, /autocompact auto로 모델 조정 기본값으로 돌아갈 수 있습니다.
- /context로 공간 사용 내역과 예약된 Autocompact buffer를 볼 수 있습니다. 같은 기능을 이어가면 compact, 새 작업이면 /clear.
- 압축은 대화 전체를 읽으므로 긴 세션일수록 오래 걸립니다. 멈추면 먼저 Claude Code를 업데이트하세요. 2.1.288에서 「Prompt is too long」으로 실패하는 문제가 수정되었습니다.
Context Management in Claude Code
채널: Anthropic · Claude3:31
Claude Code release notes — v2.1.288
릴리스 노트: github.com/anthropics/claude-code
Set the auto-compact window — official documentation
문서: code.claude.com/docs
이 페이지의 사실 관계는 Claude Code 공식 문서 및 v2.1.288 체인지로그와 대조 확인했습니다. 스크린샷은 위 영상에서 가져왔습니다. 설명된 동작은 Claude Code v2.1.288(2026년 9월) 기준입니다.
스크린샷은 Anthropic의 「Context Management in Claude Code」 영상에서 가져온 프레임이며, 출처를 밝히고 각 단계에 원본 영상 타임스탬프 링크를 달았습니다.
auto compact 단계별 풀이
컨텍스트를 채우는 것이 무엇인지 파악
- 1
컨텍스트에 로드된 것 목록 확인하기
/context를 실행하고 내역을 스크롤해 보세요. MCP 도구는 온디맨드로 로드되지만, 도구 정의·커스텀 에이전트·스킬은 각자 토큰을 미리 확보합니다. 첫 프롬프트를 보내기 전에 이미 차감된 셈이죠. 프로젝트에 불필요한 MCP 서버를 끄는 것이 컨텍스트를 아끼는 가장 싼 방법입니다.
/context 내역에는 작업 시작 전에 MCP 도구, 커스텀 에이전트, 스킬이 각각 차지하는 토큰이 표시됩니다.영상 0:10 지점 보기 - 2
남은 공간과 autocompact 버퍼 읽는 법
/context 상단에는 모델의 창 크기와 사용량이 표시됩니다. 데모에서는 claude-opus-4-6이 21k/200k 토큰(11%)입니다. 마지막 행의 Autocompact buffer는 창이 진짜 가득 차기 전에 auto compact가 작동할 수 있도록 Claude Code가 확보해 둔 여유분입니다.
/context의 Autocompact buffer 행이 압축용으로 예약된 공간입니다. 여기서는 33k 토큰(16.5%)입니다.영상 2:38 지점 보기 - 3
채워가는 세션 알아보기
긴 세션은 도구 결과로 불어납니다. 파일을 읽을 때마다, 코드 리뷰 발견 목록마다, 수정마다 메시지가 창에 쌓입니다. 데모 세션은 코드 리뷰를 돌리고 「입력 검증 누락」「하드코딩된 JWT 시크릿」 같은 발견을 나열한 뒤 수정을 요청했습니다. 바로 한도에 부딪히기 쉬운 작업 유형입니다.
발견 목록과 수정이 따르는 코드 리뷰는 컨텍스트 창을 한도까지 밀어붙이는 전형적인 긴 세션 작업입니다.영상 0:24 지점 보기 - 4
리캡으로 남는 것 확인하기
대화가 길어지면 Claude Code 자체의 리캡 — 우선순위 순위, 모든 사용자 메시지, 남은 작업 — 이 요약이 지켜야 할 것을 보여줍니다. auto compact의 원리도 같습니다. 요청과 핵심 코드 조각은 살리고, 가장 먼저 버려지는 것은 오래된 도구 출력입니다.
우선순위 순위, 사용자 메시지, 남은 작업. 요약이 끌고 가야 할 상태가 바로 이런 것입니다.영상 0:50 지점 보기
의도적으로 컴팩트하기
- 5
슬래시 메뉴에서 /compact 고르기
/를 입력하고 설명을 읽어 보세요. /clear는 「Clear conversation history and free up context」, /compact는 「Clear conversation history but keep a summary in context」. 한 줄이 차이 전부입니다. compact는 요약을 치르고 연속성을 얻고, clear는 최대 공간을 삽니다. /compact는 /compact Focus on the API changes처럼 초점 지시도 받습니다.
슬래시 메뉴가 분명히 말해줍니다. /compact는 요약을 남기고, /clear는 전부 비웁니다.영상 0:09 지점 보기 - 6
Compacting conversation 스피너 이해하기
/compact를 실행하면 모델이 지금까지의 모든 내용을 읽고 요약하는 동안 「Compacting conversation…」이 표시됩니다. auto compact는 한도 근처에서 이와 동일한 루틴을 자동으로 돌립니다. v2.1.288에서는 auto 모드가 긴 대화에서 도구 호출을 실패 처리하는 대신 압축하도록 바뀌어, 작업 중간에 멈출 일이 줄었습니다.
수동이든 자동이든 압축 중에 보이는 것은 같은 「Compacting conversation…」입니다.영상 0:46 지점 보기 - 7
컴팩트 요약 읽기
출력은 「This session is being continued from a previous conversation that ran out of context」로 시작해 Primary Request and Intent, Key Technical Concepts, Files and Code Sections를 새 창으로 운반합니다. 전체 기록 대신 요약을 들고 작업을 이어가는 것이죠.
컴팩트 요약은 세션이 컨텍스트를 다 썼음을 밝힌 뒤 보존된 내용을 나열합니다.영상 0:48 지점 보기 - 8
전체 트랜스크립트에서 세부 사항 복구하기
요약에 필요한 것이 빠졌다면 압축 후 노트가 어디를 봐야 하는지 알려줍니다. 「read the full transcript at」에 이어지는 .jsonl 경로, 그리고 Current Work와 Optional Next Step 섹션입니다. 문서의 경고는 어느 쪽이든 유효합니다. 대화 초반의 상세 지시는 유실될 수 있으니 지속적인 규칙은 CLAUDE.md에 두세요.
Current Work, Optional Next Step, 트랜스크립트 경로. 압축 후의 세 가지 복구 지점입니다.영상 0:52 지점 보기
클리어, 위임, 복구
- 9
작업이 끝나면 /clear 사용하기
새 기능을 시작하나요? /clear는 대화를 통째로 지웁니다. 문서가 말하듯 비용은 사실상 없고, 큰 컨텍스트의 압축은 그 자체가 큰 요청입니다. 먼저 /rename로 세션 이름을 지어두면 나중에 /resume로 찾아올 수 있고, 이후 세션이 알아야 할 것은 CLAUDE.md에 적어두세요.
/clear는 요약 없이 새로 시작합니다. 먼저 이름을 바꿔두어야 /resume로 찾아올 수 있습니다.영상 3:14 지점 보기 - 10
무거운 읽기를 서브에이전트에 위임하기
서브에이전트는 자신만의 컨텍스트 창에서 실행되고 메인 세션에는 요약만 돌려줍니다. 데모처럼 code-reviewer 서브에이전트를 스폰하면 리뷰 출력이 내 창에 아예 들어오지 않습니다. 답만 필요하고 과정은 필요 없는 질문에 대한, 문서가 추천하는 해법입니다.
code-reviewer 서브에이전트 스폰. 작업은 메인 컨텍스트 창 밖에서 일어납니다.영상 2:50 지점 보기 - 11
서브에이전트에게 일시키고 답만 취하기
서브에이전트가 리팩터링 요약과 할 일 업데이트를 진행하는 동안 메인 창이 받는 것은 결과뿐입니다. 메인 스레드의 도구 출력이 줄면 auto compact는 더 늦게 — 혹은 영영 — 발동하지 않습니다. 긴 프로젝트가 버퍼에 닿지 않게 하는 가장 싼 방법입니다.
서브에이전트는 요약된 결론만 보고합니다. 중간 출력은 메인 세션에 저장되지 않았습니다.영상 2:53 지점 보기
auto compact vs /compact vs /clear vs /rewind
네 가지 명령은 Claude Code의 같은 구석에 있으면서 모두 대화를 리셋하거나 재구성하지만, 답하는 질문은 다릅니다. 언제 무엇이 정답인지 정리합니다.
- 1auto compact(자동): 대화가 컨텍스트 한도 — 또는 /autocompact로 정한 창 — 에 도달하면 발동해 오래된 기록을 요약하고 세션을 그대로 이어갑니다. v2.1.288부터는 auto 모드도 아주 긴 대화에서 도구 호출을 실패 처리하는 대신 압축합니다.
- 2/compact(수동, 요약 보존): 같은 요약을 필요할 때 실행합니다. 메뉴의 표현을 빌리면 「Clear conversation history but keep a summary in context」. 창을 넘었지만 같은 기능을 계속할 때 쓰고, /compact Focus on the test output처럼 초점을 지정할 수 있습니다.
- 3/clear(새 출발): 요약 없이 전부 지우고 비용은 없습니다. 큰 컨텍스트의 압축은 그 자체가 큰 요청이죠. 계획이 끝나고 다음 작업이 무관할 때 사용하며, 먼저 /rename해두면 /resume로 이전 세션을 불러올 수 있습니다.
- 4/rewind(되돌리기): 성격이 다릅니다. Esc 두 번으로 되감기(rewind) 메뉴를 열어 이전 체크포인트의 코드와 대화를 복원합니다. 최근 변경을 취소하고 싶을 때 쓰는 도구이지, 컨텍스트 한도를 넘어 작업을 이어가기 위한 도구가 아닙니다.
- 5Anthropic 공식 영상의 경험 법칙: 창을 넘어도 같은 기능의 연속성이 필요하면 compact, 새로 시작하면 clear, 이후 세션이 기억해야 할 것은 CLAUDE.md에 두세요. 어느 쪽에도 지워지지 않습니다.
하나 더 기억할 차이: 압축은 설계상 손실을 감수합니다. 요청과 핵심 코드 조각은 보존되지만 대화 초반의 상세 지시는 유실될 수 있습니다. 확보한 공간의 대가이며, 지속적인 규칙이 채팅 기록이 아니라 CLAUDE.md에 있어야 하는 이유입니다.
Compacting conversation이 느리거나 멈췄을 때 응급 처치
압축은 대화 전체를 읽기 때문에 큰 세션의 요약은 눈에 띄게 오래 걸립니다. 그 자체는 버그가 아닙니다. 여기서는 실제로 문제인 경우와 그 처치를 다룹니다.
- 1압축 대신 「Prompt is too long」 — 먼저 Claude Code를 업데이트하세요. v2.1.288에서 직전 응답의 토큰 사용량이 0일 때 긴 대화가 자동 압축 대신 이 에러로 실패하던 문제가 수정되었습니다. 구버전은 정확히 이 지점에서 멈춥니다.
- 2압축이 끝나자마자 컨텍스트가 다시 찬다(스래싱). 거대한 파일 읽기나 도구 출력 하나가 요약 직후 창을 다 채울 수 있습니다. Claude Code는 몇 번 시도 후 루프 대신 자동 압축을 멈추고 에러를 표시합니다. /clear, 작업 분할, 무거운 읽기의 서브에이전트 위임으로 대응하세요.
- 3게이트웨이나 프록시가 큰 요청을 거부하는 경우. 엔드포인트가 200K 토큰을 넘는 요청을 거절한다면 CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000을 설정해 게이트웨이 한도를 넘기 전에 압축이 발동하도록 하세요.
- 4/autocompact가 저장했다 하는데 적용되지 않는 경우. managed settings 같은 상위 스코프가 덮어쓰는 중이며, 그 경우 명령이 직접 알려줍니다. 환경 변수 CLAUDE_CODE_AUTO_COMPACT_WINDOW가 /autocompact를 포함한 모든 것을 이깁니다.
- 5정말로 그냥 느린 경우. 한도에 가까운 창의 요약은 큰 요청입니다. /compact를 다시 돌리기 전에 잠시 기다리고, 요약이 정말 필요 없다면 /clear가 즉각적이고 공짜입니다. 무관한 MCP 서버를 꺼두면 이후의 모든 압축도 짧아집니다.
같은 세션에서 압축이 계속 실패한다면 수동 탈출로가 있습니다. /rename로 이름 붙이고, /clear하고, 나중에 /resume하거나 — 지난 번 생성된 컴팩트 요약에서 이어가세요. 디스크에는 아무것도 잃지 않습니다. 압축이 다시 만드는 것은 대화 메모리뿐입니다.