💡 TL;DR
- pdf-to-doc는 Claude Code에서 자연어 한 줄로 PDF를 Markdown/JSON으로 변환하는 스킬이다.
- 텍스트 기반 PDF는 pdfplumber로, 스캔 PDF는 OCR(ocrmypdf + pytesseract)로 처리한다.
- 원문 추출(Extract)과 요약 분석(Analyze) 두 가지 모드를 지원한다.
- 반복 헤더·푸터·페이지 번호를 자동으로 제거하고 문서 계층 구조를 보존한다.
왜 PDF 자동 처리가 필요한가
PDF는 문서 배포의 표준 포맷이다. 기술 문서, 논문, 계약서, 보고서 등 실무에서 다루는 중요 문서 대부분이 PDF 형태로 존재한다.
문제는 PDF가 “읽기 위한” 포맷이지 “처리하기 위한” 포맷이 아니라는 점이다. AI에게 분석을 맡기거나, 내용을 노션·옵시디언에 정리하거나, 다른 문서에 인용하려면 반드시 텍스트로 변환하는 작업이 필요하다.
| 상황 | 기존 방식 | pdf-to-doc |
|---|---|---|
| 논문 내용 정리 | PDF 열고 복사→붙여넣기 반복 | “paper.pdf 요약해줘” 한 줄 |
| 기술 문서 마크다운화 | 수동 타이핑 또는 변환 툴 사용 | 자동으로 헤딩·표 구조 변환 |
| 스캔 문서 텍스트 추출 | 별도 OCR 소프트웨어 필요 | –ocr 플래그 하나로 처리 |
| 여러 PDF 일괄 처리 | 반복 작업으로 시간 소모 | Claude Code 자동화로 처리 |
처리 과정 (Processing Flow)
pdf-to-doc의 전체 처리 흐름은 PDF 유형에 따라 두 갈래로 나뉜다.
주요 기능
1. 두 가지 추출 모드
📋 Extract 모드 — 원문 그대로
원문 텍스트를 그대로 유지하면서 문서의 계층 구조(제목 → 소제목 → 본문)만 Markdown 헤딩으로 변환한다. AI의 해석 없이 순수하게 내용을 보존하고 싶을 때 사용한다.
트리거 키워드: 그대로, 추출, 원문, extract, as-is
🔍 Analyze 모드 — 요약 분석
각 섹션을 1~3줄로 요약하고 핵심 포인트를 bullet로 정리한다. 긴 문서의 핵심을 빠르게 파악하거나 보고서를 작성할 때 유용하다.
트리거 키워드: 요약, 분석, 정리, summarize, analyze
2. OCR 지원 — 스캔 PDF도 처리 가능
텍스트 레이어가 없는 스캔 PDF는 두 단계 OCR 파이프라인으로 처리한다.
- ocrmypdf: PDF 전체에 텍스트 레이어를 추가하는 전처리 도구. 한국어 포함 100개 이상의 언어를 지원한다.
- pymupdf + pytesseract: ocrmypdf가 처리하지 못한 개별 페이지를 2배 해상도로 렌더링하여 OCR 정확도를 높인다.
3. 자동 노이즈 제거
PDF에서 텍스트를 추출하면 문서 본문과 무관한 노이즈가 함께 딸려온다. pdf-to-doc은 이를 자동으로 제거한다.
| 노이즈 유형 | 예시 | 처리 방식 |
|---|---|---|
| 페이지 번호 | - 2 -, - 15 - |
정규식 fullmatch로 제거 |
| 반복 헤더 | 매 페이지 상단의 문서 제목 | 3페이지 이상 반복 시 자동 감지 후 제거 |
| 반복 푸터 | 회사명, 날짜, 기밀 표시 | 동일 기준으로 자동 제거 |
| 빈 표 | 셀이 없거나 1개뿐인 표 | 유효 셀 2개 미만이면 제외 |
4. 다양한 출력 포맷
상황에 따라 Markdown 또는 JSON으로 출력할 수 있다. Markdown은 노션·옵시디언·깃허브에 바로 붙여 넣을 수 있고, JSON은 데이터 파이프라인에 활용하기 좋다.
# Markdown 출력 (기본)
python extract_pdf.py report.pdf
# JSON 출력
python extract_pdf.py report.pdf --json설치 및 사용법
설치
# 스킬 설치
cp -r pdf-to-doc/ ~/.claude/skills/
# 기본 의존성
pip install pdfplumber
# OCR 의존성 (스캔 PDF 처리 시)
brew install tesseract tesseract-lang ocrmypdf
pip install pymupdf pytesseract사용 예시
Claude Code에서 자연어로 바로 사용할 수 있다.
# 일반 PDF 추출
"report.pdf 내용 추출해서 md로 만들어줘"
# 논문 요약
"paper.pdf 요약해줘"
# 스캔 PDF OCR
"스캔된 계약서인데 텍스트 추출해줘"
# 언어 지정 OCR
"영문 스캔 문서야, OCR 적용해서 추출해줘"지원 PDF 유형
| PDF 유형 | Extract | Analyze | OCR 필요 | 비고 |
|---|---|---|---|---|
| 텍스트 기반 PDF | ✅ | ✅ | 불필요 | 최적 환경 |
| 스캔 PDF (이미지) | ✅ | ✅ | 필요 (–ocr) | tesseract 설치 필요 |
| 표 포함 PDF | ✅ | ✅ | 불필요 | Markdown 표로 자동 변환 |
| 다국어 PDF | ✅ | ✅ | 불필요 | UTF-8 완전 지원 |
| 암호화 PDF | ❌ | ❌ | – | 비밀번호 해제 후 사용 |
기술 스택
마치며
pdf-to-doc은 단순한 PDF 변환 도구가 아니다. Claude Code의 스킬 시스템과 결합하여 자연어 한 줄로 복잡한 PDF 처리 파이프라인을 실행하는 것이 핵심이다.
논문을 읽을 때, 기술 문서를 정리할 때, 오래된 스캔 문서를 디지털화할 때—더 이상 PDF 앞에서 막힐 필요가 없다.