[만드는 기록] Claude Code v2.1.299: 유휴 압축 끄기와 @ 파일 멘션 설정법

안녕하세요, muaco입니다.

이 글을 따라 하면 달라지는 두 가지

이 글을 따라 하면 Claude Code v2.1.299의 새 설정 두 가지를 직접 켜고 끌 수 있습니다. 하나는 @ 파일 멘션이 파일 내용 대신 경로만 넘기게 하는 환경 변수입니다. 다른 하나는 오래 놔둔 긴 대화를 미리 요약해 두는 유휴 압축의 기준선 조정과 끄기입니다.

기준은 v2.1.299 릴리스 노트와 2026년 10월 현재의 공식 문서입니다.

시작 전에 갖출 준비물

계정: Pro, Max, Team, Enterprise 요금제나 Console 계정이 필요합니다. 무료 claude.ai 요금제로는 Claude Code를 쓸 수 없습니다.
버전: 파일 멘션 변수는 v2.1.299부터 있습니다. 유휴 압축 설정은 v2.1.290 이상이면 되므로, 이 글은 v2.1.299 이상을 기준으로 합니다.
터미널: 명령을 글자로 쳐서 컴퓨터를 다루는 창입니다. 맥은 '터미널' 앱, 윈도는 PowerShell을 엽니다.

설정은 두 군데에 적습니다. 첫째는 환경 변수로, 프로그램이 켜질 때 먼저 들여다보는 쪽지라고 보면 됩니다. 둘째는 설정 파일 settings.json이며, 내 계정 전체에 걸리는 사용자 설정은 ~/.claude/settings.json에 있습니다.

~는 내 홈 폴더를 뜻합니다. 윈도에서는 사용자 폴더 아래의 .claude 폴더입니다.

따라 하기: 버전 확인부터 끄기까지

준비: 버전 확인

따라 하기

터미널을 열고 아래 명령을 입력하세요. 2.1.299 (Claude Code)처럼 2.1.299 이상의 숫자가 나오면 다음 묶음으로 넘어갑니다.
```
claude --version
```
숫자가 낮으면 아래 명령으로 바로 올리세요.
```
claude update
```
Successfully updated from으로 시작하는 줄이 뜨면 성공입니다.

@ 파일 멘션이 경로만 넘기게 하기

@ 파일 멘션은 입력창에 @를 치고 파일 경로를 붙여 그 파일을 가리키는 방식입니다. 기본값에서는 서류를 통째로 복사해 건네듯, 파일이 25,000토큰(AI가 글을 세는 단위) 한도 안이면 내용이 메시지에 그대로 실립니다. 변수를 켜면 서랍 위치만 알려 주고, Claude가 파일 도구로 직접 꺼내 읽습니다.

어느 쪽이 나은지는 문서에 나와 있지 않습니다. 다만 기본값은 파일을 통째로 실으므로, 큰 파일을 자주 가리켜 대화가 금방 찬다면 시험해 볼 만합니다. 같은 질문을 두 방식으로 던진 뒤 /context로 대화가 쓴 공간을 견줘 보고 고르세요.

따라 하기

먼저 지금 열린 터미널 창에서만 변수를 켜 봅니다. 창을 닫으면 사라지므로 시험용으로 알맞습니다. 맥, 리눅스, WSL(윈도 안에서 리눅스를 돌리는 기능)에서는 이렇게 입력합니다.
```
export CLAUDE_CODE_DISABLE_FILE_MENTIONS=1
```
윈도 PowerShell에서는 이렇게 씁니다.
```
$env:CLAUDE_CODE_DISABLE_FILE_MENTIONS = "1"
```
변수가 들어갔는지 확인하세요. 아래 명령에 1이 찍히면 됩니다(PowerShell은 echo $env:CLAUDE_CODE_DISABLE_FILE_MENTIONS).
```
echo $CLAUDE_CODE_DISABLE_FILE_MENTIONS
```
같은 창에서 claude를 실행하고, 입력창에 @를 쳐서 파일 하나를 고르세요. 경로 후보가 뜨면 Enter나 Tab으로 고른 뒤 Enter를 한 번 더 눌러 보냅니다.
Claude가 답하기 전에 파일 도구로 그 파일을 직접 읽는지 보세요. 폴더를 가리켜도 파일 목록 대신 경로만 넘어갑니다.
이미 ~/.claude/settings.json이 있다면 새 파일로 덮어쓰지 말고 env 안에 한 줄만 보태세요. 덮어쓰면 그동안의 설정이 사라집니다. 계속 쓰려면 사용자 설정에 이렇게 적습니다.
```
{
  "env": {
    "CLAUDE_CODE_DISABLE_FILE_MENTIONS": "1"
  }
}
```
원래대로 돌리려면 env에서 그 줄을 지우고 Claude Code를 다시 켜세요. 1단계에서 변수를 켠 창이라면 그 창에는 변수가 아직 남아 있습니다. 창을 새로 열거나, 그 창에서 unset CLAUDE_CODE_DISABLE_FILE_MENTIONS(PowerShell은 Remove-Item Env:CLAUDE_CODE_DISABLE_FILE_MENTIONS)로 먼저 지우세요. 2단계 명령에 1이 찍히지 않으면 지워진 상태입니다.

