Sprag

doc2md 상세 문서

기획서와 보고서는 대부분 pptx, xlsx, pdf, docx, fig로 옵니다. 이 형식을 그대로 다루면 두 가지 중 하나가 일어납니다. Claude Code가 이진 파일이라며 거부해서 아무것도 읽지 못하거나, 압축을 풀어 본문 XML을 읽느라 토큰을 태웁니다.…

📄 doc2md: 문서를 읽기 전에 Markdown으로 바꿉니다

기획서와 보고서는 대부분 pptx, xlsx, pdf, docx, fig로 옵니다. 이 형식을 그대로 다루면 두 가지 중 하나가 일어납니다. Claude Code가 이진 파일이라며 거부해서 아무것도 읽지 못하거나, 압축을 풀어 본문 XML을 읽느라 토큰을 태웁니다. 30MB짜리 발표자료 하나가 XML로는 54만 토큰이고, 200k 컨텍스트에는 들어가지도 않습니다. PDF는 통째로 첨부하면 페이지마다 2,500~2,900 토큰이 들고, .fig는 Read가 거부하지 않아서 이진 잡음이 그대로 컨텍스트를 채웁니다. 각 경우의 실측은 아래 절감 절에 있습니다.

doc2md는 이런 파일을 한 번 변환해 두고 원본 대신 변환본을 읽게 합니다. 54만 토큰이던 발표자료가 22,610 토큰이 됩니다.

설치할 때 함께 켜집니다. sprag install이 훅을 등록합니다(v3.32.0부터. 건너뛰려면 SPRAG_NO_DOC2MD=1을 설정하고, 나중에 끄려면 sprag doc2md off를 쓰십시오). 변환기는 설치에 들어 있지 않고, 아래에서 설명하듯 문서가 처음 나타날 때 저절로 설치됩니다. 그때까지는 훅이 변환할 수단이 없어서 아무 일도 하지 않습니다.

상황은 세 가지이고, 상황마다 걸리는 지점이 다릅니다.

상황개입 지점
프롬프트에 문서 경로를 적음 (@경로·따옴표·상대 경로 모두)UserPromptSubmit. 변환한 뒤 변환본 경로를 컨텍스트로 넣습니다
작업 도중 문서를 Readpdf와 .fig는 PreToolUse(Read)가 잡습니다. pptx·xlsx·docx는 Claude Code가 이진 파일이라며 훅보다 먼저 거부하므로, 세션 시작 안내문이 모델에게 doc2md <경로>를 실행하도록 지시합니다
문서를 메시지에 직접 첨부훅으로 잡을 수 없습니다. 어떤 훅 이벤트도 첨부 내용을 받지 못합니다. 세션 시작 안내문이 모델에게 다음부터는 경로로 달라고 사용자에게 요청하게 합니다

두 번째 줄은 추정이 아니라 실측입니다. .pdf를 Read하면 훅이 실행되고, 같은 세션에서 .pptx를 Read하면 훅 로그에 아무 기록도 남지 않습니다. .fig는 Read가 거부하지 않으므로(아래 피그마 절 참고) PDF처럼 훅이 실행됩니다.

sprag doc2md on                  # `doc2md off` 뒤에 훅을 다시 등록 (변환기는 첫 문서에서 자동 설치)
sprag doc2md                     # 변환기·훅 등록 상태 확인
sprag doc2md 보고서.pptx          # 직접 변환해 결과 확인
sprag doc2md install-converter   # 설치를 미리 끝내 두고 싶을 때만

변환기는 저절로 설치됩니다. 팀에 배포할 때 각자 설치 명령을 실행하게 만들면 그 단계에서 빠지는 사람이 생깁니다. 그래서 문서가 처음 나타나는 순간 변환기를 백그라운드로 설치하고, 설치가 끝나는 대로 곧바로 변환합니다. 실측으로 첫 문서는 약 30초(설치 15초와 markitdown 첫 임포트), 이후 새 문서는 3.7초, 캐시에 적중하면 0.1초입니다. .fig 파서는 첫 Figma 파일에서 0.5초 만에 설치됩니다.

설치는 install 단계가 아니라 첫 사용 시점에 합니다. venv가 47MB라서, 문서를 다루지 않는 사람이 치를 이유가 없는 비용이기 때문입니다. 자동 설치를 끄려면 SPRAG_DOC2MD_NO_AUTOINSTALL=1을 설정하십시오.

