i-hate-hancom

 → 

I-Hate-Hancom for Claude

한컴 서식 지옥에서 해방 — Markdown → HWPX 자동 변환 Claude Code Skill

---

The Problem: 한컴의 문제

대한민국에는 독특한 문서 생태계가 있다. 전 세계가 .docx, .pdf, 마크다운을 쓸 때, 한국의 공공기관과 기업은 **한컴오피스 한글(.hwp/.hwpx)**을 사실상 표준으로 사용한다.

이 포맷이 비효율적인 이유는 구조적이다:

• 콘텐츠 대비 서식 비용이 과도하다: 한컴 문서는 제목 크기, 들여쓰기, 표 테두리, 글머리 기호 등 시각적 서식을 수작업으로 지정해야 한다. 동일한 내용을 마크다운으로 작성하면 5분이면 끝날 일에 50분이 걸린다.
• 크로스플랫폼을 지원하지 않는다: macOS와 Linux에서 정상적으로 열리지 않고, 웹 뷰어는 레이아웃이 원본과 다르게 렌더링된다. 협업 환경에서 호환성 문제가 반복된다.
• 버전 관리가 불가능하다: .hwp는 바이너리 포맷이고, .hwpx는 ZIP 안의 XML이다. 어느 쪽이든 git diff로 변경 사항을 추적할 수 없어 협업 워크플로우에 통합되지 않는다.
• 포맷 명세가 공개되지 않았다: HWPX에 대한 공식 스펙 문서가 사실상 존재하지 않는다. 프로그래밍 방식으로 문서를 생성하려면 리버스 엔지니어링이 유일한 방법이다.
• 사용이 관성적으로 강제된다: 공공기관이 한컴 포맷으로 문서를 발송하면, 수신 측도 동일한 포맷으로 회신해야 한다. 기술적 우위가 아닌 관습이 선택을 결정한다.
• AI 활용이 본질적으로 차단된다: HWPX의 복잡한 XML 네임스페이스, 미공개 스타일 ID 체계, 바이트 단위의 구조적 민감성은 LLM이 직접 다루기에 부적합하다. 작은 오타 하나로 파일 전체가 깨지기 때문에, AI가 가장 잘하는 일 — 대량의 콘텐츠를 구조화된 문서로 빠르게 변환하는 것 — 을 한컴 포맷에서는 수행할 수 없다. 서식의 비효율이 AI 시대에 이르러 더욱 가중되는 이유다.

이 스킬은 마크다운으로 작성하고 한컴 포맷으로 출력하는 방식으로, 서식에 소비되는 시간을 구조적으로 제거한다.

---

Strengths & Limitations

할 수 있는 것

• 텍스트/마크다운 → 정부 공문서 수준 HWPX 생성
• 제목, 섹션 헤더, 불렛 리스트, 번호 리스트
• ▢/○/▷ 한국 공문서 기호 체계
• 표 (데이터 표, 비교 표, 기관 목록 등)
• 이미지 임베딩
• 강조 박스 (노트/인포), 인용 박스 (대통령 말씀 등)
• 타이틀 박스 (국정과제 제목 등)
• 볼드 키워드 강조
• 다양한 문서 유형 — 보도자료, 업무보고, 분석 기사, 칼럼

아직 할 수 없는 것

• 복잡한 중첩 표 (병합 셀)
• 수식, 차트
• 기존 HWPX 편집 (읽기는 가능)
• 다단 레이아웃
• 머리글/바닥글 커스터마이징
• HWP (구 바이너리 포맷) 지원

---

Installation

Prerequisites

• Claude Code (Desktop App 또는 CLI)
• Python 3.8+ (외부 패키지 불필요 — stdlib만 사용)

Quick Start

1. 사용자 지정 → 플러그인 탐색 진입

2. 플러그인 탐색 클릭

3. + → 마켓플레이스 추가

4. URL 입력 후 동기화

https://github.com/tjdwls101010/I-Hate-Hancom_for_Claude.git

5. I-Hate-Hancom 플러그인 설치

6. 마크다운 파일을 업로드하면 Hancom 스킬이 자동으로 트리거된다

---

Usage

마크다운 파일을 업로드하거나 자연어로 요청하면 Hancom 스킬이 자동으로 트리거된다:

https://github.com/user-attachments/assets/e0a84763-50e5-43fb-802d-2af6ba8a9c03

Claude Code에서 자연어로 요청하면 된다:

"이 마크다운 파일을 한컴 공문서로 변환해줘"
"hwpx로 만들어줘"
"보도자료 형식으로 작성해줘"
"이 hwpx 파일 읽어줘"

직접 스크립트 실행

# 1. 마크다운 린트
python3 .claude/skills/Hancom/Scripts/md_lint.py input.md

# 2. 변환 + 빌드
python3 .claude/skills/Hancom/Scripts/md_to_hwpx.py input.md --output output.hwpx --build --title "문서 제목"

# 3. HWPX 읽기
python3 .claude/skills/Hancom/Scripts/read_hwpx.py document.hwpx

# 4. HWPX 검증
python3 .claude/skills/Hancom/Scripts/validate_hwpx.py document.hwpx

---

How It Works

변환 파이프라인

graph LR
    A["📝 Markdown"] --> B["🧹 md_lint.py"]
    B --> C["✍️ Content Prep"]
    C --> D["⚙️ md_to_hwpx.py"]
    D --> E["📦 build_hwpx.py"]
    E --> F["📄 .hwpx"]

    style A fill:#e8f5e9
    style F fill:#fff3e0

단계	도구	하는 일
Lint	md_lint.py	기계적 마크다운 정리 — 제목 레벨 갭, 연속 빈줄, 리스트 간 빈줄, 후행 공백
Content Prep	Claude (수동)	의미 판단이 필요한 정규화 — 구조 재배치, 불렛→표 변환, <!-- box:note --> 등 어노테이션
Convert	md_to_hwpx.py	어노테이션된 마크다운 → section0.xml (XML 템플릿 기반 생성)
Build	build_hwpx.py	section0.xml + header.xml + 이미지 → .hwpx ZIP 아카이브

HWPX 파일 구조

HWPX는 ZIP 아카이브다. 안에 XML 파일들이 들어 있다:

document.hwpx (ZIP)
├── mimetype                    ← 반드시 첫 번째 엔트리 (STORED, 비압축)
├── META-INF/container.xml
├── Contents/
│   ├── header.xml              ← "CSS" — 모든 스타일을 ID로 정의
│   ├── section0.xml            ← "HTML" — 본문 내용, 스타일 ID 참조
│   └── content.hpf
├── settings.xml
└── version.xml