Claude Code 토큰 사용량을 줄여주는 Markdown 자동 변환 훅

실용적 조언

Claude Code 사용량이 금방 소진된다면 제공된 설치 스크립트를 통해 Markdown 변환 훅을 적용해볼 것.
이미 hooks.json을 사용 중인 경우 GitHub의 수동 설치 가이드를 참고하여 기존 설정과 병합할 것.

섹션별 상세

바이너리 파일 형식의 높은 토큰 비용 문제가 제기됐다. 원문 작성자는 PDF 파일을 그대로 Claude Code에 입력할 경우 동일한 내용의 Markdown 대비 10-20배 더 많은 토큰이 소모된다고 밝혔다. 이는 인코딩 오버헤드로 인해 사용자의 할당량이 빠르게 소진되는 주요 원인이 된다. 텍스트 기반의 Markdown으로 변환하면 정보 손실을 최소화하면서도 효율적인 컨텍스트 관리가 가능하다.

bash

curl -sSL https://raw.githubusercontent.com/sunlesshalo/claude-code-md-hook/main/install.sh | bash

Claude Code Markdown 변환 훅을 프로젝트 폴더에 설치하는 한 줄 명령이다.

PreToolUse 훅을 활용한 자동화 메커니즘이 구현됐다. Claude Code가 PDF, DOCX, XLSX, PPTX, HTML 파일을 읽으려고 시도할 때 이 훅이 호출을 가로챈다. 시스템은 원본 파일을 직접 읽는 대신 Markdown으로 변환된 캐시 버전을 에이전트에게 전달한다. 사용자는 기존 워크플로우를 변경하지 않고도 백그라운드에서 자동으로 토큰 최적화 혜택을 누릴 수 있다.

markitdown 라이브러리 연동 및 캐싱 전략이 핵심이다. 첫 실행 시 Microsoft의 markitdown 라이브러리를 자동으로 설치하여 복잡한 문서 구조를 텍스트로 파싱한다. 변환된 결과물은 로컬에 캐싱되어 이후 동일한 파일에 접근할 때 추가적인 변환 과정이나 토큰 낭비 없이 즉시 서빙된다. 이를 통해 변환에 소요되는 컴퓨팅 자원과 LLM 토큰 비용을 동시에 절약한다.

용어 해설

토큰 최적화(Token Optimization): — LLM이 텍스트를 처리하는 단위인 토큰의 사용량을 줄여 비용을 절감하고 컨텍스트 제한 내에서 더 많은 정보를 처리하는 기법이다. PDF와 같은 바이너리 형식은 텍스트보다 훨씬 많은 토큰을 소모하므로 이를 효율적인 형식으로 변환하는 것이 핵심이다.
도구 사용 전 훅(PreToolUse Hook): — AI 에이전트가 특정 도구(파일 읽기 등)를 실행하기 직전에 사용자 정의 로직을 삽입하는 메커니즘이다. 이를 통해 입력 데이터를 가공하거나 실행 조건을 변경하여 에이전트의 동작을 최적화할 수 있다.
마크다운 변환(Markdown Conversion): — PDF, DOCX, XLSX 등 복잡한 문서 형식을 구조화된 텍스트인 마크다운으로 변환하는 과정이다. LLM은 마크다운의 구조적 태그를 잘 이해하며, 바이너리 형식 대비 토큰 소모량이 압도적으로 적어 효율적이다.

언급된 도구

markitdown추천링크

다양한 문서 형식을 Markdown으로 변환하는 라이브러리

claude-code-md-hook추천링크

Claude Code용 자동 Markdown 변환 및 캐싱 훅

언급된 리소스

GitHubclaude-code-md-hook GitHub Repository