Claude Code의 Auto-Compact를 실제로 보존해야 하는 내용에 맞추는 방법 (2026년 가이드)

Anthropic은 이 과정을 완곡한 표현 없이 다음과 같이 설명합니다. Claude Code는 "오래된 도구 출력을 먼저 지운 다음, 필요한 경우 대화를 요약합니다. 사용자의 요청과 핵심 코드 스니펫은 보존되지만, 대화 초반의 세부 지침은 손실될 수 있습니다."

마지막 구절이 바로 우리가 겪는 경험의 전부입니다. 요약은 특정 방향으로 정보가 손실됩니다. 즉, 일어난 일의 대략적인 형태는 유지하되 초반에 언급한 세부 사항의 정확성은 떨어뜨립니다. 대화 시작 3분 만에 언급한 제약 조건은 요약 과정에서 압축되기 딱 좋은 세부 정보이며, 무엇이 사라졌는지 알려주는 알림도 없습니다.

하지만 모든 내용이 요약기(summariser)를 거치는 것은 아닙니다. Anthropic은 compaction 이후 각 콘텐츠 유형에 어떤 일이 일어나는지 메커니즘별 표를 공개하고 있으며, 여기서 흥미로운 부분은 요약에 전혀 영향을 받지 않는 항목들입니다:

시스템 프롬프트 및 출력 스타일: "둘 다 여전히 적용됨." 프로젝트 루트의 CLAUDE.md 및 범위 미지정 규칙: "디스크에서 다시 주입됨." 자동 메모리(Auto memory): "디스크에서 다시 주입됨." Claude가 계획 모드(plan mode)에서 작성한 계획: "디스크에서 다시 주입됨." paths: 프런트매터가 포함된 규칙: "Claude Code가 해당 규칙과 일치하는 파일을 읽을 때 다시 로드함." 하위 디렉터리의 중첩된 CLAUDE.md 파일: "Claude Code가 해당 하위 디렉터리의 파일을 읽을 때 다시 로드함." Claude가 읽거나 편집한 파일: "Claude Code가 가장 최근에 수정된 파일부터 최대 5개까지 다시 읽음."

이 목록을 설계 지침으로 받아들이십시오. 실제로 그렇기 때문입니다. 디스크에 존재하는 것은 무엇이든 다시 돌아옵니다. 대화 중에 직접 입력했기 때문에 존재하는 내용만 요약됩니다. Anthropic은 몇 줄 앞에서 다음과 같이 결론을 내립니다. "대화 기록에 의존하기보다 영구적인 규칙은 CLAUDE.md에 작성하십시오."

이는 긴 컨텍스트(context)가 메모리(memory)와 같지 않은 이유에 대한 솔직한 답변이기도 합니다. 이 점은 이 도구뿐만 아니라 전반적인 AI 시스템에 적용되는 사실이며, 저희는 왜 긴 컨텍스트 창이 메모리가 아닌가에서 이를 자세히 설명한 바 있습니다.

compact가 실행되기 전에 새 세션 시작하기. 이 방법은 효과가 있지만, 원치 않는 대화 내용과 함께 계속 유지하고 싶었던 대화 내용까지 모두 버리게 됩니다. 또한 문제를 다음 세션으로 미룰 뿐이며, 다음 세션은 이전 맥락 없이 시작됩니다. 이는 Claude Code 세션 간에 컨텍스트 공유하기에서 다룬 조율 문제입니다.

auto-compaction 끄기. 이 옵션도 사용 가능하지만, 그 결과는 문서에 명시되어 있습니다. "auto-compaction을 끄면 세션이 compacting 대신 컨텍스트 제한 에러와 함께 200K 경계에서 중단됩니다." 한계를 피한 것이 아니라, 정보 손실이 있는 요약 대신 강제 중단을 선택한 것뿐입니다.

창 크기를 최대한 높이기. 이 역시 문서화되어 있으며 한계가 있습니다. "auto-compact 창을 200K 이상으로 설정해도 제한이 풀리지 않습니다. Claude Code는 해당 창을 모델의 컨텍스트 창 크기로 제한하기 때문입니다." 창 크기 설정은 실제 한계의 일부를 조정하는 것일 뿐, 한계를 넘어설 수 있는 방법이 아닙니다.

