일회성 읽기: 중복 파일 읽기를 방지하는 Claude 코드 훅

한 개발자가 read-once라는 PreToolUse 훅을 만들어서 Claude Code가 세션 중에 같은 파일을 반복해서 읽는 경향을 해결했습니다. 이로 인해 불필요한 토큰 소비를 방지합니다.

문제와 해결책

Claude Code는 종종 이미 컨텍스트에 있는 파일을 다시 읽습니다. 예를 들어, 500줄짜리 파일을 열고 작은 편집을 한 후 Claude가 전체 파일을 다시 읽으면 읽기당 약 2,000개 이상의 토큰이 소비됩니다. 일반적인 세션에서 같은 파일이 5-10번 읽히는 경우가 있습니다.

read-once 훅은 Claude가 현재 세션에서 어떤 파일을 읽었는지 추적합니다. Claude가 변경되지 않은 파일을 다시 읽으려고 하면, 훅이 이를 차단하고 다음과 같은 메시지를 표시합니다: "read-once: config.rs (~3,400 토큰) 이미 컨텍스트에 있음 (4분 전에 읽음, 변경되지 않음). 세션 절감량: ~12,000 토큰."

작동 방식

• 첫 번째 읽기 시: 파일 경로, 수정 시간 및 타임스탬프를 기록한 후 정상적으로 읽기를 허용합니다.
• 변경되지 않은 파일 재읽기 시: Claude가 이미 내용을 가지고 있으므로 읽기를 차단합니다.
• 변경된 파일 재읽기 시: 전체 재읽기를 허용하는 대신, 훅이 diff를 계산하고 변경된 부분만 반환합니다. Claude는 이미 컨텍스트에 이전 버전을 가지고 있으며 델타만 필요합니다. 3줄이 변경된 500줄 파일의 경우, ~2,000개 대신 ~30개의 토큰을 사용하여 파일 반복 시 80-95%를 절약합니다.

기능 및 구성

이 도구는 TTL을 인식하며 캐시 항목은 20분 후에 만료됩니다(구성 가능). 만료 후에는 Claude가 컨텍스트를 압축하여 이전 내용을 잃어버렸을 수 있으므로 재읽기가 허용됩니다.

구성은 환경 변수를 통해 수행됩니다:

• READ_ONCE_TTL=1200 - 캐시 만료 전 초 단위 시간(기본값 20분)
• READ_ONCE_DIFF=1 - diff 모드 활성화
• READ_ONCE_DIFF_MAX=40 - 전체 재읽기로 폴백하기 전 최대 diff 줄 수
• READ_ONCE_DISABLED=1 - 완전히 끄기

기술적 세부사항

전체 도구는 jq와 diff를 제외한 종속성이 없는 약 250줄의 bash 스크립트입니다. MIT 라이선스로 배포되며 .claude/settings.json 훅에 자신을 추가하여 설치합니다.

개발자는 Claude Code를 자율 루프에서 실행할 때 토큰 비용이 빠르게 누적되기 때문에 이 도구를 만들었습니다. diff 모드만으로도 세션당 토큰 사용량을 약 30% 절감했다고 보고되었습니다.