Kordoc은 어디에 쓰나: HWP 문서를 읽고 채우고 비교하는 방법

HWP 문서를 읽는 도구가 왜 양식 채우기와 문서 비교까지 제공할까. 클코단에서는 Kordoc의 출력이 괜찮다는 반응에 이어 정작 어디에 써야 하는지 묻는 질문이 나왔다. 답은 문서 한 건의 변환보다 원본을 읽어 데이터를 뽑고 결과물을 다시 확인하는 작업에 있다.

HWP를 읽어야 다음 작업도 시작된다

Kordoc은 HWP·HWPX뿐 아니라 PDF, DOCX, XLSX, PPTX와 이미지도 Markdown 또는 구조화 데이터로 바꾼다. CLI, JavaScript 라이브러리, MCP 서버 중 작업 환경에 맞는 진입점을 고를 수 있다. Node.js 20 이상이 필요하다. CLI만 쓴다면 별도 전역 설치 없이 npx kordoc 문서.hwpx -o 문서.md로 변환한다. (github.com)

용도에 따라 출력 형식을 고르면 된다. 사람이 내용을 검토하거나 AI에 전달할 때는 Markdown이 편하다. 표의 칸이나 문서 정보를 프로그램에서 다룬다면 npx kordoc 검토서.hwpx --format json으로 블록·쪽별 내용·메타데이터를 받는다. 개발자는 라이브러리의 parse() 결과에서 markdown, blocks, metadata를 각각 사용할 수도 있다. (github.com)

예를 들어 여러 기관에서 받은 신청서를 하나씩 열어 항목을 옮기는 작은 팀이라면 먼저 원본을 JSON으로 읽어 필요한 칸을 추출할 수 있다. 반대로 문서의 내용만 검색 대상으로 넣으려면 Markdown이나 구조 청크 출력이 맞다. Kordoc 사용법 문서는 표를 독립 청크로 나누는 출력도 안내한다. 변환 명령 하나로 업무 자동화가 완성되지는 않는다. 다만 뒤따르는 검색·대조·입력 작업에 쓸 재료는 만들어 준다. (github.com)

기존 HWPX 양식을 채울 때 필요한 입력은 무엇인가

빈 양식에 반복해서 값을 적는다면 원본 HWPX와 입력값이 필요하다. 먼저 npx kordoc fill 신청서.hwpx --dry-run으로 도구가 찾은 필드를 확인한다. 이어 필드 이름에 맞춘 values.json을 준비하고 npx kordoc fill 신청서.hwpx -j values.json -o 결과.hwpx를 실행한다. Kordoc 사용법에 따르면 누름틀 이름을 우선 찾고 남은 입력값은 항목 라벨에 맞춘다. (github.com)

가령 양식에서 확인한 필드가 제목과 작성일이라면 JSON의 키도 그 이름에 맞춰야 한다. 출력은 값이 들어간 HWPX 파일이다. 같은 이름이 여러 곳에 잡히는 양식에는 --require-unique로 중복 매칭을 거부할 수 있다. 필드 확인 없이 ‘알아서 채워 달라’고 맡기는 것보다 무엇이 채워졌고 빠졌는지 살피기 쉽다. (github.com)

방에서는 Kordoc의 문서 처리 결과를 좋게 평가하는 의견이 나왔다. 하지만 그 대화만으로 특정 양식의 성공률까지 알 수는 없다. 서식이 복잡할수록 입력값의 정확성과 완성 파일의 화면 상태는 별도로 확인해야 한다.

특히 기존 문서의 문장까지 고치려면 양식 채우기가 아니라 서식 보존 패치 경로를 쓴다. --keep-layout-tables로 원본을 Markdown으로 추출해 수정한 뒤 patch 명령으로 HWPX에 반영하는 순서다. 도구는 반영하지 못한 편집을 건너뛴 사유와 함께 보고한다. (github.com)

스캔 PDF와 수정본 비교는 다른 문제다