유휴 압축 조건 확인하고 기준선 바꾸기

단골 식당을 떠올려 보세요. 주방이 방금 받은 긴 주문서를 잠시 기억해 두면, 손님이 한 줄을 더 주문해도 처음부터 다시 읽지 않습니다. Claude Code도 대화를 이렇게 기억해 두는데, 이를 프롬프트 캐시라고 부릅니다.

기억에는 유효 시간이 있고, 이를 TTL이라고 합니다. 구독 요금제를 한도 안에서 쓴다면 기본 대화의 TTL은 한 시간입니다. 그 시간이 지나면 어떻게 될까요?

다음 메시지가 긴 대화를 처음부터 다시 처리하느라 느려집니다. 그래서 Claude Code는 TTL이 끝나기 직전에, 회의록 전문을 요점 정리로 바꾸듯 대화를 요약해 둡니다. 대화가 쉬는 동안 하는 압축이라 이름도 유휴 압축.

조건은 다섯 가지이고, 모두 채워야 돕니다. 압축이 안 걸렸다면 아래를 하나씩 짚어 보세요.

터미널에서 대화형으로 쓰는 세션입니다.
대화가 한 시간짜리 프롬프트 캐시를 쓰고 있습니다.
Claude Code가 Anthropic에서 기능 플래그(기능을 켜고 끄는 스위치 목록)를 받아 올 수 있습니다.
대화 크기가 기준선에 닿았습니다. 기본값은 200,000토큰입니다.
마지막 요청 뒤 약 54분이 지났고, 그때 컴퓨터가 깨어 있습니다.

따라 하기

긴 대화가 열린 세션에서 /usage를 입력하세요. Prompt cache (main) 줄 끝에 1h TTL이 보이면 둘째 조건은 채운 상태입니다.
/context로 지금 대화가 공간을 얼마나 쓰는지 보세요. 기준선에 한참 못 미친다면 유휴 압축은 아직 걸리지 않습니다.
기준선을 낮추려면 사용자 설정의 env에 CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS를 넣습니다. 컨텍스트 창(한 번에 담을 수 있는 대화의 최대 크기)이 200K인 모델은 200,000토큰에 닿기 전에 자동 압축이 먼저 걸려, 기본값으로는 대상이 되지 않기 때문입니다. 앞에서 넣은 줄과 함께 두면 이런 모양입니다.
```
{
  "env": {
    "CLAUDE_CODE_DISABLE_FILE_MENTIONS": "1",
    "CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS": "150000"
  }
}
```
값은 쉼표 없이 숫자만 적습니다. 100000보다 작으면 100000으로 올려 적용되고, 숫자가 아닌 값은 무시됩니다.
컴퓨터를 켜 둔 채 54분 넘게 자리를 비웠다가 돌아오세요. 대화에 Compacted while idle, before the prompt cache expired가 떠 있으면 유휴 압축이 제대로 돈 상태입니다.

유휴 압축 끄기

따라 하기

