무엇이 되나

한글(HWP/HWPX)은 한국 공공·기업 문서의 표준이지만, AI가 다룰 수 있는 도구가 사실상 없었습니다. hwpx-kit은 AI 에이전트가 한글 문서를 읽고, 채우고, 고치고, 새로 만들 수 있게 하는 도구 모음입니다.

👤 "이 양식에 채워줘"                    → 서식(폰트·표·조판) 무손상으로 값만 채운 사본
👤 "이 기획서를 ○○사업용으로 바꿔줘"      → 기존 문서를 양식 삼아 내용 전면 교체
👤 "한글로 새 기획서 만들어줘"            → 내장 템플릿으로 표지·장·표 갖춘 문서 생성
👤 "예산 앞에 장 하나 추가하고 표 넣어줘"   → 장 헤더 복제·새 표 생성·쪽나눔까지
👤 "금액 한글로 병기해줘"                → 금12,340원(금일만이천삼백사십원) — 계산 착오 0
👤 "이거 워드로도 줘" / "PPT로 만들어줘"   → docx 변환 / 발표자료 재구성
👤 "이 명단으로 위촉장 30부 만들어줘"      → 엑셀 명단 × 양식 일괄 생성 (메일머지)
👤 "제출 전에 검토해줘"                  → 빈칸·표기 위반·개인정보 잔존 기계 검수
👤 "여기 도장 찍어줘"                    → 직인·증명사진 삽입 (이미지는 사용자 제공)
👤 "이 이미지 표처럼 그려줘"              → 병합·색·열폭·정렬 갖춘 표 원샷 생성

모든 채우기는 원본을 절대 수정하지 않고 사본에만 씁니다. 실제 공공기관 서식 (보도자료·신청서·계획서·회의록·공고문)으로 왕복 검증했습니다.

이런 분들을 위해 만들었습니다: 공공기관·학교의 서식 담당자, 사업계획서를 반복 작성하는 창업자·연구자, 한글 문서를 AI 워크플로에 넣고 싶은 개발자.

데모 — 한마디로 기획서 한 부

"hwpx로 새로운 사업기획서 작성해줘. 서울광역시에서 진행하는 Claude Code 해커톤"

① 시작점 — 내장 템플릿 (양식 파일이 없을 때 기준. 갖고 있는 양식이 있으면 그 양식을 그대로 씁니다)

② 작업 과정 — 필수 정보(일시·대상·주최·예산)를 먼저 묻고, 답을 받아 진행합니다

③ 결과물 — 표지·5개 장·일정표·예산표까지 채워진 완성본. 서식은 템플릿 그대로

이 데모에서 실제로 일어난 일들:

• 아는 것만 쓰고, 모르는 건 묻습니다 — 장소가 미정이라고 하자 "서울 시내 행사장(추후 확정)"으로 표기하고 확정되면 수정하겠다고 알림. 말하지 않은 정원·시상금을 지어내지 않음
• 내용을 주면 그대로, 안 주면 Claude가 초안 — 시상금 구성은 사용자가 준 숫자 그대로, 추진배경·목적은 "필요하다고 생각하는 것들 다 써줘"라는 요청에 Claude가 작성. 상세하게 말할수록 상세하게 반영됩니다
• 표 계산은 결정론 — 예산표 합계 7,000 + 30,000 = 총계 37,000천원, 수기 계산 착오 없음
• 구조도 바꿉니다 — 장 추가/복제, 표 행 추가·삭제(서식 승계), 쪽나눔까지. "5장 뒤에 강사진 장 추가해줘"가 통합니다
• 기존 양식 재활용 — 작성 완료된 옛 기획서를 주고 "○○사업용으로 바꿔줘"라고 하면 그 문서를 양식 삼아 내용만 전면 교체 (서식 무손상)

30초 설치

Claude Code에서:

/plugin marketplace add 6aneffy/hwpx-kit
/plugin install hwpx-kit@hwpx-kit-market

이게 전부입니다. CLI 런타임은 첫 사용 때 스킬이 알아서 설치를 진행합니다 (PC에 Python 3.10+만 있으면 됩니다).

pip install hwpx-kit-cli

# Windows 일괄 (CLI + 플러그인 등록)
irm https://raw.githubusercontent.com/6aneffy/hwpx-kit/main/install.ps1 | iex

