클로드 코드 유휴 압축: 맥락 복구와 idleCompaction 설정 구분

클로드 코드에 작업 방향과 제외할 방법을 설명한 뒤 쉬었다 돌아왔다고 가정해보겠습니다. 같은 대화인데 이미 접어 둔 방법을 다시 권하거나 중요한 조건을 빼먹는다면, 설명을 반복하기 전에 유휴 압축 여부를 확인할 필요가 있습니다.

자리를 비운 사이 대화를 요약하는 유휴 압축이 있었는지부터 보겠습니다. 다만 여기에는 서로 다른 일이 두 개 들어 있습니다. 이미 줄어든 작업 맥락을 다시 맞추는 일, 그리고 다음 휴식 때 같은 압축을 하지 않도록 설정하는 일입니다. 앞으로의 동작을 바꾸는 스위치가 지난 대화까지 되돌려 주지는 않습니다.

유휴 압축 표시와 설치 버전을 확인합니다

확인할 문구는 Compacted while idle, before the prompt cache expired입니다. 프롬프트 캐시가 만료되기 전에 유휴 상태에서 압축했다는 뜻입니다. 쉬고 돌아온 뒤 맥락이 달라졌고 이 표시도 있다면 유휴 압축을 살펴볼 이유가 생깁니다. 반대로 답변이 마음에 들지 않는다는 이유만으로 모든 문제를 여기에 맡겨 버리면 진단이 너무 편리해집니다.

개발사 저장소에 올라온 별도 보고에서는 macOS에서 2.1.286으로 업데이트한 뒤, 오래 열어 둔 약 20개 세션 가운데 7개가 유휴 상태에서 압축됐습니다. 보고자가 아쉬워한 것은 단순히 대화가 짧아졌다는 사실이 아니었습니다. 구체적으로 내렸던 지시, 결정을 내린 이유, 함께 정한 작업 방식이 이후 세션이 보는 요약에서 빠졌다는 점입니다. 코딩을 맡길 때는 “무엇을 만든다” 못지않게 “왜 저 방법은 안 쓴다”가 중요하니, 결과만 남은 요약으로는 같은 출발선에 서기 어렵습니다.

이 보고는 대화 원문이 삭제됐다는 말과는 구분해야 합니다. 보고자는 전체 대화 기록인 transcript가 디스크에 남아 있었고, 이를 보고 작업 맥락을 다시 구성했다고 밝혔습니다. 기록이 보관되어 있는 것과 현재 답변에 쓰는 맥락에 내용이 포함된 것은 별개입니다.

그렇다고 휴식 시간을 재서 원인을 판정할 수 있는 것도 아닙니다. 2026년 10월 3일 개발사 저장소 협업자 blois가 설명한 당시 대상은 200k+, 즉 20만 토큰 이상의 큰 컨텍스트였습니다. 이를 모든 버전·대화 크기에 적용되는 “55분 쉬면 무조건 압축” 규칙으로 외워 둘 일은 아닙니다. 휴식에 타이머를 걸기보다, 실제 표시와 설치 버전을 확인하는 편이 낫습니다.

2.1.290부터 추가된 설정과 로그 해석

이 동작을 원하지 않는 사람을 위한 선택지는 추가됐습니다. 2026년 10월 6일 blois는 2.1.290에 idleCompaction 설정이 추가돼 유휴 압축을 끌 수 있다고 안내했습니다. 이후 문제를 제기한 보고자도 2.1.291에서 "idleCompaction": false로 해결됐다고 확인하며 이슈를 완료 처리했습니다.

예전 기록을 들여다보는 경우에는 작은 함정도 있습니다. 초기 보고에서는 직접 /compact를 실행하지 않았는데 압축 원인을 나타내는 trigger가 manual로 남았습니다. 2.1.290에서는 이 값이 auto로 바뀌었습니다. 오래된 로그의 manual만 보고 본인이 무심코 명령을 눌렀다고 결론낼 필요는 없고, 바뀐 auto 역시 유휴 압축만을 위한 전용 표시는 아닙니다.

먼저 터미널에서 아래 명령으로 설치 버전을 확인합니다. 이 글의 설정은 해당 기능이 추가된 2.1.290 이상을 대상으로 합니다. 그보다 오래된 버전이라면 설치 방식에 맞춰 업데이트하는 것이 먼저입니다.

claude --version

전체 프로젝트와 개인 로컬 설정의 범위

앞으로 유휴 압축을 막기로 했다면, 이제 설정 파일의 적용 범위를 고를 차례입니다. 이 컴퓨터에서 본인이 사용하는 모든 프로젝트에 적용할지, 지금 작업하는 프로젝트에만 적용할지에 따라 파일이 달라집니다. 한 프로젝트의 사정으로 고른 설정을 다른 작업에도 일괄 배포할 이유는 없습니다.

적용하려는 범위	사용할 개인 설정 파일
이 컴퓨터에서 사용하는 내 모든 프로젝트	~/.claude/settings.json
이 프로젝트에서만 사용하는 개인 설정	프로젝트 루트의 .claude/settings.local.json

이름이 비슷한 .claude/settings.json은 팀과 공유하는 프로젝트 설정입니다. 혼자 유휴 압축을 끄려는 일이라면 위의 개인 설정 중에서 고르는 편이 맞습니다. .claude/settings.local.json을 직접 만들 때는 .gitignore 처리도 확인해야 합니다. Claude Code가 설정을 저장하며 자동으로 제외해 주는 경우와, 사람이 직접 파일을 만드는 경우는 같지 않습니다.

