한글(HWP)문서, AI가표까지 제대로읽게
중급자용© AIKOREACLUBchrisryugj/kordoc
한글(HWP) 문서, AI가 표까지 제대로 읽게
HWP·HWPX 같은 한글 문서와 PDF, 엑셀을 AI가 읽기 좋은 글로 바꾸고, 반대로 AI가 쓴 내용을 공문서 HWPX로 만들거나 양식 칸을 채워 주는 도구예요
구청 공문, 학교 가정통신문, 정부 지원사업 신청서. 한국에서 일하면 한글(HWP) 파일을 피할 수 없어요. 그런데 이걸 AI에게 맡기려고 글자만 복사해 붙이면, 칸을 합친 표가 풀리면서 어느 값이 어느 줄에 붙은 건지 엉켜 버려요. 공문서 표에는 이렇게 합친 칸이 흔하죠.kordoc은 광진구청에서 7년 동안 HWP와 씨름한 지방공무원이 만든 도구예요. 합친 칸까지 살린 표로 문서를 읽어 AI에게 넘기고, 거꾸로 AI가 쓴 글을 한글 공문서 서식으로 만들거나 신청서 칸을 채워 줘요. 최신판 4.24.41이 2026-11-03에 나왔을 만큼 자주 고쳐지는 저장소예요.
같은 법령 별표 한 건을 HWP와 스캔 이미지로 넣은 실제 출력이에요. 왼쪽 원본에서 빨갛게 표시된 합친 칸이 오른쪽 결과에서 rowspan(세로로 합친 칸 수), colspan(가로로 합친 칸 수)으로 그대로 남아요. 스캔 이미지는 글자 인식(OCR)이 자동으로 켜져요. README 움짤에는 HWPX와 PDF로 넣은 장면도 있어요.이미지·설명: chrisryugj/kordoc README (MIT)
칸을 합친 표, 글자만 뽑으면 생기는 일
수업료등 반환기준 (일부)
| 구분 | 반환사유 발생일 | 반환금액 |
|---|---|---|
| 가. 징수기간이 1개월 이내인 경우 | 교육시작 전 | 이미 낸 수업료등 전액 |
| 총교육시간의 1/3이 지나기 이전 | 이미 낸 수업료등의 2/3 | |
| 1/3이 지난 후부터 1/2이 지나기 이전까지 | 이미 낸 수업료등의 1/2 | |
| 총교육시간의 1/2이 지난 후 | 반환하지 않음 |
| 구분 | 반환사유 발생일 | 반환금액 |
|---|---|---|
| 가. 징수기간이 1개월 이내인 경우rowspan="4" | 교육시작 전 | 이미 낸 수업료등 전액 |
| 총교육시간의 1/3이 지나기 이전 | 이미 낸 수업료등의 2/3 | |
| 1/3이 지난 후부터 1/2이 지나기 이전까지 | 이미 낸 수업료등의 1/2 | |
| 총교육시간의 1/2이 지난 후 | 반환하지 않음 |
README 예시에 나온 법령 별표(대안교육기관에 관한 법률 시행령 별표 2)의 일부를 줄여 옮겼어요.
README의 실제 출력 장면을 이해하기 쉽게 저희가 다시 그린 예시예요. 실제 결과는 문서의 표 모양과 파일 형식에 따라 달라요.
한눈에
무엇인가요
kordoc은 한국 문서를 AI와 이어 주는 변환기예요. 한쪽은 읽기, 다른 쪽은 쓰기예요.읽기. HWP 3.x·5.x, HWPX, HWPML, PDF, 엑셀(XLS·XLSX), 워드(DOCX), 파워포인트(PPTX), 사진(PNG·JPG·WebP)을 마크다운이나 구조화된 데이터로 바꿔요. 한컴오피스가 없어도 파일을 직접 읽고, 스캔본은 내 컴퓨터에서 도는 한국어 OCR로 읽어요.쓰기. 마크다운으로 쓴 글을 보고서, 계획서, 개조식 같은 공문서 서식의 HWPX로 만들고, 신청서 양식의 빈칸이나 표준 기안문의 누름틀을 채워요. 옛 HWP를 서식 그대로 HWPX로 바꾸는 것도 돼요.확인. 두 문서를 칸 단위로 비교(신구대조)하고, 공문서 표기법과 AI 문체를 검수하고, 주민번호 같은 개인정보를 가려요.쓰는 방법은 셋이에요. 터미널 명령(CLI), AI에 붙이는 MCP 서버(도구 22개), 프로그램 안에 넣는 라이브러리.
함께 쓰는 도구 · 클로드 코드 · 클로드 데스크톱 · 커서 · 코덱스 · VS Code · 제미나이 CLI
이런 분께
- 공문, 기안문, 보고서를 매일 한글로 쓰는 공무원, 공공기관, 학교 행정실
- 지원사업 신청서처럼 HWP 양식 칸을 채워야 하는 소상공인, 스타트업
- 한국 공공 문서를 AI 검색(RAG)이나 챗봇에 넣으려는 개발자
어떻게 작동하나요
1. 표를 표 그대로 읽어요. HWP 안의 표를 칸 하나하나의 위치와 합친 범위까지 읽어서, 마크다운 안에 rowspan·colspan이 붙은 표로 내보내요. AI는 이 표를 보고 어느 값이 어느 줄에 속하는지 알 수 있어요.2. AI에 붙이면 파일 경로만 주면 돼요. npx -y kordoc setup 한 번이면 클로드 데스크톱, 클로드 코드, 커서, 코덱스 등에 MCP가 등록돼요. 그다음엔 대화에서 파일을 가리키기만 하면 AI가 읽고, 비교하고, 양식을 채워요.3. 양식은 칸 이름으로 채워요. '성명=홍길동' 처럼 이름표와 값을 주면 그 이름표 옆이나 아래 빈칸을 찾아 넣어요. 누름틀이 있는 서식이면 누름틀 이름부터 맞추고, 맞는 칸이 없는 값은 따로 알려 줘요.4. 쓸 때는 공문서 규칙을 입혀요. 마크다운 제목 바로 아래 인용문(> …하고자 함)은 요약 상자가 되고, 목록은 공문서 항목 부호 단계로 바뀌어요. 우리 기관 문서 몇 건으로 서식 묶음(기관팩)을 만들어 그 모양대로 새 문서를 낼 수도 있어요.핵심은 사람이 다시 맞추던 표의 칸 관계를, 읽을 때도 쓸 때도 깨지 않는다는 거예요.
바로 쓸 수 있나요
필요한 것Node.js 20 이상과 터미널. AI와 함께 쓰려면 클로드 데스크톱, 클로드 코드, 커서 같은 MCP를 지원하는 AI 도구
비용저장소 자체는 무료(MIT). 함께 쓰는 AI 도구 요금은 따로예요
시작하기
- Node.js 20 이상 준비
맥, 리눅스, 윈도우 모두 돼요. 터미널에서 node -v 로 버전을 확인해요.
- AI 도구에 연결
설치된 AI 도구(클로드 데스크톱, 클로드 코드, 커서, 코덱스, VS Code 등)를 골라 설정을 자동으로 넣어요. 끝나면 그 도구를 다시 켜요.
npx -y kordoc setup - 클로드 코드라면 플러그인으로도 돼요
두 줄을 차례로 입력해요. 상세 사용법은 HWP·HWPX 파일이나 공문서 작성 요청에 스킬이 알아서 켜진다고 적어요.
/plugin marketplace add chrisryugj/kordoc /plugin install kordoc@kordoc - 터미널에서 바로 변환
설치 없이 npx 로 실행해요. 결과 마크다운과 함께 그림은 images 폴더에 저장돼요.
npx kordoc 문서.hwp -o 문서.md
npx kordoc 문서.hwp -o 문서.md
README 자주 묻는 질문에 나온 첫 명령이에요. MCP로 연결했다면 대화에서 파일 위치를 알려 주고 읽어 달라고 하면 돼요.처음 쓰는 순서
npx -y kordoc setup쓰는 AI 도구에 MCP 등록, 도구를 다시 켜기npx kordoc 문서.hwpx -o 문서.md먼저 한 건을 변환해 표가 제대로 나오는지 보기npx kordoc fill 서식.hwpx -j 값.json --dry-run양식에 값이 어느 칸에 들어갈지 미리 확인npx kordoc fill 서식.hwpx -j 값.json -o 결과.hwpx실제로 채우기npx kordoc lint 결과.hwpx내보내기 전 표기법 검수
README와 상세 사용법에 나온 명령을 처음 쓰는 순서로 묶은 예예요.
명령 하나에 문서가 이렇게 바뀌어요
README와 상세 사용법에 나온 명령과 기능을 이해하기 쉽게 저희가 그린 예시예요. 실제 출력 모양과 지적 문구는 판 번호와 문서에 따라 달라요.
명령어 전체 17개, 언제 쓰나
읽기
kordoc 문서.hwpx -o 문서.md- 한글 문서를 마크다운으로 저장
kordoc *.pdf -d ./결과- 여러 파일 한 번에 변환
kordoc 스캔본.pdf --ocr- 스캔본을 내 컴퓨터 OCR로 읽기
kordoc 검토서.pdf --format chunks- AI 검색(RAG)에 넣기 좋은 조각으로
kordoc watch ./수신함 -d ./변환결과- 폴더에 들어오는 문서 자동 변환
양식
kordoc fill 신청서.hwpx --dry-run- 채울 수 있는 칸 목록만 보기
kordoc fill 신청서.hwpx -f '성명=홍길동'- 칸 이름으로 값 넣기
kordoc fill --template gian -j 값.json- 표준 일반기안문 만들기
kordoc seal 신청서.hwpx --image 도장.png- (인) 자리에 도장 찍기
쓰기·변환
kordoc generate 보고서.md --preset 보고서- 마크다운을 공문서 HWPX로
kordoc to-hwpx 문서.hwp- 옛 HWP를 서식 그대로 HWPX로
kordoc patch 원본.hwpx 편집.md- 고친 내용만 원본 서식에 반영
kordoc pack build 보고서1.hwpx 보고서2.hwpx- 우리 기관 서식 묶음(기관팩) 만들기
확인·보안
kordoc compare 구버전.hwp 신버전.hwpx- 두 판 비교(신구대조)
kordoc lint 보고서.md --gate --preset 보고서- 표기법·AI 문체·구성 검수
kordoc lint 예산편성.hwpx --budget- 예산 산출근거 검산
kordoc redact 민원서류.hwpx -o 마스킹.hwpx- 개인정보 가리기
모두 앞에 npx 를 붙여 설치 없이 실행해요. README와 상세 사용법(docs/usage.md)에 나온 명령 중 자주 쓸 만한 것만 골랐어요. 전체 옵션은 상세 사용법의 CLI 항목에 있어요.
AI 없이 터미널만으로도 돼요
한컴오피스 없이 파일을 직접 읽어요. 여러 파일은 별표(*)로 한 번에 바꿔요.
npx kordoc *.hwpx -d ./outputKORDOC_OFFLINE=1 을 켜면 바깥 통신을 모두 막고, OCR도 API 키 없이 내 컴퓨터에서 돌아요. 모델 옮기기는 폐쇄망 설치 문서에 있어요.
KORDOC_OFFLINE=1 npx kordoc 스캔본.pdf --ocr -o 스캔본.md비슷한 도구
kordoc은 한국 공문서(HWP)와 그 표·양식에 집중하고, 아래 둘은 더 넓은 문서 형식을 다루는 쪽이에요(각 README 기준).
주의할 점
- 개인정보 가리기 결과는 공개 전에 사람이 꼭 다시 봐야 한다고 상세 사용법이 적어요. 이미지 속 글자는 자동 탐지 대상이 아니고, 이름과 주소는 직접 켜야(--rules 에 name, address) 가려져요.
- AI에 MCP로 붙이면 AI가 내 컴퓨터 파일을 읽어요. KORDOC_ROOT 로 읽을 수 있는 폴더를 정해 두는 편이 안전해요.
- README의 정확도 숫자는 만든 사람이 정해 둔 문서 묶음으로 잰 값이에요. 표 구조가 맞는 것과 칸 내용, 화면 모양까지 똑같은 것은 다른 지표라고 README가 직접 밝혀요. 중요한 문서는 결과를 원본과 대조하세요.
- OCR은 처음 쓸 때 한국어 모델(약 18MB)을 내려받아요. 이미지 속 수식 인식 모델의 바탕(YOLOv8)은 AGPL-3.0 이라, 수식 OCR에 기대는 상용·비공개 제품을 만든다면 그 조건을 따로 확인하라고 적혀 있어요.
- 한글과컴퓨터의 공식 도구가 아니라 개인 개발자가 만든 오픈소스예요. 거의 매일 새 판이 나오니 업무에 쓸 땐 판 번호를 기록해 두세요.
더 보기
광진구청에서 7년간 일한 지방공무원이 만들었어요. README는 5개 공공 프로젝트에서 실제 관공서 문서 수천 건으로 검증했다고 적어요. 기안문 서식 등 일부는 rhwp(MIT) 같은 다른 오픈소스에서 가져왔어요.
상세 사용법 ↗공식 소개 페이지 ↗양식 일괄 채우기 시연 영상 ↗폐쇄망 설치 ↗벤치마크 상세 ↗깃허브 저장소 ↗
낯선 말
- HWP·HWPX · 한글 프로그램의 파일 형식이에요. HWP는 예전 방식, HWPX는 한글 2020 이후의 새 방식이에요
- 마크다운 · # 제목, - 목록처럼 간단한 기호로 구조를 적는 글 형식이에요. AI가 읽고 쓰기 편한 형식이에요
- rowspan·colspan · 표에서 세로로, 가로로 몇 칸을 합쳤는지 적는 표시예요
- MCP · AI가 바깥 도구를 불러 쓰게 이어 주는 표준 연결 방식이에요
- 누름틀 · 한글 서식에서 클릭해 내용을 채우게 만들어 둔 빈칸이에요
- 신구대조표 · 고치기 전과 고친 뒤를 나란히 놓고 바뀐 곳을 보여 주는 표예요
- RAG · AI가 답하기 전에 내 문서에서 관련 부분을 찾아 읽게 하는 방식이에요
댓글
AI 답은 참고 자료예요. 법·세금·돈·건강처럼 삶에 큰 영향을 주는 일에서는 AI 답이 정답이 될 수 없어요. 최종 판단은 전문가나 공식 기관에서 확인하세요.
