Claude Code, 파일 멘션에서 파일 경로만 전달하는 옵션 추가

파일 멘션의 자동 확장을 선택할 수 있습니다

Claude Code 2.1.299는 한국시간 2026년 10월 14일 공개됐습니다. 주요 변경 중 하나는 CLAUDE_CODE_DISABLE_FILE_MENTIONS 환경 변수입니다. 이를 사용하면 @로 언급한 파일의 내용을 바로 넣는 대신 경로를 전달하고, Claude가 파일 도구로 읽도록 합니다. 파일을 참고시키는 요청 자체를 없애는 옵션으로 이해하면 안 됩니다.

공식 환경 변수 문서는 값을 1로 설정하면 파일과 디렉터리 멘션의 확장을 중단한다고 설명합니다. 경로와 함께 파일 도구를 사용해 읽으라는 안내가 전달되므로, 이후 실제로 파일을 읽는 단계는 여전히 발생할 수 있습니다. 이 옵션을 켜면 파일 내용이 절대로 모델에 전달되지 않는다는 보장은 없습니다.

설정 위치가 적용 여부에 영향을 줍니다

현재 공식 문서에는 프로젝트·로컬 설정에 넣은 이 변수는 무시된다고 적혀 있습니다. 따라서 저장소의 설정 파일에 적어 두고 적용됐다고 판단하기보다, 실행 환경에 전달된 값과 사용 버전을 함께 확인하는 편이 좋습니다. 문서는 2.1.299 이상이 필요하다는 조건도 명시합니다.

대형 파일을 매번 자동으로 문맥에 넣는 흐름과 필요한 파일을 도구로 확인하는 흐름은 작업 순서가 다릅니다. 후자는 어떤 파일을 언제 읽었는지 관찰하기 쉬운 반면, 파일 접근 권한이나 경로 해석에 문제가 있으면 필요한 내용에 도달하지 못할 수 있습니다. 경로가 전달됐다는 사실만 보고 파일 분석까지 끝났다고 판단하지 않아야 합니다.

토큰 절감률을 미리 정할 수는 없습니다

자동 확장을 줄이는 옵션이라는 이유만으로 일정한 토큰 절감이나 속도 향상을 약속할 수 없습니다. Claude가 결국 같은 파일을 읽거나 추가 탐색을 수행하면 결과가 달라질 수 있기 때문입니다. 릴리스에는 이 옵션의 절감률이나 벤치마크가 제시되지 않았습니다. 같은 질문과 파일을 사용해 실제 읽기 횟수와 결과의 충분함을 비교해야 합니다.

같은 릴리스에는 PDF를 멘션할 때 파일 바이트를 세션 기록에 계속 보관하지 않도록 해 메모리·디스크 사용을 개선한 내용도 있습니다. 이는 파일 멘션을 경로로 넘기는 옵션과 별개의 수정입니다. PDF 처리 방식의 변화가 일반 소스 파일의 추론 비용을 그대로 줄인다는 의미로 연결하지 않는 것이 정확합니다.

간단한 비교로 확인할 항목

공개 가능한 작은 파일과 긴 파일을 준비하고 동일한 요청을 두 설정에서 실행해 볼 수 있습니다. 답변이 파일 내용에 근거하는지, 읽기 도구가 실행됐는지, 읽지 못한 상황을 솔직하게 알리는지를 비교합니다. 민감한 파일의 접근 제한은 별도의 권한 정책으로 유지해야 합니다. 이 글은 공식 릴리스와 환경 변수 문서를 대조한 설명이며, 실제 사용량이나 응답 시간을 측정한 결과는 아닙니다.

출처

• 공식 릴리스 원문
• 공식 파일 멘션 환경 변수 설명