기본값이 단 하나의 숫자라고 가정하기. 이는 모델과 환경에 따라 다릅니다. Anthropic의 기준에 따르면 설정이 없을 때 "Claude Code는 대화가 모델의 컨텍스트 제한에 도달할 때 compact를 수행"하며, 클라우드 세션, 200K 경계에서 compact를 수행하는 일부 모델, 그리고 기본 1M 창을 가진 모델(기본적으로 창이 가득 차기 전인 약 967K 토큰에서 compact 수행)에 대한 예외가 있습니다.

/compact 무작정 실행하기. 아무것도 안 하는 것보다는 낫지만, 대부분의 사람들이 존재조차 모르는 제어 기능인 focus 옵션과 함께 사용할 때 훨씬 더 효과적입니다.

compaction이 일어날 때마다 제약 조건 다시 붙여넣기. 이는 진짜 해결책이 무엇인지 보여주는 임시방편입니다. 요약 후에 규칙을 다시 언급해야 한다면, 그 규칙은 디스크에 있어야 마땅합니다. 사람들이 이전 명령어를 찾기 위해 계속 스크롤을 올리는 현상에도 동일한 원리가 적용되며, 이에 대해서는 Claude Code가 이전 명령 기록을 잃어버리는 이유에서 살펴보았습니다.

다음 순서대로 두 가지 제어 기능을 사용합니다.

1단계: 살아남아야 하는 규칙은 대화가 아닌 디스크에 저장하기

이 단계는 가장 효과적이면서도 비용이 들지 않는 방법입니다. 프로젝트 루트의 CLAUDE.md 및 범위 미지정 규칙에 있는 모든 내용은 compaction 이후 디스크에서 다시 주입됩니다. 자동 메모리도 디스크에서 다시 주입됩니다. 계획 모드에서 작성된 계획도 디스크에서 다시 주입됩니다. 경로 범위 규칙은 일치하는 파일을 읽을 때 다시 로드되고, 중첩된 CLAUDE.md 파일은 해당 하위 디렉터리의 파일을 읽을 때 다시 로드됩니다.

따라서 실질적인 규칙은 다음과 같습니다. 세션 중에 같은 말을 두 번 하고 있다면, 그것은 메시지가 아니라 CLAUDE.md에 작성해야 할 내용입니다. 이렇게 하면 요약 과정에서 압축될 수 있는 내용이 매번 그대로 다시 로드되는 내용으로 전환됩니다.

그다음 요약기에 직접 지시하는 제어 기능을 추가합니다. Anthropic은 다음과 같이 설명합니다. "compaction 중에 보존할 내용을 제어하려면 CLAUDE.md에 'Compact Instructions' 섹션을 추가하거나, focus 옵션을 지정하여 /compact를 실행하십시오(예: /compact focus on the API changes)." Compact Instructions 섹션은 해당 프로젝트에서 향후 수행될 모든 compaction에 적용되는 상시 지침으로, 보존해야 할 내용을 세네 줄로 작성해 두면 됩니다.

2단계: 우선순위를 파악하고 창 크기를 설정할 위치 선택하기

Anthropic은 세 가지 설정 위치를 문서로 제공하며, 이들 간의 우선순위는 명확합니다.

현재 세션 및 향후 세션에 적용하려면 값을 지정하여 /autocompact를 실행합니다. Claude Code는 "이를 사용자 설정에 autoCompactWindow로 저장하고 현재 세션에 적용"합니다. 단, 디버깅 전에 알아두어야 할 주의 사항이 있습니다. "관리형 설정(managed settings)과 같이 더 높은 우선순위의 설정 범위에서 해당 키를 설정한 경우, 명령어는 입력한 값을 저장하지만 세션은 해당 범위의 창 크기를 유지하며 명령어 실행 시 이 사실을 알려줍니다." /autocompact auto를 실행하면 "모델에 맞게 조정된 창 크기"로 돌아갑니다.

단 한 번의 실행에만 적용하려면 --autocompact 플래그를 전달합니다. 이는 "저장된 설정을 변경하지 않고 해당 실행에 대해서만 설정을 재정의(override)"합니다. 이 플래그는 명령어에는 없는 특징이 있습니다. "/autocompact와 달리, 이 플래그는 관리형 설정과 같은 더 높은 우선순위의 설정 범위에 의해 선점(preempt)되지 않습니다."

스크립트 및 클라우드 환경의 경우 CLAUDE_CODE_AUTO_COMPACT_WINDOW 환경 변수를 설정합니다. 이는 다른 모든 설정보다 위에 위치합니다. "이 변수가 설정되어 있는 동안에는 명령어, 플래그, 사용자 설정보다 우선하며, /autocompact를 실행하면 창 크기를 변경하는 대신 재정의 상태임을 보고합니다."