또 ~/.claude.json은 로그인·상태 등을 담는 별도 파일이지, 이 설정을 넣을 장소가 아닙니다. 점 하나와 경로 한 토막이 제법 큰 차이를 만듭니다. 여기서 고르는 것은 로컬 환경의 설정 범위이며, 이 파일을 바꿨다고 클라우드 세션까지 같은 값이 적용된 것으로 보면 안 됩니다.

기존 JSON을 보존하며 설정하고 확인합니다

선택한 설정 파일에 넣을 값은 아래와 같습니다. 새로 만드는 빈 파일에 사용할 최소 전체 예시입니다.

{
  "idleCompaction": false
}

기존 파일을 위 예시로 통째로 바꾸면 다른 옵션을 잃습니다. 기존 최상위 JSON 객체의 다른 항목은 그대로 두고 idleCompaction만 추가하거나 같은 키의 값을 false로 바꿉니다. env 등 다른 항목 안에 넣는 값은 아닙니다.

파일은 엄격한 JSON 문법을 지켜야 합니다. 항목 사이에는 쉼표가 필요하지만 마지막 항목 뒤에는 쉼표를 붙이지 않고, 설명용 주석도 넣지 않습니다. false는 따옴표 없는 불리언 값입니다. 문자열인 "false"로 바꾸거나 같은 키를 중복해서 추가하지 말아야 합니다. 바꿀 내용은 작으니 기존 파일을 따로 보관해 두고 해당 항목만 손대는 편이 낫습니다.

저장 뒤에는 Claude Code 안에서 /status를 열어 Setting sources에 해당 설정 출처가 읽혔는지 확인합니다. 이것은 파일이 읽혔다는 확인이지, idleCompaction의 실제 적용값을 확인한 것은 아닙니다. 오류나 거부된 항목은 터미널의 claude doctor로 살펴볼 수 있습니다.

여러 범위에서 같은 키를 지정했다면 우선순위도 봐야 합니다. 사용자 전체 설정보다 프로젝트·로컬 설정이나 명령행 옵션이 우선할 수 있고, 조직 관리 정책이 위에 있으면 개인 파일에 적었다고 무조건 덮어쓸 수는 없습니다. 설정을 더 세게 쓰는 방법이 필요한 것이 아니라, 어느 값이 적용되는지를 구분해야 하는 문제입니다.

빠진 작업 맥락은 원자료와 대조합니다

앞으로의 설정과는 별개로, 이미 진행 중인 작업에서 무엇이 빠졌는지도 짚어 두면 좋습니다. 코드 파일을 다시 읽으면 현재 구현은 확인할 수 있지만, 그 구현을 택한 이유나 일부러 하지 않기로 한 작업까지 파일에 적혀 있으리라는 보장은 없습니다. “파일을 읽었으니 다 기억하겠지” 하고 바로 수정을 맡기면, 빠진 전제를 안고 다음 단계로 넘어갈 수 있습니다.

복귀할 때는 원본 대화·작업 메모·실제 파일을 대조해 현재 목표, 중요한 결정과 그 이유, 관련 파일, 마지막 테스트 결과, 다음 작업을 다시 맞추는 편을 권합니다. 클로드에게 이해한 상태를 설명하게 한 뒤 중요한 조건이 실제로 포함됐는지 확인합니다. 필요한 파일을 다시 읽히고 빠진 결정을 보충하되, 원자료에서 찾지 못한 내용을 추측으로 채우지는 않습니다.

설정 파일을 저장한 즉시, 이미 열어 둔 세션까지 바뀌었다는 전제로 자리를 뜨지는 말아야 합니다. 설정 편집은 대체로 자동으로 다시 읽히지만, 이 항목의 실행 중 반영까지 단정하기는 어렵습니다. 진행 중인 변경사항과 중요한 작업 상태를 먼저 남긴 뒤, 설정을 읽힌 새 세션에서 이어갈 준비를 하는 쪽이 안전합니다. 새 세션 역시 앞선 맥락을 저절로 물려받는 것으로 생각하지 말고, 앞에서 정리한 근거를 함께 전달합니다.

총평: 압축 설정과 맥락 복구를 따로 판단합니다

idleCompaction을 끄는 것은 유휴 압축에 대한 선택입니다. 컨텍스트가 한계에 가까워질 때의 일반 자동 압축과 직접 실행하는 /compact는 별개로 남습니다. 일반 자동 압축 설정인 autoCompactEnabled까지 함께 끌 이유는 없습니다. 쉬는 사이의 압축을 피하려다 문맥창의 한계를 다루는 장치까지 건드리는 것은, 원하는 일보다 훨씬 큰 변경입니다.

유휴 압축은 캐시 만료 뒤 긴 맥락을 다시 처리하는 비용을 줄이려는 동작입니다. 끝난 작업을 정리할 때는 유용할 수 있지만, 결정 이유와 세부 지시가 많은 진행 중 작업에서는 중요한 전제를 다시 설명하는 부담이 생길 수 있습니다. 저는 비용과 작업 맥락 가운데 어느 쪽을 더 아끼고 싶은지에 따라 고를 설정이라고 봅니다. 항상 켜거나 꺼야 하는 정답은 아닙니다.

그리고 이 설정 하나가 무제한 기억을 만들어 주지는 않습니다. 이미 빠진 내용은 원자료로 보완하고, 앞으로의 유휴 압축은 버전과 범위를 골라 설정합니다. 줄여야 할 것은 사람의 휴식 시간이 아니라, 돌아온 뒤 같은 설명을 다시 하는 일입니다.