OCR (PDF + Image)

PDF 및 이미지 파일을 Claude의 vision 기능으로 읽어 마크다운으로 변환합니다.

Supported Formats

Quick Start

# 단일 파일 (PDF 또는 이미지)
/ocr /path/to/document.pdf
/ocr /path/to/image.png

# 커스텀 지침과 함께
/ocr /path/to/document.pdf "표만 추출해줘"
/ocr /path/to/screenshot.png "코드만 추출해줘"

# 폴더 내 모든 PDF/이미지 (병렬 처리)
/ocr /path/to/folder/

Core Workflow

Step 1: 경로 및 파일 타입 확인

# 파일인지 폴더인지 확인
ls -la <path>

파일 타입 분류:

• .pdf → PDF 모드
• .png, .jpg, .jpeg, .webp, .gif, .bmp, .tiff → 이미지 모드
• 폴더 → Batch Mode로 진행

Step 2: 저장 방식 선택 (PDF만 해당)

PDF 파일인 경우에만 사용자에게 저장 방식을 질문:

AskUserQuestion:
  question: "PDF 변환 결과를 어떻게 저장할까요?"
  header: "저장 방식"
  options:
    - label: "통합 저장 (Recommended)"
      description: "모든 페이지를 하나의 마크다운 파일로 저장"
    - label: "페이지별 저장"
      description: "각 페이지를 개별 마크다운 파일로 저장 (document_p1.md, document_p2.md, ...)"

저장 방식 변수:

• unified: 통합 저장 → document.pdf → document.md
• per_page: 페이지별 저장 → document.pdf → document_p1.md, document_p2.md, ...

이미지 파일: 저장 방식 질문 없이 바로 image.png → image.md로 변환

Single File Mode - Image

단일 이미지 파일 처리 워크플로우.

IMPORTANT: 단일 파일도 Task 에이전트를 사용하여 메인 컨텍스트를 보호합니다.

Task(subagent_type="general-purpose"):
  프롬프트: |
    이미지 파일을 OCR하여 마크다운으로 변환하고 저장해주세요.

    파일: [이미지 절대경로]
    커스텀 지침: [사용자 지침 있으면 포함]

    **수행 작업:**
    1. Read 도구로 이미지 읽기
    2. 이미지 내용을 마크다운으로 변환
    3. Write 도구로 [파일명].md 파일 저장
    4. 저장 완료 확인

    **에러 핸들링:**
    - 413 에러: "⚠️ 파일 크기 초과 (413 에러)"
    - 기타 에러: "⚠️ [에러 메시지]"

    **반환 형식 (내용 제외, 상태만):**
    ✅ 성공: [파일명] → [출력파일명].md
    또는
    ⚠️ 실패: [파일명] - [사유]

Single File Mode - PDF

단일 PDF 파일 처리 워크플로우.

IMPORTANT: 단일 파일도 Task 에이전트를 사용하여 메인 컨텍스트를 보호합니다.

통합 저장 모드 (unified)

Task(subagent_type="general-purpose"):
  프롬프트: |
    PDF 파일을 OCR하여 마크다운으로 변환하고 저장해주세요.

    파일: [PDF 절대경로]
    저장 방식: 통합 (모든 페이지를 하나의 파일로)
    커스텀 지침: [사용자 지침 있으면 포함]

    **수행 작업:**
    1. Read 도구로 PDF 읽기
    2. 모든 페이지를 하나의 마크다운으로 변환
    3. Write 도구로 [파일명].md 파일 저장
    4. 저장 완료 확인

    **에러 핸들링:**
    - 413 에러: "⚠️ 파일 크기 초과 (413 에러)"
    - 기타 에러: "⚠️ [에러 메시지]"

    **반환 형식 (내용 제외, 상태만):**
    ✅ 성공: [파일명] → [출력파일명].md
    또는
    ⚠️ 실패: [파일명] - [사유]

페이지별 저장 모드 (per_page)

Task(subagent_type="general-purpose"):
  프롬프트: |
    PDF 파일을 OCR하여 페이지별로 마크다운 파일을 생성해주세요.

    파일: [PDF 절대경로]
    저장 방식: 페이지별 (각 페이지를 개별 파일로)
    커스텀 지침: [사용자 지침 있으면 포함]

    **수행 작업:**
    1. Read 도구로 PDF 읽기
    2. 각 페이지별로 마크다운 변환
    3. 각 페이지를 개별 파일로 저장:
       - [파일명]_p1.md (1페이지)
       - [파일명]_p2.md (2페이지)
       - ...
    4. 모든 파일 저장 완료 확인

    **출력 파일 명명 규칙:**
    - document.pdf → document_p1.md, document_p2.md, document_p3.md, ...

    **에러 핸들링:**
    - 413 에러: "⚠️ 파일 크기 초과 (413 에러)"
    - 기타 에러: "⚠️ [에러 메시지]"

    **반환 형식 (내용 제외, 상태만):**
    ✅ 성공: [파일명] → [N]개 페이지 파일 생성
       - [파일명]_p1.md
       - [파일명]_p2.md
       - ...
    또는
    ⚠️ 실패: [파일명] - [사유]

Batch Mode (폴더 처리)

폴더 내 여러 PDF/이미지를 병렬로 처리.

