| name | kordoc |
| description | 대한민국 관공서 및 기업에서 사용하는 다양한 문서 포맷(HWP, HWPX, HWPML, PDF, XLSX, DOCX)을 파싱, 생성, 비교, 수정하기 위해 [kordoc](https://github.com/chrisryugj/kordoc) CLI를 사용하는 에이전트의 행동 지침 |
1. 목적 및 개요
본 기술 지침은 대한민국 관공서 및 기업에서 사용하는 다양한 문서 포맷(HWP, HWPX, HWPML, PDF, XLSX, DOCX)을 파싱, 생성, 비교, 수정하기 위해 kordoc CLI를 사용하는 에이전트의 행동 지침이다. 에이전트는 이 도구를 활용하여 LLM이 이해하기 가장 좋은 형태로 문서를 읽고, 다시 완벽한 공문서 형태로 출력해야 한다.
2. 핵심 명령어 레퍼런스
📄 문서 읽기 및 파싱
npx kordoc <파일명>
npx kordoc <입력파일> -o <출력파일.md>
- 구조화된 JSON 데이터 추출 (문서 구조 및 메타데이터 포함):
npx kordoc <입력파일> --format json
npx kordoc <입력파일> --pages 1-3
🏛️ 공문서 및 HWPX 생성 (역변환)
마크다운 서식을 기반으로 한국 행정 공문서 표준 서식(행정안전부 행정업무운영편람 근거)을 따르는 HWPX 문서를 생성한다.
npx kordoc generate <마크다운파일.md> -o <출력파일.hwpx>
npx kordoc generate <마크다운파일.md> -o <출력파일.hwpx> --preset <보고서|기안문|계획서|고시|회의록>
- 지원 프리셋:
보고서 (보고서, □○-ㆍ 불릿), 기안문 (공식 기안 서식), 계획서, 고시, 회의록
🔄 서식 보존 인플레이스(In-place) 패치
기존 한글 파일(.hwp, .hwpx)의 원본 디자인, 글꼴, 크기, 표 구조를 1바이트도 건드리지 않고 텍스트만 교체하거나, 문장을 표로 바꿀 때 사용한다.
npx kordoc patch <원본파일.hwpx> <편집된마크다운.md> -o <결과파일.hwpx>
- 동작 원리: 에이전트가
parse로 읽은 마크다운에서 텍스트만 수정한 뒤 patch에 넘기면 원본 서식이 100% 유지된 채 반영된다.
✏️ 양식 자동 채우기 (Form Filler)
신청서, 보고서 등 빈칸이나 괄호, 체크박스가 있는 템플릿 문서에 값을 자동으로 주입한다.
npx kordoc fill <템플릿.hwpx> -f '성명=홍길동,주소=서울' -o <결과.hwpx>
npx kordoc fill <템플릿.hwpx> -j <데이터.json> -o <결과.hwpx>
npx kordoc fill <템플릿.hwpx> --dry-run
🔍 신구대조표 (문서 비교)
두 문서의 차이점을 분석하여 바뀐 부분을 찾아내고 통계를 출력한다. (HWP와 HWPX 크로스 비교 가능)
npx kordoc compare <구버전> <신버전>
3. 에이전트 행동 지침 및 규칙 (Crucial Rules)
🔴 규칙 1: 대한민국 행정 공문서 항목부호 8단계 준수
--preset 보고서 등을 통해 문서를 생성할 때, 에이전트가 작성하는 마크다운 리스트의 중첩 깊이는 행정 표준에 의해 아래와 같이 강제로 변환된다. 마크다운 마커 기호(*, -, 1.)에 상관없이 들여쓰기 깊이(Depth)로 제어되므로 구조를 명확히 해야 한다.
- 1단계:
1., 2., 3.
- 2단계:
가., 나., 다.
- 3단계:
1), 2), 3)
- 4단계:
가), 나), 다)
- 5단계:
(1), (2), (3)
- 6단계:
(가), (나), (다)
- 7단계:
①, ②, ③
- 8단계:
㉮, ㉯, ㉰
🔴 규칙 2: 패치(patch) 기능의 제약 사항 인지
patch 명령은 원본 구조를 유지하는 기술이므로 새로운 문단을 추가하거나, 표의 행/열을 늘리거나 줄이는 편집은 거부(skip)된다.- 구조적인 변경(예: 표 추가, 대대적인 본문 추가)이 필요할 때는
patch 대신 generate 명령을 사용하여 새 문서를 빌드해야 한다.
- 단, v3.5.0부터 기존 문단을 마크다운 표 형태(
| ... |)로 수정하여 패치하면 원본 안에서 문장을 표로 인플레이스 변환하는 것은 전적으로 지원한다.
🔴 규칙 3: PDF 품질 신호 대응
PDF를 파싱한 후 출력 결과에 qualitySummary.needsOcr이 감지되거나 한글 깨짐 신호(low_text, high_pua)가 발생하면, 해당 PDF는 텍스트 층이 깨진 이미지 기반 문서다. 이때는 사용자에게 OCR 엔진 연동이 필요함을 리포팅해야 한다.
4. 추천 워크플로우 패턴
패턴 A: 기존 공문서 문구 수정 및 교정 (서식 보존)
npx kordoc 원본.hwpx -o 임시.md 로 문서를 읽는다.- 에이전트(LLM)가
임시.md 내용 중 오탈자, 비문, 또는 사용자가 요청한 가이드라인에 맞춰 마크다운 텍스트를 수정한다.
npx kordoc patch 원본.hwpx 수정본.md -o 최종결과.hwpx 를 실행하여 상사에게 보고할 수 있는 완벽한 서식의 한글 파일을 완성한다.
패턴 B: 마크다운 초안으로부터 기안문/보고서 신규 생성
- 에이전트가 기획서나 보고서 내용을 마크다운으로 풍부하게 작성한다. (표 포함 가능)
npx kordoc generate 초안.md -o 정부보고서.hwpx --preset 보고서 명령을 수행하여 표준 여백(위20/아래10/좌20/우20mm)과 명조(함초롬바탕) 글꼴, 자동 내어쓰기가 적용된 공문서를 생성한다.