Python 3.10 이상이 필요합니다. markitdown이 요구하는 최소 버전인데, macOS의 기본 /usr/bin/python3는 3.9입니다. 그래서 PATH 순서를 따르지 않고 버전을 보고 인터프리터를 골라 venv를 만듭니다. 3.9로 만들면 pip가 markitdown을 2019년 자리표시자 릴리스(0.0.1a1)로 해석합니다. 그러면 설치는 성공한 것처럼 보이지만 모든 변환이 임포트 단계에서 죽습니다. 직접 밟아 보고서야 알게 된 함정입니다. 3.10 이상이 아예 없으면, 성공할 수 없는 설치 명령 대신 brew install python을 안내합니다.

변환기는 도구 전용 venv(<상태 디렉터리>/doc2md-venv)에 설치합니다. 시스템 Python을 건드리지 않고, CLI를 지우면 venv도 함께 사라집니다. uv tool이나 PATH에 markitdown이 이미 있으면 새로 만들지 않고 그것을 먼저 씁니다.

변환은 markitdown이 맡습니다. 슬라이드 번호, 제목 계층, 표, 발표자 노트, 시트별 제목이 모두 남고, 한글도 깨지지 않습니다.

몇 가지는 의도적으로 하지 않습니다.

변환이 얼마를 아끼는지

변환본은 첫머리에 출처 주석을 답니다. 어떤 원본을 언제 변환했고 몇 토큰인지가 파일을 여는 순간 보입니다. 절감액은 스테이터스라인의 절감 줄 끝에 📄 Doc2md saved로 붙습니다.

절감액의 기준은 변환기가 없을 때 실제로 하게 되는 일이고, 그 일은 형식마다 다릅니다. 두 경우 모두 2026-09-06에 실측했습니다.

PDF는 첨부와 비교합니다. claude --print --input-format stream-json으로 같은 한 줄 프롬프트를 파일을 문서 블록으로 붙여서, 그리고 붙이지 않고 보낸 뒤 입력 토큰을 비교했습니다. 대조군은 42,204 토큰이었고, 두 번 반복해도 값이 같았습니다.

첨부 파일분량첨부가 더 든 토큰페이지당
보고서 PDF7페이지+20,5372,934
보고서 PDF5페이지+12,7092,542

첨부한 PDF는 모델이 내용을 통째로 읽습니다. 대신 페이지마다 2,500~2,900 토큰이 드는 반면, 변환본은 5,531 토큰입니다. 계수는 실측치 두 개보다 낮은 페이지당 2,500을 씁니다. 넉넉히 잡아 부풀리기보다 낮게 잡아 밑도는 편이 낫기 때문입니다.

pptx·xlsx·docx는 압축을 푸는 경우와 비교합니다. 이 형식은 애초에 첨부로 모델에 닿지 않습니다. 같은 방식으로 docx를 보냈더니 78 토큰만 늘었고 모델은 파일이 없다고 답했으며, Read도 이진 파일이라며 거부합니다. 그러므로 변환기가 없을 때 실제로 하게 되는 일은 압축을 풀고 본문 XML을 읽는 것입니다. 글자 수의 대부분을 태그와 스타일 속성이 차지하는 그 XML입니다.

원본본문 XML변환본차이
발표자료 pptx (31.8MB)약 540,429 토큰약 22,610 토큰23.8배
사업계획서 docx (189KB)약 79,621 토큰약 1,684 토큰47.3배

30MB짜리 발표자료 하나가 XML로는 54만 토큰입니다. 200k 컨텍스트에는 들어가지도 않습니다. 이 기준은 형식별 계수가 아니라, 파일마다 실제 XML 크기를 재서 씁니다.

.xls는 zip 컨테이너가 아니라서 재어 볼 마크업이 없으므로 절감을 0으로 둡니다.

클라이언트 동작이 바뀌면 scripts/doc2md-baseline.mjs로 첨부 쪽을 다시 재고, src/doc2md-ledger.cjs의 ATTACHMENT_BASELINE 표에 값만 갈아 끼우면 됩니다.

피그마 .fig도 변환합니다

