Show GN: 나래 한글(나래팩) – AI 에이전트용 HWP/HWPX 편집·생성 CLI/스킬/템플릿 패키지

충청북도에서 4년차 특수교사로 일하고 있습니다.

원래 코딩에는 큰 관심이 없었습니다. 그런데 특수학교에서 처음 근무하면서, 일반 교육에는 과할 정도로 많은 에듀테크가 특수교육 쪽에는 너무 부족하고 환경도 열악하다는 걸 알게 됐습니다. 이쪽은 시장이 작아 돈이 안 되다 보니 개발자들이 관심을 갖기 어렵다는 점도 안타까웠습니다. 그래서 개발자 지인과 AI의 도움을 받아 특수교육 쪽 개발을 직접 해 보기로 했습니다.

왜 한글(HWP)인가

지금은 초등학교 특수학급에 있는데, 교육·공직 현장은 hwp에 꽁꽁 묶여 있다고 느낍니다. 기존에 쓰던 공문서 양식이 전부 한글이고, 공직 특유의 분위기까지 더해져서 자연스럽게 hwp로 올려야 할 것 같은 분위기가 있습니다. 편집이 필요 없고 서명이 들어간 문서만 PDF로 하고, 나머지는 웬만하면 엑셀이나 한글을 씁니다.

특히 교수학습지도안이나 교육계획처럼 표가 복잡한 고정 서식에 내용을 채워야 하는 문서가 많습니다. 이런 문서를 AI에게 맡기면 문서가 이상해지거나 완성도가 너무 낮았고, 수정도 제대로 되지 않았습니다.

3년 전까지는 언젠가 누군가가 hwp를 정복해서, AI로 딸깍하면 편집도 생성도 다 되겠거니 했습니다. 그런데 아직도 hwp의 벽은 견고했고, 얼마 전부터 "내가 그 누군가가 되어 보자"는 마음으로 만들기 시작했습니다.

접근성이 기준이었습니다

대부분의 선생님들은 아직 무료 계정으로 웹에서 AI를 쓰는 게 기본입니다. 그래서 설치가 복잡하면 안 되고, 가볍게 첨부하거나 GitHub 링크를 올리는 것만으로 한글 작업이 되어야 한다고 생각했습니다. 코딩 에이전트(Claude Code, Codex 등)에서는 같은 패키지를 로컬에서 그대로 쓸 수 있습니다.

CLI를 이렇게 설계했습니다

AI에게 매번 파이썬 코드를 짜게 하면 느리고, 서식이 깨지거나 파일이 손상되기 쉽습니다. 그래서 AI가 코드가 아니라 "작업 명세(JSON)"를 쓰게 만들었습니다.

python narae.py run job.json --result result.json

하나로 실행하고, 결과도 JSON으로 돌려줍니다. AI가 성공·실패를 스스로 확인할 수 있습니다.- 작업은 inspect(문서 구조 확인), edit(기존 문서 편집), create(새 문서 생성), render(미리보기) 네 가지입니다.

• 편집은 먼저 inspect로 표와 셀의 주소(예:
  body/3/cell/1/1/0

)를 얻고, 그 주소를 지정해서 고치는 순서입니다. AI가 문서 전체를 다시 쓰지 않고 필요한 칸만 건드립니다. - 정해진 연산자만 씁니다. 셀 병합·분할, 셀 내용 지정, 셀 서식(테두리·배경·굵기), 행 삽입·삭제, 표·그림 위치와 크기 조정 같은 것들입니다. AI가 바이너리를 직접 만지지 않습니다.

• 편집할 때 바뀌는 부분만 수정하고 나머지는 원본 그대로 두도록 만들었습니다. 표 서식이 깨지는 문제를 줄이려는 설계입니다.
• HWPX는 XML을, HWP 5.0은 바이너리를 직접 읽고 수정합니다. 한컴오피스가 없어도 되고, HWP는 이 방식이 실패하면 한컴 COM으로 넘어갑니다.
• "'비고' 셀 테두리 없애줘" 같은 자연어도 같은 연산자로 변환해서 실행합니다.
• AI가 읽을 규칙은 SKILL.md에 정리했습니다. 원본 위치 외에 불필요한 PDF·백업 파일을 남기지 않는 것, 쪽수가 밀릴 때는 글자 크기 대신 자간을 줄이는 것 같은 규칙입니다.
• 자주 쓰는 양식은 JSON 템플릿으로 저장해서 반복 사용할 수 있습니다. 기본으로 형식 템플릿 11종, 문구 템플릿 7종이 들어 있습니다.

실제로 쓰던 연구보고서 문서로 빈 칸에 사진 넣기, 표에 행 추가하기, 행 지우기, 표 테두리 투명하게 하기를 시험해 봤습니다.

아직 부족한 점

• 템플릿 추출과 쪽수 검증 같은 보조 도구는 현재 HWPX만 지원합니다. 업데이트를 통해 HWP도 지원할 예정입니다.
• 한글 문서마다 내부 구조가 달라서, 모든 문서에서 똑같이 동작한다고 장담하기는 어렵습니다. 새 양식에 적용할 때는 한컴오피스에서 열어 결과를 확인해 주세요.
• AI의 도움을 받아 만든 만큼, 놓친 부분이 많을 수 있습니다.
• 특수교육뿐 아니라 hwp/hwpx를 많이 쓰시는 분들께 도움이 되면 좋겠습니다. 안 되는 문서나 필요한 기능은 GitHub 이슈로 남겨 주시면 반영하겠습니다.