스킬 (Claude Code 플러그인)

스킬은 사용자에게 필수 정보를 먼저 묻고(선택지 UI), 초안을 확정받은 뒤 작업합니다. 말하지 않은 값을 지어내지 않습니다.

CLI

모든 명령은 --json으로 한 줄 JSON 봉투(ok/data/warnings/error)를 반환합니다. 종료 코드: 0 성공 · 1 오류 · 2 부분 성공.

# 읽기·분석
hwpx-kit analyze 양식.hwpx --json            # 채울 수 있는 필드 탐지 (fill_key 반환)
hwpx-kit read 문서 --format md               # 본문 추출 — hwpx·PDF·DOCX·XLSX 내장 지원
hwpx-kit outline 문서.hwpx --json            # 문단·표 배치 지도 (삽입 앵커 탐색)
hwpx-kit table-map 문서.hwpx --table 3 --json # 표 셀 좌표·병합 상태
hwpx-kit validate 문서.hwpx --json           # 구조 검증

# 채우기·편집 (원본 불변 — 항상 --out 사본)
hwpx-kit fill 양식.hwpx --data 값.json --out 결과.hwpx
hwpx-kit fill-batch 양식.hwpx --rows 명단.xlsx --template 값틀.json --out-dir 결과/ --name "{성명}_위촉장.hwpx"  # 메일머지
hwpx-kit inspect 결과.hwpx --json            # 제출 전 검수 — 잔여 마커·공문 표기·개인정보·문서 구조·미리보기 잔존
hwpx-kit inspect 결과.hwpx --checks layout --json  # 셀 넘침(내용 잘림 위험) 추정 경고
hwpx-kit open-check 결과.hwpx --json         # (진단용) 한글 실열림 확인 — 한글을 자동 구동하므로 개발·회귀 전용
hwpx-kit table-set 문서.hwpx --table 3 --data 셀.json --out 결과.hwpx   # 좌표 셀 쓰기
hwpx-kit table-clear 문서.hwpx --table 3 --rows 1-20 --out 결과.hwpx    # 셀 내용 비우기
hwpx-kit table-copy 문서.hwpx --table 1 --after-table 4 --out 결과.hwpx # 표 통째 복제 (서식·병합 유지)
hwpx-kit table-new 문서.hwpx --rows 6 --cols 4 --like-table 3 --after-text "앵커" --out 결과.hwpx
hwpx-kit row-add 문서.hwpx --table 3 --like 2 --count 3 --out 결과.hwpx      # 행 추가 (기준 행 서식 승계)
hwpx-kit row-del 문서.hwpx --table 3 --rows 5-7 --out 결과.hwpx              # 행 삭제
hwpx-kit row-height 문서.hwpx --table 3 --like 1 --rows 2-5 --out 결과.hwpx  # 행 높이 정돈
hwpx-kit table-build 문서.hwpx --spec 표스펙.json --at-text "앵커" --out 결과.hwpx  # 표 원샷 생성 (병합·색·열폭·정렬·내용)
hwpx-kit cell-merge 문서.hwpx --table 3 --range "0,0:0,2" --out 결과.hwpx     # 셀 병합 (해제는 cell-split)
hwpx-kit cell-color 문서.hwpx --table 3 --range "0,0:0,5" --color "#D9E5FF" --out 결과.hwpx  # 셀 배경색
hwpx-kit col-width 문서.hwpx --table 3 --widths "2,3,3,2" --out 결과.hwpx     # 열 너비 비율
hwpx-kit cell-align 문서.hwpx --table 3 --range "0,0:9,5" --align center --out 결과.hwpx  # 셀 정렬
hwpx-kit page-break 문서.hwpx --table 5 --out 결과.hwpx                 # 쪽나눔 (새 장 시작)
hwpx-kit page-setup 문서.hwpx --orientation landscape --margins "20,20,15,15" --out 결과.hwpx  # 용지·방향·여백·다단
hwpx-kit image-add 문서.hwpx --image 도장.png --at-text "(인)" --width-mm 20 --out 결과.hwpx  # 직인·사진
hwpx-kit image-list 문서.hwpx --json                                    # 본문 이미지 목록 (편집 대상 확인)
hwpx-kit image-replace 문서.hwpx --index 0 --image 새로고.png --out 결과.hwpx  # 이미지 교체 (크기·위치 유지, resize/del도)
hwpx-kit seal 문서.hwpx --image 도장.png --at-text "행정안전부장관" --dx-mm 25 --out 결과.hwpx  # 발신명의 위 날인 (겹침)
hwpx-kit toc-add 문서.hwpx --at-text "앵커 문단" --out 결과.hwpx        # 목차 삽입 — 쪽번호는 한글 COM 실측 (후보 확인은 toc)
hwpx-kit note-add 문서.hwpx --at-text "앵커 문단" --text "각주 내용" --out 결과.hwpx  # 각주/미주
hwpx-kit link-add 문서.hwpx --at-text "앵커 문단" --url "https://..." --display "안내" --out 결과.hwpx  # 하이퍼링크 (책갈피는 bookmark-add)
hwpx-kit shape-add 문서.hwpx --type line --at-text "앵커 문단" --width-mm 150 --out 결과.hwpx  # 구분선·도형
hwpx-kit header-footer 문서.hwpx --footer "대외비" --page-number center --out 결과.hwpx