기획서가 PPT에서 피그마로 옮겨 가는 추세라서, .fig 파일도 같은 훅이 잡습니다. .fig는 zip 컨테이너지만 안에 든 canvas.fig가 피그마의 비공개 바이너리(kiwi 포맷)라서 markitdown이 열지 못합니다. 그래서 이 형식만 Node 파서(openfig-core, MIT)로 변환합니다. doc2md install-converter가 markitdown과 함께 도구 상태 디렉터리에 설치하며, 패키지 자체는 여전히 무의존성입니다.

변환 결과는 아웃라인입니다. 페이지와 프레임 계층은 헤딩으로, 텍스트 노드는 본문으로 옮기고, 도형·벡터 같은 시각 요소는 나열하지 않고 개수만 남깁니다. 기획서에서 내용은 글이고, Rectangle 173이 이백 줄 나오면 글이 묻히기 때문입니다. 텍스트가 하나도 없는 파일(순수 그래픽)은 빈 문서로 꾸미지 않고 변환 불가로 알립니다.

실제 파일로 검증했습니다. 피그마 커뮤니티의 Bootstrap UI kit(8.1MB, 노드 4,155개, 텍스트 1,312개)와 Tailwind kit(52MB)이 각각 0.2초 안에 71.9KB, 44KB 아웃라인으로 변환됐고, 한국어 텍스트의 왕복도 손실이 없었습니다. .fig는 두 세대가 있습니다. 요즘 익스포트는 zip 컨테이너이고 옛 익스포트는 fig-kiwi 바이너리 원형인데, 둘 다 처리합니다.

.fig의 절감이 가장 큽니다. 오피스 형식과 달리 Read가 .fig를 거부하지 않습니다. 확장자를 모르니 이진 파일을 그대로 텍스트로 읽어 들이고, 컨텍스트가 토큰화된 잡음으로 찹니다. 두 파일 모두 42,760 토큰짜리 대조군과 비교해 측정했습니다.

파일크기Read가 더 쓴 토큰변환본
plan.fig26KB+44,195100 토큰
bootstrap-kit.fig8.1MB+43,99418,397 토큰

크기가 300배 차이 나는데 비용은 같습니다. Read가 상한에서 잘라 버리기 때문인데, 바꿔 말하면 문서 전체 값을 치르고 일부만 받는 셈입니다. 그래서 기준선은 파일 크기와 무관한 44,000 토큰으로 고정했습니다. 같은 방법으로 pptx와 docx도 재 보니 각각 +317, +185 토큰이었습니다. 거부 메시지 한 줄이 전부입니다.

왜 파일 크기에 비례시키지 않는가

기준선은 "변환이 없었으면 실제로 나갔을 비용"이어야 합니다. 직관으로는 파일이 클수록 더 태울 것 같지만, Read 도구에는 상한이 있어(기본 2,000줄, 줄당 문자 제한) 이진 파일은 그 지점에서 잘립니다. 26KB 파일조차 이미 상한을 넘기므로, 크기가 300배 차이 나는 두 파일이 201 토큰 차이밖에 나지 않았습니다. 8.1MB가 통째로 들어갔다면 수백만 토큰이지만, 그만큼은 200k 컨텍스트에 들어가지 않으므로 아무도 쓸 수 없는 비용입니다. 쓸 수 없는 비용을 아꼈다고 적으면 부풀리기입니다.

이 원칙은 모든 기준선에 같게 적용됩니다.

공통 규칙은 하나입니다. 기준선이 추정과 실측 사이에서 갈리면 항상 낮은 쪽을 택합니다. 도구를 돋보이게 하는 숫자보다 사용자가 믿을 수 있는 숫자가 더 가치 있습니다.

문서를 수정해야 할 때: 복사본과 스크립트

변환은 단방향이라서, 변환본 .md를 고쳐도 원본에는 반영되지 않습니다. 훅은 변환 캐시와 원본 이진 파일을 Edit·Write로 고치려는 시도를 거부하고 올바른 경로를 안내합니다. 원본을 복사하고, 복사본을 스크립트로 수정하고, 수정본을 doc2md로 다시 변환해 검증하는 순서입니다.

install-converter가 편집 라이브러리(python-pptx·python-docx·openpyxl)를 변환기 venv에 함께 설치합니다. 그래서 "23번 슬라이드 차트를 꺾은선으로 바꿔줘" 같은 구조 편집도 에이전트가 바로 스크립트를 작성해 처리할 수 있습니다. .fig는 openfig-core가 인코더까지 제공하므로, 텍스트를 수정한 뒤 다시 인코딩할 수 있습니다.