세 가지 레버와 하나의 순서: 환경 변수 > 플래그 > 명령어 > 저장된 설정 순이며, 관리형 설정은 명령어는 선점할 수 있지만 플래그는 선점할 수 없습니다. 설정한 대로 창 크기가 적용되지 않는다면 이 목록이 디버깅 순서가 됩니다.

3단계: 창 크기가 문제가 아님을 나타내는 에러 인식하기

하나의 메시지는 별도의 단계로 다룰 가치가 있습니다. 왜냐하면 사람들이 잘못된 제어 기능을 찾게 만들기 때문입니다. Anthropic은 다음과 같이 설명합니다. "Autocompact is thrashing: the context refilled to the limit...이라는 메시지가 표시되면 자동 compaction은 성공했으나 파일이나 도구 출력으로 인해 컨텍스트 창이 즉시 여러 번 연속해서 다시 가득 찬 것입니다. Claude Code는 진행이 되지 않는 루프에서 API 호출을 낭비하지 않기 위해 재시도를 중단합니다."

Thrashing(스래싱)은 compaction이 작동한 직후 거대한 무언가가 다시 들어왔음을 의미합니다. 창 크기를 늘리는 것은 도움이 되지 않으며, 해결책은 다시 채워지는 것을 막는 것입니다. Anthropic이 제안하는 방법은 문제가 되는 출력을 제외하는 집중형(focused) compaction을 실행하는 것입니다. "큰 출력을 제외하는 focus 옵션과 함께 /compact를 실행하십시오. 예를 들어 /compact keep only the plan and the diff와 같이 실행합니다."

함께 알아두어야 할 메시지가 하나 더 있습니다. /compact 실행 시 "Not enough messages to compact."가 반환된다면, 대화의 "턴(turn) 수가 너무 적어 요약할 수 없는 상태입니다. 단 한 번의 대용량 붙여넣기로 인해 컨텍스트가 가득 찬 경우에도 이런 일이 발생할 수 있습니다." 증상은 다르지만 진단은 동일합니다. 문제는 창 크기가 아니라 단 하나의 거대한 객체입니다.

위의 모든 단계는 대화 속의 사실을 더 오래 지속되는 곳으로 옮기는 과정입니다. CLAUDE.md는 단일 기기의 단일 리포지토리 범위 내에서만 지속됩니다. MemoryLake는 사용자가 직접 더 오래 지속되는 사실을 기록하는 저장소로, 세션과 무관하며 연결된 모든 어시스턴트에서 읽을 수 있습니다. 사용자는 자신의 언어로 직접 항목을 작성합니다. Anthropic의 시스템이나 다른 벤더의 저장소에서 데이터를 읽거나 쓰거나 삭제하지 않으므로, 세션, 대화 기록 및 규칙 파일은 전적으로 Claude Code의 자체 제어 하에 유지됩니다.

1단계: API 키 생성하기

대시보드에서 키를 생성합니다. 이 키를 통해 현재 세션, 다음 compaction 이후의 세션, 그리고 다른 리포지토리의 세션이 모두 동일한 사실 집합에 접근할 수 있게 됩니다.

2단계: 첫 번째 메모리 업로드하기

compaction 이후에 다시 언급해야 했던 내용부터 시작하십시오. 제약 조건, 결정 사항과 그 이유, 이미 제외된 접근 방식 등이 이에 해당합니다. 보통 12개 정도의 짧은 항목이면 하나의 프로젝트를 커버할 수 있습니다. 서술형이 아닌 날짜가 포함된 진술문 형태로 작성하십시오.

3단계: AI 및 에러전트 연결하기

Claude Code가 이 레이어를 가리키도록 설정하여, 요약에서 살아남는 방식이 아니라 세션 시작 시점에 해당 사실들이 로드되도록 하십시오. 그런 다음 확실한 방법으로 테스트해 보십시오. 의도적으로 세션을 compact하고 그 사실 중 하나를 물어보십시오. 답변을 얻는다면, 이제 compaction은 무엇을 보존할지 결정하는 유일한 요소가 아니게 된 것입니다.

첫 번째 변화는 compaction이 더 이상 무작위로 느껴지지 않는다는 점입니다. 사용자가 확인하고 설정할 수 있는 창 크기에서 실행되며, 파일을 다시 주입하면서 대화를 요약하고, thrashing이 발생할 때 이를 알려줍니다. 이는 세 가지 개별적인 동작이며 각각에 맞는 세 가지 대응 방법이 존재합니다.

