kordoc

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>

• JSON 파일을 이용한 대량 주입:

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단계: 1., 2., 3.
2. 2단계: 가., 나., 다.
3. 3단계: 1), 2), 3)
4. 4단계: 가), 나), 다)
5. 5단계: (1), (2), (3)
6. 6단계: (가), (나), (다)
7. 7단계: ①, ②, ③
8. 8단계: ㉮, ㉯, ㉰

🔴 규칙 2: 패치(patch) 기능의 제약 사항 인지

• patch 명령은 원본 구조를 유지하는 기술이므로 새로운 문단을 추가하거나, 표의 행/열을 늘리거나 줄이는 편집은 거부(skip)된다.
• 구조적인 변경(예: 표 추가, 대대적인 본문 추가)이 필요할 때는 patch 대신 generate 명령을 사용하여 새 문서를 빌드해야 한다.
• 단, v3.5.0부터 기존 문단을 마크다운 표 형태(| ... |)로 수정하여 패치하면 원본 안에서 문장을 표로 인플레이스 변환하는 것은 전적으로 지원한다.

🔴 규칙 3: PDF 품질 신호 대응

PDF를 파싱한 후 출력 결과에 qualitySummary.needsOcr이 감지되거나 한글 깨짐 신호(low_text, high_pua)가 발생하면, 해당 PDF는 텍스트 층이 깨진 이미지 기반 문서다. 이때는 사용자에게 OCR 엔진 연동이 필요함을 리포팅해야 한다.

---

4. 추천 워크플로우 패턴

패턴 A: 기존 공문서 문구 수정 및 교정 (서식 보존)

1. npx kordoc 원본.hwpx -o 임시.md 로 문서를 읽는다.
2. 에이전트(LLM)가 임시.md 내용 중 오탈자, 비문, 또는 사용자가 요청한 가이드라인에 맞춰 마크다운 텍스트를 수정한다.
3. npx kordoc patch 원본.hwpx 수정본.md -o 최종결과.hwpx 를 실행하여 상사에게 보고할 수 있는 완벽한 서식의 한글 파일을 완성한다.

패턴 B: 마크다운 초안으로부터 기안문/보고서 신규 생성

1. 에이전트가 기획서나 보고서 내용을 마크다운으로 풍부하게 작성한다. (표 포함 가능)
2. npx kordoc generate 초안.md -o 정부보고서.hwpx --preset 보고서 명령을 수행하여 표준 여백(위20/아래10/좌20/우20mm)과 명조(함초롬바탕) 글꼴, 자동 내어쓰기가 적용된 공문서를 생성한다.