# 변환·생성
hwpx-kit fmt --amount 12340 --json           # 금12,340원(금일만이천삼백사십원)
hwpx-kit fmt --date 20260101 --json          # 2026.1.1.(목)
hwpx-kit convert 문서.hwp --json             # .hwp → .hwpx (Windows + 한글)
hwpx-kit export 문서.hwpx --to docx --json   # 워드로 내보내기 (Windows + 한글)
hwpx-kit generate 초안.md --out 새문서.hwpx   # Markdown → 공문서 (kordoc)
hwpx-kit render 문서.hwpx --engine com --out p.pdf   # 한글 실물 PDF 미리보기 (정확, Windows+한글) / kordoc SVG는 --engine kordoc

fill_key 계약

analyze가 주는 키를 그대로 데이터 JSON의 키로 씁니다.

요구 사항

아키텍처

Claude Code 스킬 6종 ──→  hwpx-kit CLI (47 명령, JSON 봉투)
                              └─ adapter/  ← 엔진 격리 계층
                                  ├─ python-hwpx    hwpx 분석·채우기·표 조작
                                  ├─ pypdf·python-docx·openpyxl   타 포맷 읽기
                                  ├─ pyhwpx(COM)    .hwp 변환·docx 내보내기
                                  └─ kordoc         구형 .hwp·생성·렌더 (선택)
templates/ 기본 계획서 템플릿 (표지·장 헤더·표 골격, 마커 내장)

설계 불변 원칙: ① 원본 절대 수정 금지 ② --json stdout은 봉투 한 줄만 ③ 서식은 항상 보존 (셀을 비워도 글자모양이 유지되어 재기입 시 원래 서식을 물려받음).

민감정보 처리 (secure 모드)

주민번호·계좌 같은 값은 AI 모델을 거치지 않고 채울 수 있습니다: 사용자가 값 파일을 직접 작성 → 스킬은 경로만 전달 → fill --secure가 CLI에서만 읽어 채움. --secure는 하나라도 못 채우면 산출물 없이 실패하고(부분 채움 방지), 출력에 값을 노출하지 않습니다. 제출 전 inspect로 개인정보 잔존(주민번호·전화·이메일 패턴)도 기계 검사할 수 있습니다.

🚧 같은 코어를 MCP 서버로 노출하는 버전도 제작 중입니다 (Claude Desktop 등 MCP 클라이언트용).

검증

• 자동 테스트 212개 (pytest)
• 실서식 수렴 테스트: 보도자료·신청서·계획서·회의록·공고문 5계열, 실제 공공기관 문서 30여 종으로 analyze→fill→validate 왕복
• 실사용 시나리오 테스트 다수 — 백지 생성 완주, 장·표 동적 추가, 보도자료 변환, 외부 사용자 설치·작성 검증 (발견된 문제는 즉시 수정 반영)

라이선스

Apache-2.0 · © 2026 6aneffy

이슈·PR 환영합니다. 특히 실제 기관 양식에서의 analyze/fill 실패 사례 제보가 가장 값집니다 (단, 기관 내부 문서를 이슈에 첨부하지 마세요 — 재현 가능한 합성 예시로 부탁드립니다).