마크다운 한 벌로, 그림까지 박힌 한글 보고서 — kordoc을 kdr로 키운 기록

마크다운만 쓰면, 그림까지 박힌 한글(HWPX) 보고서가 통째로 나온다. 오픈소스 kordoc을 포크해 이미지 임베드와 디자인을 더하고, AI가 설계·삽화·조립·검증까지 하는 스킬 kdr로 키웠다. 코드는 모두 깃허브에 올려뒀다.

왜 만들었나

한국에서 공공·기업 문서의 사실상 표준은 한글(HWP/HWPX)이다. 그런데 이걸 자동으로 생성하려고 하면 길이 거의 없다. 마크다운으로 초안을 쓰고, 표를 만들고, 인포그래픽을 넣고, 다시 한글에 옮겨 붙이는 일을 매번 손으로 했다. R&D 제안서처럼 표와 그림이 많은 문서일수록 이 옮기기 작업이 통째로 반나절을 잡아먹었다.

"마크다운 한 벌만 쓰면 그림까지 들어간 완성된 HWPX가 나오게 할 수 없을까?" 이게 출발점이었다.

kordoc — 좋은 출발점

검색 끝에 kordoc(by chrisryugj)을 찾았다. HWP/HWPX를 파싱하고 생성하는 타입스크립트 라이브러리로, 마크다운→HWPX 변환의 뼈대가 이미 있었다. 다만 내가 필요한 두 가지가 비어 있었다.

• 이미지 임베드가 없었다. 인포그래픽이 핵심인 문서엔 치명적이었다.
• 디자인이 밋밋했다. 폰트·간격·표 머리·여백이 보고서 수준이 아니었다.

그래서 포크했다. 없는 건 직접 채우면 된다.

kordoc → kdr로 키우기

포크한 kordoc에 먼저 이미지 임베드(HWPX의 hp:pic 구조)를 붙였다. 그리고 내가 쓴 책 『깔끔한 보고서 디자인 노하우』의 원칙을 깔보디노 프리셋으로 코드에 박아 넣었다. 메인 1색, 강조할 것만 강조, 표 머리는 굵게·가운데, 본문 줄간격 160%처럼.

그 위에 kdr라는 Claude Code 스킬을 씌웠다. 흐름은 네 단계다.

1. 설계 — 주제를 받아 마크다운으로 문서를 구성한다(표·그림 자리·톤).
2. 이미지 생성 — 삽화·도식을 AI(Codex 또는 Gemini)로 만든다.
3. 조립 — 확장한 kordoc으로 텍스트·표·이미지를 단일 HWPX로 합친다.
4. 검증 — 임베드된 이미지 수·표·레이아웃을 실제로 확인한다.

진짜 어려운 건 행복한 경로가 아니었다

만들면서 배운 건 대부분 HWPX의 함정에서 나왔다. 몇 개만 적어둔다. 같은 길을 가는 사람이 시간을 아끼길 바란다.

• CRLF가 제목을 깨뜨린다. 윈도우에서 저장한 마크다운의 줄바꿈(\r\n) 때문에 # 제목 파싱이 통째로 어긋났다. 제목에 #가 글자 그대로 찍히는 증상. 줄바꿈 정규화 한 줄로 해결.
• 속성 값이 직관과 반대였다. 한글 어절(낱말 단위) 줄나눔을 켜는 값이 BREAK_WORD다. 이름만 보면 "낱말을 깨라"인데, 실제로는 낱말을 지킨다. 반대로 KEEP_WORD가 글자 단위로 깨버린다. 이걸 거꾸로 알고 한참 헤맸다.
• 결과를 못 보고 고치는 게 가장 큰 적이었다. XML만 보고 추측으로 고치니 자꾸 빗나갔다. 그래서 한글(HWP) COM으로 HWPX를 직접 PDF·이미지로 렌더해서 눈으로 보는 자가검증 루프를 만들었다. AI가 자기 출력물을 직접 보고 단어 깨짐·여백·정렬을 잡는다. 이게 품질을 결정적으로 끌어올렸다.
• 여백은 이미지를 줄여서가 아니라 글로 채운다. 페이지 하단이 비면 그림을 작게 줄이고 싶어지지만, 그러면 그림만 초라해진다. 큰 그림은 그대로 두고, 그 그림을 설명하는 문장을 더해 공간을 채운다. 공간도 메우고 설득력도 올라간다. 이 원칙을 스킬에 못 박아뒀다.

결과 — 마크다운 한 벌이 이렇게 나온다

아래는 kdr로 만든 데모 보고서 9쪽이다(내용·기관·수치는 시연용 가상 정보). 표지부터 표·인포그래픽·설명까지, 마크다운과 AI 생성 이미지만으로 조립된 결과다.

표 머리의 색과 정렬, 본문 줄간격, 그림 아래 설명으로 채운 여백 — 손으로 옮겨 붙이지 않고 마크다운에서 바로 나온 모습이다.

깃허브

코드는 공개해뒀다. 한글 보고서 자동화로 고생하는 분께 도움이 되면 좋겠다.

• kdr 스킬: github.com/icenovel-rgb/kdr
• kordoc 포크: github.com/icenovel-rgb/kordoc (원본 kordoc by chrisryugj)

원본 kordoc이 든든한 뼈대를 줬고, 거기에 이미지와 디자인, 그리고 "AI가 자기 출력을 보고 고치는" 루프를 더했다. 도구도 결국 AI와 함께 만들어 기록한다. 다음 보고서는 더 적게 손대고 더 빨리 나올 것이다.