네 형식 모두 2026-09-06에 처음부터 끝까지 실행해 검증했습니다. docx는 텍스트 치환 10건과 3회 연속 재저장, pptx는 막대 차트를 꺾은선으로 교체하면서 데이터 행 추가, xlsx는 값 정정과 행 추가, fig는 텍스트 수정과 재인코딩, 재파싱입니다. 모든 경우에 원본은 바이트까지 그대로였고, 수정본을 다시 변환하면 변경 내용이 나타났습니다. 한 가지 주의할 점이 있습니다. pptx에서 차트 도형을 제거하면 옛 차트 XML 파트가 고아로 남습니다. PowerPoint는 무시하지만, 파일을 깔끔하게 만들려면 그 파트와 rels도 지우십시오. 차트와 이미지 같은 시각 요소는 변환본에 나타나지 않으므로, 시각 편집의 최종 확인은 해당 프로그램에서 해야 합니다.

DRM으로 보호된 문서

암호와 DRM은 판별 원리가 다르지만 처리는 같습니다. 사내 DRM(파수·마크애니·소프트캠프 등)은 문서에 암호를 거는 것이 아니라 파일 전체를 감싸며, 벤더 에이전트가 허용한 프로세스만 평문을 봅니다. Python은 그 허용 목록에 없으므로 디스크에 있는 것은 벤더 헤더가 붙은 암호문입니다. 암호를 입력해서 풀 수 있는 문제가 아닙니다.

판별은 첫 바이트를 보고 갈립니다. zip 헤더면 내려받다 끊긴 파일이고, OLE 컨테이너면 암호가 걸린 문서이며, 둘 다 아니면 애초에 그 형식이 아닙니다.

✗ bad-archive: File is not a zip file            ← 다시 받으십시오
✗ encrypted: password-protected Office file      ← 확인할 수 없다고 알리고 멈춤
✗ drm-protected: DRM-wrapped file (FASOO)        ← 확인할 수 없다고 알리고 멈춤

벤더 이름은 진단 출력에 참고로 붙일 뿐이고, 판별 자체는 벤더를 몰라도 성립합니다. PDF는 공개된 DRM 보안 핸들러 이름(FOPN_foweb, EBX_HANDLER, Adobe.APS)으로 같은 판정을 합니다.

암호가 걸린 문서와 Windows

암호 문서는 오류가 아니라 상태로 다룹니다. 사내에서 받는 문서 중 일부는 암호가 걸려 있습니다. Office는 암호를 걸 때 패키지를 zip이 아니라 OLE 복합 문서로 감싸 저장합니다. 그래서 예전에는 암호가 걸린 docx를 zip으로 열려다 "손상된 zip"이라고 알렸고, 사용자는 엉뚱한 곳에서 원인을 찾아야 했습니다. 지금은 변환 전에 판별해서 이렇게 알립니다.

✗ encrypted: password-protected Office file (OLE-wrapped)
✗ encrypted: password-protected PDF

암호 문서와 DRM 문서 모두, 모델에게 "내용을 확인할 수 없다고 사용자에게 알리고 우회하지 말라"고 안내하며 원본 Read는 거절합니다. 사내 문서의 암호화는 정책이므로 열리지 않는 것이 맞고, 이 도구는 암호를 묻지도 저장하지도 않습니다. pptx·xlsx·docx는 Claude Code가 settings 훅보다 먼저 이진 파일로 거절하므로 훅의 안내가 모델에 닿지 않습니다. 그래서 이 안내는 mod가 대신 전합니다. 열람은 자유롭고 인쇄만 제한된 PDF는 암호 문서가 아니므로 그대로 변환합니다(오탐 확인 완료). 구형 .xls도 원래 OLE 형식이라서 암호 문서로 오인하지 않습니다.

Windows를 지원하며, 실제 Windows 러너에서 검증합니다. Windows를 쓰는 팀을 위해 다음을 맞췄습니다.

sprag doc2md --clean으로 변환 캐시를 비우고, doc2md off로 훅을 제거합니다. 훅 해제는 이 도구의 항목만 골라 지우므로, PreToolUse에 등록해 둔 다른 훅은 그대로 남습니다.

다른 문서