1. 파일 목록 수집 및 분류

# 폴더 내 지원 파일 목록
ls <folder_path>/*.{pdf,png,jpg,jpeg,webp,gif,bmp,tiff} 2>/dev/null

파일 분류:

• PDF 파일 목록: *.pdf
• 이미지 파일 목록: *.png, *.jpg, *.jpeg, *.webp, *.gif, *.bmp, *.tiff

2. 저장 방식 선택 (PDF가 있는 경우만)

PDF 파일이 포함된 경우에만 저장 방식 질문:

AskUserQuestion:
  question: "PDF 변환 결과를 어떻게 저장할까요? (이미지는 항상 통합 저장)"
  header: "저장 방식"
  options:
    - label: "통합 저장 (Recommended)"
      description: "각 PDF의 모든 페이지를 하나의 마크다운 파일로 저장"
    - label: "페이지별 저장"
      description: "각 PDF의 페이지를 개별 마크다운 파일로 저장"

3. 배치 분할 (3개 단위)

파일들을 3개씩 그룹으로 나눕니다 (PDF와 이미지 혼합 가능):

• 그룹 1: file1.pdf, image1.png, file2.pdf
• 그룹 2: image2.jpg, file3.pdf, image3.webp
• ...

4. 병렬 에이전트 실행

각 그룹에 대해 Task 도구로 병렬 에이전트 실행:

Task(subagent_type="general-purpose"):
  프롬프트: |
    다음 파일들을 OCR하여 마크다운으로 변환해주세요.

    파일 목록:
    - [file1 절대경로]
    - [file2 절대경로]
    - [file3 절대경로]

    PDF 저장 방식: [unified 또는 per_page]
    커스텀 지침: [사용자 지침 있으면 포함]
    출력 폴더: [원본과 동일 폴더]

    **파일 타입별 처리:**
    - PDF (.pdf): 지정된 저장 방식 적용
    - 이미지 (.png, .jpg 등): 항상 통합 저장 (image.png → image.md)

    **CRITICAL - 각 파일에 대해 에이전트 내에서 완료:**
    1. Read 도구로 파일 읽기
    2. 에러 발생 시 skip하고 다음 파일로 (413 에러 등)
    3. 마크다운으로 변환
    4. **Write 도구로 파일 저장** (반드시 에이전트 내에서!)
    5. 저장 완료 확인

    **IMPORTANT**:
    - 변환된 마크다운 내용을 메인으로 반환하지 마세요
    - 파일 저장까지 에이전트 내에서 완료해야 합니다
    - 메인에는 처리 결과 상태만 반환합니다

    처리 결과를 다음 형식으로만 보고 (내용 제외):
    ✅ 성공: [파일명] → [출력파일명].md
    ⚠️ SKIP: [파일명] - [사유]

IMPORTANT:

• 모든 그룹의 Task를 동시에 호출하여 병렬 실행
• 에이전트는 Read + Write 모두 완료 후 상태만 반환
• 메인 컨텍스트에 파일 내용이 로드되지 않도록 함

5. 결과 집계

모든 에이전트 완료 후 결과 집계:

## 📊 OCR 처리 결과

### ✅ 성공 ([N]개)
**PDF:**
- document1.pdf → document1.md
- document2.pdf → document2_p1.md, document2_p2.md (페이지별)

**이미지:**
- screenshot.png → screenshot.md
- photo.jpg → photo.md

### ⚠️ Skip ([M]개)
- large_file.pdf - 파일 크기 초과 (413 에러)
- corrupted.png - 읽기 실패

### 📁 출력 위치
[folder_path]/

마크다운 변환 가이드라인

파일 내용을 분석하여 다음 형식으로 마크다운 변환:

# 문서 제목

## 섹션 1
본문 내용...

### 표
| 열1 | 열2 |
|-----|-----|
| 값  | 값  |

### 이미지/다이어그램 설명
[이미지 설명: ...]

커스텀 지침 적용

사용자가 추가 지침을 제공한 경우:

• "표만 추출" → 표 형식 데이터만 마크다운 테이블로
• "요약해줘" → 핵심 내용만 요약
• "영어로 번역" → 번역된 결과물
• "코드만 추출" → 코드 블록만 추출

Supported Content Types

Important Rules

Context 보호 (핵심)

• ALWAYS Task 에이전트 내에서 Read + Write 모두 완료
• ALWAYS 에이전트는 처리 상태만 반환 (변환된 내용 반환 금지)
• NEVER 메인 컨텍스트에 파일 내용을 로드하지 않음

처리 방식

• ALWAYS Read 도구를 사용하여 파일 읽기 (라이브러리 사용 금지)
• ALWAYS 원본 문서의 구조를 최대한 보존
• ALWAYS 사용자 커스텀 지침이 있으면 우선 적용
• ALWAYS 에러 발생 시 해당 파일 skip하고 나머지 계속 처리
• ALWAYS 폴더 처리 시 3개 단위로 병렬 에이전트 실행
• NEVER 외부 라이브러리 사용하지 않음 (PyPDF, Pillow 등)
• NEVER 읽을 수 없는 부분을 추측으로 채우지 않음 (불명확시 [불명확] 표시)
• NEVER 하나의 context에서 모든 파일을 처리하지 않음 (메모리 초과 방지)