설정 파일에 "idleCompaction": false를 넣으세요. 사용자, 프로젝트, 로컬 설정 어디에 넣어도 되며, 모든 프로젝트에서 끄려면 사용자 설정에 둡니다.
```
{
  "idleCompaction": false
}
```
env 블록이 이미 있다면 그 안이 아니라 바깥 중괄호 안에 나란히 두세요. env 안은 환경 변수 자리라서 설정 키를 넣으면 엉뚱한 곳에 적은 셈이 됩니다.
```
{
  "env": {
    "CLAUDE_CODE_DISABLE_FILE_MENTIONS": "1"
  },
  "idleCompaction": false
}
```
끈 뒤 54분 넘게 비웠다 돌아와도 압축 문구가 뜨지 않으면 적용된 상태입니다. 대신 돌아와 보낸 첫 메시지는 대화 전체를 다시 처리하므로 느리고 사용량도 더 듭니다.

참고로 DISABLE_AUTO_COMPACT 환경 변수도 유휴 압축을 멈춥니다. 하지만 평소의 자동 압축까지 함께 꺼지니, 유휴 압축만 끄려면 위 키를 쓰는 편이 맞습니다.

막히기 쉬운 곳 네 가지

프로젝트 설정에 넣었는데 @ 멘션이 그대로입니다

보이는 모습: .claude/settings.json에 변수를 적었는데도 @로 가리킨 파일 내용이 그대로 실립니다.
이유: 이 변수는 프로젝트 설정과 로컬 설정(.claude/settings.local.json)에서는 무시됩니다. 내려받은 저장소가 마음대로 정하면 안 되는 변수로 분류돼 있기 때문입니다.
할 일: 터미널에서 켜거나 ~/.claude/settings.json으로 옮기세요.

한 시간을 비웠는데 압축 문구가 없습니다

보이는 모습: 돌아와 보니 Compacted while idle 문구가 없고, 첫 답이 유난히 늦습니다.
이유: TTL이 5분이면 둘째 조건에서 빠집니다. API 키로 로그인했거나, Amazon Bedrock 같은 클라우드 제공자를 쓰거나, 구독 한도를 넘겨 사용 크레딧(한도 뒤에 따로 내는 사용량)을 쓰는 중이면 그렇습니다. 200K 창 모델에서 기준선을 기본값으로 두었을 때도 자동 압축이 먼저 걸립니다.
할 일: /usage에서 TTL부터 보세요. API 키 사용자는 설정에 "promptCacheTtl": "1h"를 넣으면 한 시간 캐시가 되지만, 한 시간 캐시는 쓰기 요금이 더 비쌉니다. 대화 크기가 문제라면 앞의 기준선 변수를 낮춥니다.

보안 설정을 켠 PC에서는 조건을 채워도 돌지 않습니다

보이는 모습: TTL도 한 시간이고 대화도 큰데 압축 문구가 뜨지 않습니다.
이유: CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC가 켜져 있으면 기능 플래그를 받아 오지 못해 셋째 조건이 깨집니다. 값을 0이나 false로 바꿔도 계속 막는다는 점이 함정입니다.
할 일: 터미널과 settings.json의 env를 모두 살펴 이 변수가 있는지 보세요. 변수를 아예 지워야 풀리는데, 회사가 일부러 켜 둔 설정일 수 있으니 관리자에게 먼저 물어보세요.

업데이트했는데 버전이 그대로입니다

보이는 모습: claude update가 Claude is up to date!라고 하는데 버전은 2.1.299보다 낮습니다.
이유: Homebrew, WinGet, apk로 설치하면 이 문구가 나오고, Claude Code가 스스로 올리지 않습니다. 게다가 Homebrew의 claude-code는 안정 채널이라 보통 일주일쯤 늦게 따라옵니다.
할 일: Homebrew는 brew upgrade claude-code, WinGet은 winget upgrade Anthropic.ClaudeCode, apk는 apk update && apk upgrade claude-code를 실행합니다. Homebrew에서 새 버전이 바로 필요하면 brew uninstall --cask claude-code로 지운 뒤 brew install --cask claude-code@latest로 다시 설치하세요. 그다음부터는 brew upgrade claude-code@latest로 올립니다.

여기서 더 나아가려면

/usage의 Prompt cache (main) 줄은 캐시가 왜 깨졌는지 짐작할 단서도 보여 줍니다. 압축 시점을 직접 정하고 싶다면, 일이 한 덩어리 끝난 지점에서 /compact를 실행해 보세요.

이상으로 글 마치겠습니다.

출처