한 달에 신청서 수십 건을 받아서 이름, 소속, 연락처를 하나하나 손으로 입력하는 업무를 해 보신 적 있으신가요. 열어서 칸 찾고, 타이핑하고, 저장하고, 다음 파일을 여는 일이 반복되다 보면 오타가 나고 서식이 틀어집니다. 그래서 이번에는 kordoc의 쓰기 기능을 실제로 돌려 봤습니다.
이 글은 kordoc 입문 시리즈 4편입니다. kordoc이 무엇인지부터 보고 싶으시면 필라글 kordoc 설치부터 사용법까지, HWP·PDF를 AI가 읽게 만드는 MCP 완전 가이드를, 명령어 기본기는 2편 kordoc CLI 사용법, npx 한 줄로 HWP를 마크다운으로 변환하는 법을, Claude 연결은 3편 kordoc Claude Desktop 연결 방법을 먼저 보고 오셔도 좋습니다. 여기서는 읽기에서 한 걸음 더 나가서, 문서를 채우고, 만들고, 고치는 세 가지를 다룹니다.
쓰기 기능은 세 가지만 알면 됩니다
kordoc의 쓰기 명령은 많아 보이지만 핵심은 셋입니다. fill은 이미 있는 양식의 빈칸에 값을 채웁니다. generate는 마크다운으로 쓴 글을 공문서 형식의 HWPX로 만들어 줍니다. patch는 원본 문서를 마크다운으로 뽑아서 고친 뒤, 원본 서식은 그대로 둔 채 바뀐 내용만 반영합니다.
세 명령의 차이를 한 줄로 외우면 이렇습니다. 틀이 있고 값만 넣을 때는 fill, 틀부터 새로 만들 때는 generate, 기존 문서를 부분 수정할 때는 patch입니다.
실습을 위해 테스트용 신청서를 만들었습니다
실제 기관 양식을 올리면 보안 문제가 있어서, 테스트용 신청서를 kordoc의 generate로 만들었습니다. 이름, 소속, 연락처, 이메일, 신청 과정, 신청일 칸이 비어 있는 표 하나짜리 양식입니다. 마크다운은 이렇게 썼습니다.
# 교육 참가 신청서
| 성명 | | 소속 | |
| --- | --- | --- | --- |
| 연락처 | | 이메일 | |
| 신청 과정 | | 신청일 | |
위와 같이 교육 참가를 신청합니다.이걸 HWPX로 바꾸는 명령은 이렇습니다.
npx kordoc generate 신청서.md -o 신청서.hwpx --preset 보고서여러분은 이 단계를 건너뛰고 가지고 계신 실제 HWPX 양식으로 바로 시작하시면 됩니다. 참고로 fill이 서식을 그대로 보존하는 방식은 HWPX 기준입니다. HWP 5.x 파일은 먼저 npx kordoc to-hwpx 파일.hwp로 HWPX로 바꾼 뒤 쓰시는 편이 안전합니다.
fill 1단계, 어떤 칸이 인식되는지 먼저 확인하기
값을 채우기 전에 반드시 해 보시길 권하는 단계가 있습니다. 양식에서 kordoc이 어떤 칸을 입력란으로 인식하는지 보는 것입니다.
npx kordoc fill 신청서.hwpx --dry-run실행하면 파일은 만들어지지 않고, 인식된 필드 목록이 JSON으로 나옵니다. 제 샘플에서는 성명, 소속, 연락처, 이메일, 신청 과정, 신청일이 각각 라벨과 현재 값, 표 안의 행과 열 위치와 함께 잡혔습니다. 눈여겨볼 점은 “신청 과정”처럼 두 단어로 된 라벨도 하나의 이름으로 인식됐다는 것입니다. 나중에 값을 넘길 때 이 라벨 이름이 곧 열쇠가 됩니다.
실제 기관 서식은 훨씬 복잡합니다. 이 단계에서 내가 채우려는 칸이 목록에 안 나오면 그 칸은 이후에도 채워지지 않으니, 본 작업 전에 꼭 확인하세요.
fill 2단계, JSON 파일로 한 번에 채우기
채울 값은 JSON 파일로 준비합니다. 키는 방금 확인한 라벨 이름입니다.
{
"성명": "홍길동",
"소속": "에이다루트",
"연락처": "010-1234-5678",
"이메일": "hong@example.com",
"신청 과정": "AI 에이전트 입문",
"신청일": "2026-11-10"
}그리고 실행합니다.
npx kordoc fill 신청서.hwpx -j 값.json -o 신청서_작성완료.hwpx터미널에는 “6개 필드 채움 (원본 스타일 보존)”이라는 메시지가 나왔습니다. 결과 파일을 다시 읽어 보니 여섯 칸이 모두 제자리에 들어가 있었고, 표 구조와 아래 문장도 그대로였습니다. 구조가 깨지지 않았는지 보려고 validate 명령도 돌려 봤는데 구조 검증을 통과했습니다.
npx kordoc validate 신청서_작성완료.hwpx값이 두세 개뿐이라면 JSON 파일 없이 명령줄에서 바로 넘겨도 됩니다.
npx kordoc fill 신청서.hwpx -f '성명=홍길동,소속=에이다루트' -o 결과.hwpx값에 쉼표가 들어가거나 항목이 많으면 JSON 파일이 훨씬 안전합니다.
키가 틀리면 넘어가지 않습니다
자동화에서 제일 무서운 건 틀렸는데 아무 말도 없는 경우입니다. 그래서 일부러 없는 칸 이름을 섞어서 넣어 봤습니다.
npx kordoc fill 신청서.hwpx -f '성명=김철수,없는칸=테스트' -o t1.hwpx결과는 “1개 필드 채움”과 함께 “매칭 실패: 없는칸” 경고가 나왔습니다. 맞는 칸은 채우고, 못 찾은 키는 명시적으로 알려 주는 방식입니다. 대량 처리 스크립트를 만들 때는 이 경고 줄을 검사해서 실패 건을 따로 모아 두세요.
값이 정확히 어느 칸에 들어갈지 미리 보고 싶다면 --dry-run에 값 파일을 함께 줍니다. 그러면 키별로 대상 칸의 표 번호와 행, 열이 나옵니다. 제 샘플에서는 눈에 보이는 신청서 표가 0번이 아니라 1번으로 나왔는데, 제목 영역이 따로 표 구조로 만들어져 앞 번호를 차지한 것으로 짐작합니다. 번호가 예상과 달라도 당황하지 마시고, 이 번호는 문서 안의 표를 순서대로 센 값이라고 이해하세요.
내장 기안문 서식으로 공문서 만들기
양식 파일이 아예 없을 때를 위해 kordoc에는 표준 기안문 서식이 들어 있습니다. 목록은 이렇게 확인합니다.
npx kordoc fill --list-templates일반기안문(gian)이 보였고, 필드 이름으로 행정기관명, 수신자, 경유, 제목, 본문, 붙임, 발신명의, 기안자, 검토자, 결재권자, 시행번호, 시행일 같은 것들이 나열되어 있었습니다. 일반기안문은 누름틀 23곳, 간이기안문(gian-simple)은 13곳이라고 공식 문서에 안내되어 있습니다. 대외 시행문은 일반기안문, 내부결재 보고서는 간이기안문을 고르면 됩니다.
저는 필드 중 여섯 개만 채워 봤습니다.
{
"행정기관명": "에이다루트",
"수신자": "내부결재",
"제목": "교육 참가 신청 협조 요청",
"본문": "다음과 같이 교육 참가를 신청하오니 협조하여 주시기 바랍니다.",
"기안자": "홍길동",
"시행일": "2026. 11. 10."
}npx kordoc fill --template gian -j 기안.json -o 기안문.hwpx결과를 읽어 보니 기관명, 수신, 제목, 본문이 제자리에 들어갔고 “붙임 1부. 끝.”도 서식 그대로 남아 있었습니다. 시행일은 시행 항목 괄호 안에 들어갔고, 채우지 않은 결재권자나 접수번호 같은 칸은 비어 있었습니다. 이름을 안 주면 비워 두는 방식이라, 필요한 칸은 모두 JSON에 넣어야 한다는 뜻입니다.
generate, 마크다운 초안을 공문서 HWPX로
AI에게 보고서 초안을 쓰게 하고 그걸 한글 문서로 받고 싶을 때 쓰는 명령이 generate입니다. 마크다운으로 쓴 간단한 계획서로 시험해 봤습니다.
# 문서 자동화 도입 계획
> 반복되는 공문서 작성 시간을 줄이기 위해 AI 문서 도구를 도입하고자 함
## 1. 추진 배경
- 월 40건 이상의 신청서를 수작업으로 입력 중
- 오기입과 서식 깨짐이 반복적으로 발생
- 보고서 형식이 부서마다 달라 검토에 시간이 소요됨
## 2. 추진 계획
| 단계 | 내용 | 기간 |
| --- | --- | --- |
| 1단계 | 현황 분석 | 11월 |
| 2단계 | 시범 적용 | 12월 |npx kordoc generate 계획.md -o 계획.hwpx --preset 보고서처음에는 제목 바로 아래 인용문 없이 돌렸더니 “보고서 요약박스가 없습니다”라는 경고가 나왔습니다. 보고서 프리셋은 제목 바로 뒤의 인용문을 요약 상자로 쓰는데, “하고자 함”으로 끝나는 한 문장을 넣으라는 안내였습니다. 위처럼 인용문을 넣으니 경고가 사라졌습니다.
렌더링 결과는 꽤 그럴듯했습니다. 마크다운의 하이픈 목록이 공문서의 □와 ㅇ 항목부호로 바뀌었고, “1. 추진 배경” 같은 소제목은 로마 숫자 장 헤더로 바뀌었습니다. 표는 머리 행에 음영이 들어갔고 아래에는 “- 1 -” 형태의 쪽번호가 붙었습니다. 한 가지 눈에 띈 점은, 요약 상자 문장이 길면 글자가 상자 오른쪽 끝까지 닿는다는 것입니다. 요약은 짧게 쓰는 편이 모양이 좋습니다.
npx kordoc render 계획.hwpx --format png --pages 1 -d ./png이 명령으로 결과를 그림으로 뽑아서 확인할 수 있습니다. 한글을 열지 않고도 결과를 눈으로 확인할 수 있는 점이 편합니다.
공문서 표기법도 검사해 줍니다. generate에 --gate를 붙이면 표기법, 문체, 윤문, 구성을 검사해서 통과하지 못하면 파일을 만들지 않습니다. 제 계획서는 게이트를 통과했습니다. 따로 lint 명령으로 표기법만 검사할 수도 있는데, “2026.11.10″이라고 쓴 문장을 넣어 보니 날짜 온점 뒤에 한 칸씩 띄워야 한다며 “2026. 11. 10.”처럼 쓰라고 오류로 알려 줬습니다. 사람이 놓치기 쉬운 부분입니다.
patch, 원본 서식은 그대로 두고 내용만 고치기
실무에서 가장 자주 쓰게 될 기능이 이것입니다. 문서를 처음부터 다시 만들면 로고와 글꼴, 결재란이 다 날아가는데, patch는 고친 내용만 반영합니다. 과정은 세 단계입니다.
첫 번째로 원본을 마크다운으로 뽑습니다. 이때 --keep-layout-tables 옵션을 꼭 붙여야 원본 표 구조가 유지됩니다.
npx kordoc 계획.hwpx --keep-layout-tables -o 편집.md두 번째로 편집.md를 열어 고칩니다. 저는 “월 40건”을 “월 60건”으로, 표의 “12월”을 “12월~1월”로 바꿨습니다. 세 번째로 패치를 실행합니다.
npx kordoc patch 계획.hwpx 편집.md -o 계획_반영.hwpx결과는 “2개 변경 적용 (원본 서식 보존)”이었고, 이어서 “편집 마크다운과 재파싱 결과 완전 일치”라는 검증 메시지가 나왔습니다. 고친 내용이 제대로 들어갔는지 스스로 확인한 뒤 알려 주는 구조입니다. 원본과 결과를 compare로 비교해 보니 추가 0, 삭제 0, 변경 2, 동일 7로, 제가 고친 두 곳만 달라져 있었습니다.
npx kordoc compare 계획.hwpx 계획_반영.hwpx문단을 새로 추가하는 편집도 해 봤습니다. 마크다운에 “ㅇ 표준 서식 도입 시 검토 시간 단축 기대”라는 줄을 하나 끼워 넣고 패치했더니 “3개 변경 적용”으로 반영됐습니다. 새 문단은 같은 부호를 쓰는 기존 문단의 서식을 따라가기 때문에, 이웃 줄과 들여쓰기와 모양이 같아집니다.
사소한 점이지만 하나 알려 드립니다. 패치 후 결과를 마크다운으로 다시 읽으면 물결표가 12월\~1월처럼 역슬래시가 붙어서 보입니다. 마크다운 쪽 표기 때문에 그렇게 보일 뿐, 문서 안의 XML을 확인해 보니 글자는 12월~1월 그대로였습니다. 놀라서 원본을 의심하지 않으셔도 됩니다.
실무에 쓰기 전에 알아 둘 점
제가 해 본 것은 단순한 표 하나짜리 양식과 짧은 보고서입니다. 실제 기관 양식은 표 안에 표가 들어가거나 병합 셀이 많아서, --dry-run으로 칸 매칭부터 확인하지 않고 바로 채우면 엉뚱한 칸에 들어갈 수 있습니다. 같은 라벨이 문서에 두 번 나올 때를 대비한 옵션도 있습니다. --require-unique를 주면 한 키가 두 곳 이상에 매칭될 때 거부한다고 공식 문서에 안내되어 있습니다.
결과 파일은 반드시 한글에서 열어 사람이 한 번 확인하세요. kordoc의 검증이 통과했다고 해서 한컴오피스에서 모양이 똑같이 보인다는 보장까지는 없습니다. 암호가 걸린 파일은 --password로 열 수 있지만, 한컴 문서보안(DRM)이 걸린 파일은 열 수 없습니다.
개인정보가 많은 신청서를 다룬다면 redact 명령으로 주민등록번호나 전화번호를 가려 둘 수 있습니다. 다만 자동 탐지 보조 도구이므로 결과를 사람이 최종 확인해야 하고, 이미지 속 글자는 탐지하지 못한다고 문서에 분명히 적혀 있습니다.
마무리, 읽는 도구에서 쓰는 도구로
정리하겠습니다. 이미 있는 양식에 값을 넣을 때는 fill로 먼저 --dry-run 확인을 하고, 값은 JSON으로 넘깁니다. 맞지 않는 키는 경고로 알려 주니 그 줄을 놓치지 마세요. 틀부터 새로 만들 때는 generate에 프리셋을 주고, --gate로 표기법까지 걸러 냅니다. 기존 문서를 고칠 때는 --keep-layout-tables로 뽑아서 편집한 뒤 patch로 반영하면, 서식은 그대로이고 고친 곳만 바뀝니다.
처음에는 fill로 작은 양식 하나부터 해 보시길 권합니다. 칸이 제대로 들어가는 걸 한 번 보고 나면 generate와 patch는 훨씬 쉽게 느껴집니다.
마지막 5편에서는 방향을 바꿔서 RAG 쪽으로 갑니다. 공문서를 검색 가능한 지식으로 만들기 위해 청크로 나누고, 스캔한 PDF를 OCR로 읽는 방법을 [kordoc RAG 청크 변환과 스캔 PDF OCR](5편 링크)에서 이어 가겠습니다.