글자를 선택할 수 없는 스캔 PDF는 일반 PDF 변환과 입력 조건이 다르다. Kordoc은 npx kordoc 스캔본.pdf --ocr -o 스캔본.md를 안내한다. 추출한 글이 깨진 PDF라면 쪽별 품질 신호를 확인해 OCR 재처리 여부를 결정할 수도 있다. 이미지와 스캔본의 글을 읽은 뒤에도 숫자와 표의 행·열은 원본과 대조해야 한다. (github.com)

두 파일 사이에서 무엇이 달라졌는지를 찾는 일은 별도다. npx kordoc compare 구버전.hwp 신버전.hwpx는 서로 다른 형식의 문서도 비교한다. 예컨대 사업계획서 수정본을 받았다면 먼저 두 파일을 대조하고 변경된 표와 문단을 검토할 수 있다. 최종 문서를 새로 쓰는 generate 명령이나 기존 파일에 값을 넣는 fill 명령과는 목적이 다르다. (github.com)

파싱 품질 수치는 조심해서 읽어야 한다. 프로젝트가 공개한 4.18.8 검증에서는 HWPX 2,286개 문서의 보이는 표 9,865개가 기준 표 구조와 일치했다. 개발 문서는 표의 구조, 셀 내용, 화면상 재현도를 서로 다른 지표로 구분한다. 표 구조 일치율을 ‘어떤 문서든 글과 모양이 완벽하다’는 보증으로 읽을 수 없는 이유다. (github.com)

에이전트 연결은 변환 다음의 선택지다

Kordoc은 특정 AI 도구에 종속된 기능이 아니다. npx -y kordoc setup으로 지원되는 클라이언트에 MCP를 등록하고 재시작하면 에이전트가 문서 파싱·비교·생성 도구를 호출할 수 있다. 공식 안내에는 Cursor, Codex 등 여러 클라이언트가 포함된다. 에이전트에게 문서를 분석시키려면 원본 파일을 읽을 권한과 원하는 산출물부터 정해야 한다. (github.com)

민감한 업무 문서라면 연결 범위가 더 중요하다. Kordoc 보안 문서는 KORDOC_ROOT를 설정하지 않은 MCP 서버가 허용 확장자의 파일을 넓게 읽을 수 있다고 명시한다. 이 설정으로 읽기·쓰기 경로를 지정한 디렉터리 아래로 제한할 수 있다. 문서 파싱 자체를 로컬에서 처리한다는 설명과 연결된 AI 서비스에 문서 내용을 전달해도 되는지는 별개의 판단이다. (github.com)

어디까지 맡기고 무엇을 직접 확인할까

PDF·Office 문서 파싱만 필요하다면 선택지는 Kordoc 하나가 아니다. Docling의 지원 형식 목록에도 PDF와 DOCX·XLSX·PPTX가 있다. 반면 HWP·HWPX 원본을 받아 Markdown으로 읽고 기존 양식을 채우거나 두 판본을 비교해야 한다면 Kordoc의 기능 조합이 작업에 직접 맞는다. 비교할 때는 ‘문서를 읽을 수 있는가’뿐 아니라 ‘원본 형식으로 무엇을 돌려받는가’를 함께 봐야 한다. (github.com)

최근 변경도 검증의 필요성을 보여 준다. Kordoc 저장소는 2026년 10월 8일 배포한 4.21.1에서 이미지 OCR의 글 순서와 테두리 없는 영수증 표 행 처리를 수정했다고 기록한다. 쓰는 사람 입장에서는 환영할 개선이지만 스캔 문서의 배치가 결과에 영향을 줄 수 있다는 신호이기도 하다.

Kordoc은 문서를 AI가 읽을 형태로 옮기는 데서 시작해 값을 채우고 차이를 찾는 데까지 쓸 수 있다. 다만 마지막 승인 전에 원본과 출력 파일을 나란히 보는 단계까지 없애 주는 도구는 아니다. (github.com)