두 번째는 CLAUDE.md가 올바르게 사용된다는 점입니다. 다시 주입되는 항목들의 목록을 파악하고 나면, 이 파일은 프로젝트의 사소한 정보를 적어두는 곳이 아니라 "요약 과정에서 반드시 살아남아야 하는 내용"을 담는 곳이 되며, Compact Instructions 섹션은 요약기에 직접 지시를 내리는 통로가 됩니다.

세 번째는 긴 세션을 다시 유용하게 활용할 수 있게 된다는 점입니다. 매 시간마다 새 세션을 시작하려는 본능은 compaction을 신뢰하지 못하는 데서 비롯됩니다. 이를 제어하는 것이 피하는 것보다 비용이 적게 들며, 새 세션이 버리는 연속성을 유지할 수 있습니다. 세션을 분리하는 것이 정말 올바른 선택인 경우, 이는 다른 상속 규칙을 가진 별개의 작업이며, 이에 대해서는 포크된 Claude Code 세션이 인계받는 내용에서 다루었습니다.

네 번째는 에러 메시지가 유용해진다는 점입니다. Thrashing 및 "Not enough messages to compact"는 모두 설정의 문제가 아니라 너무 큰 단일 객체를 가리키며, 이를 알면 엉뚱한 수치를 조정하느라 오후 시간을 낭비하지 않을 수 있습니다. compaction 과정에서 어떤 내용을 버려도 되는지에 대한 더 넓은 주제는 다른 도구를 통해 compaction에서 살아남을 내용 결정하기에서 다루었습니다.

두 번 말하게 된다면 기록하십시오. 세션 중에 다시 언급하는 내용은 모두 CLAUDE.md에 작성해야 하며, 그래야 요약되지 않고 디스크에서 다시 주입됩니다.

프로젝트별로 Compact Instructions 섹션을 추가하십시오. 이는 focus 옵션을 지정한 /compact 명령어의 상시 적용 버전이며, 향후 모든 compaction에 적용됩니다.

조정하기 전에 우선순위를 파악하십시오. 환경 변수, 실행 플래그, 명령어, 저장된 설정 순이며, 관리형 설정은 명령어를 선점할 수 있습니다.

정상 상태로 돌아가려면 /autocompact auto를 사용하십시오. 임의로 선택한 숫자가 아닌 모델에 맞게 조정된 창 크기로 세션을 되돌립니다.

Thrashing을 콘텐츠의 문제로 취급하십시오. compaction은 성공했으나 큰 객체가 창을 다시 채운 것입니다. focus 옵션을 지정한 compaction으로 해당 객체를 제외하십시오.

세션 간에 공유되는 사실은 리포지토리 외부에 보관하십시오. CLAUDE.md는 프로젝트 내의 compaction에서는 살아남지만, 다른 프로젝트나 다른 도구로 전달되지는 않습니다.

Claude Code의 auto-compact에는 두 가지 다이얼이 있지만 대부분의 사람들은 둘 다 사용하지 않습니다. 트리거는 auto-compact 창으로, /autocompact, --autocompact 플래그 또는 CLAUDE_CODE_AUTO_COMPACT_WINDOW를 통해 설정할 수 있으며, 이들 간에는 문서화된 우선순위가 존재하고 모델 자체의 컨텍스트 창 크기로 제한됩니다. 보존되는 내용은 디스크에 있는 항목(프로젝트 규칙, 자동 메모리, 계획 모드 계획, 경로 범위 규칙 등은 모두 다시 주입됨)과 Compact Instructions 섹션 또는 focus 옵션이 지정된 /compact에 의해 결정됩니다.

손실되는 내용은 Anthropic이 명확히 밝히고 있습니다. 요청과 핵심 코드 스니펫은 보존되지만 "대화 초반의 세부 지침은 손실될 수 있습니다." 이는 요약의 본질이지 결함이 아니며, 벤더의 조언이 정답입니다. 대화 기록에 의존하기보다 영구적인 규칙은 파일에 작성하십시오.

그다음 단계는 간단하지만 시도해 볼 가치가 있습니다. 파일은 단일 프로젝트 내부의 compaction에서만 살아남습니다. 다음 분기에도 다른 리포지토리에서, 다른 어시스턴트와 함께 계속 적용해야 할 결정 사항이라면 세션의 경계가 전혀 닿지 않는 곳에 보관할 가치가 있습니다.