스프쌤
자동화

HWPX 문서 자동화와 AGENTS.md 기반 AI 에이전트 스킬 설계

✍ 야금야금⏱ 21분 소요2026-11-05👁
← 목록으로 돌아가기

공공기관과 일선 학교를 30년 넘게 묶어둔 HWP의 폐쇄적 장벽은, XML 기반 HWPX 표준과 LLM 에이전트 스킬 규격을 만나면서 어떻게 100% 제어 가능한 코드로 전환되었을까요?

✦ AI Key Summary & Global Takeaways

이 아티클의 핵심 내용 요약과 글로벌 검색·AI 엔진을 위한 테이크어웨이입니다.

✦ KR 주제: HWPX 개방형 규격 분석과 AGENTS.md를 활용한 AI 문서 생성 자동화

✦ KR 핵심 요약: HWPX는 KS X 6101 OWPML 표준을 채택한 XML 기반 문서로, 한글 오피스 설치 없이도 프로그래밍 방식으로 100% 정밀 복원이 가능합니다. LLM을 연동할 때 단발성 프롬프트 대신 AGENTS.md 규격으로 조판 로직과 수식 변환 규칙을 스킬화하면, 교육 현장의 수학·영어 문제지 제작 및 공공 서식 생성 작업을 결정론적 수준으로 자동화할 수 있습니다.

🌐 Global Takeaway: HWPX operates on the open KS X 6101 OWPML standard, enabling 100% deterministic document reconstruction via raw XML manipulation without relying on native HWP runtimes. Structuring LLM operations through modular AGENTS.md skill definitions decouples domain logic from volatile model prompts, allowing scalable and verifiable document automation across education and public sectors.

아래 그림은 폐쇄형 바이너리 HWP와 개방형 XML 표준 HWPX 간의 아키텍처 차이 및 에이전트 변환 파이프라인을 보여줍니다.

HWPX 패키지 계층 구조
ZIP 압축 컨테이너표준 압축 패키징 및 확장자 캡슐화
META-INF / container.xml패키지 내 파일 경로 및 OCF 매니페스트 정의
Contents / content.hpf스파인, 메타데이터, 매니페스트 리소스 목록 관리
Contents / section0.xml실제 본문 문단, 표, 컨트롤, 수식 데이터 저장 (KS X 6101)
BinData & Settings포함된 이미지 바이너리 및 문서 환경 설정 XML
HWPX 파일은 표준 ZIP 컨테이너 내부에 매니페스트와 XML 메타데이터가 계층별로 분리된 구조입니다.
AGENTS.md 기반 문제지 자동 생성 파이프라인
요구사항 접수과목 및 문제 유형 지정
→
AGENTS.md 호출문서 생성 스킬 컨텍스트 로딩
→
수식·서식 매핑수식 스크립트 및 표 규격 생성
→
XML 유효성 검증OWPML 스키마 준수 확인
→
HWPX 패키징ZIP 무손실 압축 및 배포
자연어 요구사항을 AGENTS.md 규칙을 거쳐 유효한 OWPML XML 트리로 변환하고 HWPX로 패키징합니다.

🚨 1. 개방형 HWPX 규격이 촉발한 한글 문서 자동화의 전환점

대한민국의 공공기관, 교육계, 연구기관에서 수십 년간 표준으로 군림해 온 HWP 포맷은 특유의 폐쇄적인 바이너리(Compound File Binary Format) 구조로 인해 엔지니어들에게 악명 높은 자동화의 장벽이었습니다. 윈도우 환경에서 한컴오피스 클라이언트를 백그라운드 프로세스로 띄운 뒤 OLE 오토메이션(Automation) API나 Win32COM 인터페이스를 후킹해야만 문서 서식을 간신히 조작할 수 있었습니다. 이는 동시 접속 처리가 필수적인 웹 서버나 리눅스 컨테이너 환경에서는 사실상 구축이 불가능한 구조적 한계를 낳았습니다. 그러나 한글과컴퓨터가 국가표준(KS X 6101)에 기반한 개방형 워드프로세서 마크업 언어(OWPML) 규격인 HWPX를 본격 도입하면서 문서 엔지니어링의 패러다임은 근본적으로 뒤바뀌었습니다.

HWPX는 단순한 확장자의 변경이 아닙니다. 마이크로소프트의 DOCX가 OOXML 표준으로 전환되었듯, HWPX는 문서 내부의 모든 문단, 글자 속성, 표 레이아웃, 벡터 그래픽, 수학 수식을 투명한 XML 트리 구조로 노출합니다. 즉, 비싼 오피스 라이선스나 윈도우 전용 런타임에 의존하지 않고도, 표준 파일 I/O 라이브러리와 XML 파서만으로 문서를 바이트 단위에서 재구성할 수 있게 된 것입니다. 이는 복잡한 시험 문제지나 정밀한 공공 서식을 다루는 개발자들에게 전례 없는 자유도를 부여했습니다.

한글 문서 처리 방식 포지셔닝
자동화 유연성
HWPX + AI 에이전트 스킬
  • 100% 서식 재현
  • OS 종속성 완전 제거
  • CLI 및 서버리스 처리
한컴 OLE 오토메이션 (HWP)
  • Windows 종속
  • 한글 프로세스 강제 구동
  • 동시성 제어 불가
단순 텍스트/마크다운 변환
  • 낮은 레이아웃 복원력
  • 수학 수식 깨짐
  • 공공 서식 미달
순수 파이썬 바이너리 파서
  • 역공학 한계
  • 신규 서식 파손 위험
  • 유지보수 고비용
문서 제어 정밀도
바이너리 접근법과 XML 기반 개방형 접근법의 자동화 난이도 및 제어 가능성 비교

1-1. 바이너리 HWP와 XML 기반 HWPX의 기술적 대비

두 포맷의 차이는 단순한 호환성 문제를 넘어 아키텍처 레벨에서의 결정론적 조작 가능 여부를 가릅니다. 기존 바이너리 HWP 파일의 경우, 구조를 분석하기 위해 비공개 레코드 구조체를 바이트 단위로 언패킹해야 했으며 버전 차이에 따라 예기치 않은 데이터 깨짐 현상이 빈번했습니다. 반면 HWPX는 표준 압축 아카이브 기술을 사용하여 모든 메타데이터와 본문을 분리합니다.

비교 항목 기존 바이너리 HWP 개방형 HWPX (KS X 6101)
기저 포맷 Compound File Binary Format (CFBF) Open Packaging Conventions (ZIP 기반 XML 패키지)
본문 표현 방식 태그 레코드 스트림 바이너리 OWPML (XML 마크업 기반 계층 트리)
실행 의존성 Windows 환경 및 한컴 ActiveX/COM 종속 OS 무관 (Linux, macOS, 웹 브라우저, 서버리스)
자동화 파이프라인 백그라운드 오피스 프로세스 구동 필수 경량 스크립트(Python, Rust, Node.js) 단독 처리
수식 표현 한글 고유 수식 스크립트 바이너리 임베딩 XML 엘리먼트 내 텍스트 기반 수식 스크립트 보존

이러한 구조적 개방성은 최근 급격히 발전한 대형 언어 모델(LLM) 및 AI 에이전트와 결합할 때 진정한 위력을 발휘합니다. LLM은 바이너리 스트림을 다룰 수 없지만, 명확한 스키마가 존재하는 XML 구조체와 텍스트 기반 수식 코드는 고도의 정확도로 이해하고 생성할 수 있기 때문입니다.


🧩 2. HWPX 내부 아키텍처: 패키징과 OWPML 스키마 분해

HWPX 파일의 정체는 사실 표준 ZIP 알고리즘으로 압축된 디렉터리 아카이브입니다. 파일 확장자를 .zip으로 변경한 후 압축을 해제하면, 문서의 외형과 내용을 결정짓는 표준화된 파일 레이아웃이 모습을 드러냅니다. 이 내부 체계를 정확히 이해하는 것이야말로 원본 서식을 100% 무손실로 복원하는 엔지니어링의 시작점입니다.

문서 패키지의 최상위에는 OCF(Open Container Format) 표준을 따르는 매니페스트와 설정 디렉터리가 자리 잡고 있습니다. 문서를 렌더링하거나 프로그래밍 방식으로 조작할 때 가장 핵심이 되는 영역은 Contents 디렉터리 하위에 위치한 스파인(Spine) 및 섹션 파일들입니다.

2-1. 패키지 핵심 디렉터리 및 파일 명세

HWPX 컨테이너 내부의 구조는 표준 규격에 따라 철저하게 역할이 분리되어 있습니다.

  • META-INF/container.xml: 패키지의 진입점(Entry point)을 정의하며, 본문 루트 파일인 content.hpf의 상대 경로를 브라우저나 파서에 전달합니다.
  • Contents/content.hpf: 패키지 내부에 포함된 모든 자원(폰트, 이미지, XML 섹션)의 MIME 타입과 스파인(문서 읽기 순서)을 기술하는 매니페스트 XML입니다.
  • Contents/header.xml: 문서 전반에서 재사용되는 스타일, 글자 모양(charPr), 문단 모양(paraPr), 글꼴 목록(fontFace), 번호 매김 및 글머리표 정의를 중앙에서 관리합니다.
  • Contents/section0.xml: 실제 텍스트, 표(hp:tbl), 그림(hp:pic), 수식(hp:equation) 등이 문단 단위(hp:p)로 배치되는 본문 코어 XML입니다.
  • BinData/: 문서 본문에 삽입된 래스터 이미지(PNG, JPEG), OLE 개체 등 바이너리 미디어가 원본 그대로 저장되는 저장소입니다.

이러한 패키징 덕분에 개발자는 전체 문서를 다시 쓸 필요 없이, 특정 문단의 텍스트나 수식 블록만을 DOM 파서로 탐색하여 갈아 끼운 뒤 다시 압축하는 초경량 업데이트 작업을 손쉽게 수행할 수 있습니다.


🤖 3. AI 에이전트와 AGENTS.md: 문서 생성을 '스킬'로 규격화하는 원리

문서 자동화 프로젝트에서 많은 개발자들이 범하는 치명적인 실수는 LLM에게 단일 프롬프트로 "한글 시험지 서식에 맞춰 HWPX XML을 작성해 줘"라고 요구하는 것입니다. LLM은 수천 줄에 달하는 OWPML 스키마의 태그 닫힘 상태, 네임스페이스(xmlns:hp, xmlns:hs), 고유 식별자(id, z-order)를 완벽하게 유지하지 못하고 환각(Hallucination)을 일으킵니다. 결과적으로 생성된 XML 파싱이 실패하거나, 한컴오피스에서 열었을 때 문서가 손상되었다는 치명적인 에러 메시지를 마주하게 됩니다.

이 문제를 돌파하기 위한 아키텍처가 바로 작업을 AGENTS.md 규격으로 구조화하고 개별 기능을 스킬(Skill) 단위로 격리하는 전략입니다.

"한글 문서는 HWPX 확장자라면 그 무엇이든 똑같이 100% 복원하여 만들 수 있습니다. 하지만 만든 뒤에는 작업을 AGENTS.md, 스킬화하고 이를 관리하는 것이 다음 작업을 빨리하기 위한 핵심입니다." — 오픈소스 커뮤니티 및 자동화 에디터 경험담 중

AGENTS.md 스킬 수명 주기
템플릿 정의서식·수식 스키마 확정
스킬 격리AGENTS.md 명세 작성
모델 실행LLM 통한 XML 변환
스키마 검증파서 기반 오류 검출
스킬 튜닝예외 사례 피드백 반영
↻반복
프롬프트 템플릿의 불안정성을 탈피하여 모델 독립적인 스킬로 유지보수하는 반복 순환 구조

AGENTS.md 파일은 AI 코딩 에이전트(예: Claude Code, Cursor, AutoGen 등)가 프로젝트 컨텍스트를 로드할 때 가장 먼저 참조하는 시스템 명세서 역할을 수행합니다. 문서 생성에 필요한 규칙을 모듈화된 서브 스킬로 정의함으로써, 모델의 추론 부하를 분산시키고 결정론적 출력을 강제할 수 있습니다.

3-1. AGENTS.md에 정의되는 핵심 스킬셋 계층

  1. 서식 스캐폴딩 스킬 (scaffold_hwpx): 사전에 검증된 빈 문서 패키지 템플릿(header.xml, content.hpf 포함)을 복제하여 작업 공간을 구성하는 파일 시스템 I/O 도구입니다.
  2. 문단 및 런 빌더 스킬 (build_paragraph): 자연어 텍스트와 스타일 ID를 입력받아 문법적으로 완전한 <hp:p>와 <hp:run> XML 노드를 생성하는 스킬입니다.
  3. 표 격자 계산 스킬 (generate_table_grid): 다단 문제지나 문제 번호 표를 작성할 때 셀의 너비, 높이, 테두리 속성(hp:tc, hp:cellAddr)을 수학적으로 계산하여 오류 없는 표 트리를 엮어냅니다.
  4. 수식 변환 스킬 (latex_to_hwp_eq): 모델이 생성한 LaTeX 수식을 한글 네이티브 수식 스크립트 문자열로 변환하고 이를 <hp:equation> 엘리먼트로 감싸는 전용 트랜스파일러입니다.

이처럼 모델에게 XML 전체를 맡기지 않고, '데이터 추상화'와 '스키마 조립'을 분리하여 스킬화할 때 프로덕션 레벨의 100% 무결성 문서 복원이 가능해집니다.


📐 4. 수학 수식과 영어 지문: 복잡한 레이아웃의 무손실 복원 기법

교육 현장에서 교사와 강사들이 가장 많은 시간을 소모하는 작업은 기출문제나 모의고사 문항을 재편집하여 2단(단축) 문제지로 조판하는 일입니다. 특히 수학 영역의 분수, 적분 기호, 행렬 수식과 영어 영역의 좌우 2단 지문 배치는 일반적인 마크다운이나 워드 프로세서 변환기로는 원본 스타일을 유지하기가 극히 까다롭습니다.

HWPX에서 수학 수식은 MathML이 아닌 한글 고유의 스크립트 문법(HWP Equation Script)을 XML 엘리먼트 내에 텍스트 노드로 품고 있습니다. 따라서 LLM 기반 에이전트 파이프라인에서는 글로벌 표준인 LaTeX 수식을 한글 수식 스크립트로 오차 없이 치환하는 매핑 레이어가 필수적입니다.

4-1. 수식 문법 매핑과 다단 레이아웃 제어

예를 들어 LaTeX의 \frac{a}{b}는 한글 수식에서 {a} over {b}로 치환되어야 하며, \sqrt{x}는 sqrt {x}로 변환되어야 합니다. 또한 거듭제곱, 밑첨자, 대형 연산자(\sum, \int)의 공백 및 괄호 크기 자동 조절(\left( ... \right) -> left ( ... right )) 규칙을 엄격하게 적용해야 합니다.

<!-- HWPX section0.xml 내부의 실제 수식 엘리먼트 구조 예시 -->
<hp:run>
  <hp:ctrl>
    <hp:colPr colCount="2" sameSz="1" gap="850"/>
  </hp:ctrl>
</hp:run>
<hp:p id="12" paraPrIDRef="3">
  <hp:run charPrIDRef="1">
    <hp:t>1. 다음 극한값을 구하시오.</hp:t>
  </hp:run>
  <hp:run charPrIDRef="2">
    <hp:equation version="Ext" text="lim_{x -> 0} {sin x} over {x} = 1" baseUnit="1000" textColor="000000"/>
  </hp:run>
</hp:p>

위 XML 코드에서 볼 수 있듯이, 단 설정은 <hp:colPr> 컨트롤을 통해 2단(colCount="2"), 단 간격 8.5mm(gap="850", 내부 단위는 HWPUNIT: 1pt = 100 HWPUNIT)로 정확히 제어됩니다. 수식은 <hp:equation> 태그 내의 text 속성에 순수 텍스트 스크립트로 주입됩니다. AI 에이전트는 이 템플릿의 규격을 스킬 라이브러리로 보유하고 있으므로, 입력받은 원문 텍스트가 아무리 길고 복잡하더라도 정해진 슬롯에 데이터를 정확히 안착시킬 수 있습니다.


⚙️ 5. 파이썬 기반 HWPX 파싱·조립 자동화 파이프라인

실제 프로덕션 환경에서 HWPX 문서를 파싱하고, AI가 작성한 본문 XML을 병합한 뒤 완전한 파일로 재패키징하는 파이썬(Python) 파이프라인의 핵심 구조를 살펴보겠습니다. 외부 무거운 오피스 라이브러리 없이 표준 모듈인 zipfile과 xml.etree.ElementTree(또는 lxml)만으로 빌드 시스템을 구축할 수 있습니다.

아래 코드는 HWPX 아카이브를 안전하게 해제하여 본문 XML을 조작하고, OCF 규격을 위반하지 않도록 무압축 mimetype과 함께 다시 ZIP으로 패키징하는 결정론적 빌드 스크립트의 뼈대입니다.

import zipfile
import os
import shutil
from xml.etree import ElementTree as ET

def extract_hwpx(hwpx_path: str, extract_dir: str):
    """HWPX 파일의 압축을 지정된 디렉터리에 해제합니다."""
    if os.path.exists(extract_dir):
        shutil.rmtree(extract_dir)
    with zipfile.ZipFile(hwpx_path, 'r') as zip_ref:
        zip_ref.extractall(extract_dir)

def inject_section_content(extract_dir: str, new_xml_content: str):
    """AI 에이전트가 생성한 본문 XML을 section0.xml에 교체 주입합니다."""
    section_path = os.path.join(extract_dir, 'Contents', 'section0.xml')
    with open(section_path, 'w', encoding='utf-8') as f:
        f.write(new_xml_content)

def pack_hwpx(source_dir: str, output_hwpx_path: str):
    """OWPML 표준에 맞게 디렉터리를 HWPX 파일로 재압축합니다."""
    with zipfile.ZipFile(output_hwpx_path, 'w', compression=zipfile.ZIP_DEFLATED) as zip_out:
        # mimetype 파일이 존재하는 경우 맨 처음에 압축 없이(ZIP_STORED) 기록하는 것이 표준 권장사항
        mimetype_path = os.path.join(source_dir, 'mimetype')
        if os.path.exists(mimetype_path):
            zip_out.write(mimetype_path, 'mimetype', compress_type=zipfile.ZIP_STORED)

        for root, dirs, files in os.walk(source_dir):
            for file in files:
                if file == 'mimetype':
                    continue
                full_path = os.path.join(root, file)
                rel_path = os.path.relpath(full_path, source_dir)
                zip_out.write(full_path, rel_path)

이러한 최소한의 무결성 빌드 체인을 갖춘 뒤, LLM 에이전트에게는 오직 new_xml_content의 내부 노드 규칙만을 책임지게 함으로써, 아카이브 손상이나 바이너리 헤더 파손 가능성을 원천적으로 차단합니다.


⚠️ 6. 한글 자동화 시스템 구축 시 마주치는 기술적 함정과 예외 처리

HWPX가 개방형 XML을 지향하지만, 여전히 레거시 한컴오피스 엔진의 렌더링 동작에 기인한 미묘한 트랩들이 도사리고 있습니다. 엔지니어가 사전에 대비하지 않으면 테스트 환경에서는 정상 작동하던 문서가 일선 학교나 관공서 PC에서 깨지는 상황이 발생합니다.

  1. HWPUNIT 단위 계산 오차: 한글 문서는 마이크로소프트 워드의 1/20 pt(dxa)나 CSS의 픽셀(px)이 아닌, 1인치를 7200으로 나눈 독자적인 HWPUNIT(1pt = 100 HWPUNIT) 단위를 폭넓게 사용합니다. 글자 크기, 여백, 셀 너비 태그에 이 배수를 잘못 적용하면 레이아웃이 화면 밖으로 밀려나는 사태가 발생합니다.
  2. ID 참조 무결성(Referential Integrity): section0.xml에 등장하는 각 문단은 paraPrIDRef, charPrIDRef 속성을 통해 header.xml에 선언된 스타일 ID를 외래키처럼 참조합니다. 만약 에이전트가 존재하지 않는 ID(예: charPrIDRef="99")를 부여하면 한컴오피스는 문서를 열람할 때 "스타일 정보가 누락되었습니다"라는 경고를 띄우거나 비정상 종료됩니다.
  3. 확장자 강제 변경의 한계: 구형 HWP 파일을 단순히 이름만 .hwpx로 바꾼다고 해서 XML 패키지가 되지 않습니다. 자동화 파이프라인 인입 단계에서 Magic Byte 검사를 수행하여 바이너리 HWP(D0 CF 11 E0)인지 표준 ZIP 헤더(50 4B 03 04)인지 반드시 판별해야 합니다.
  4. 특수 문자 엔티티 이스케이프: 수식 및 영어 지문에 자주 쓰이는 꺾쇠괄호(<, >)와 앰퍼샌드(&)가 XML 파서에 의해 깨지지 않도록 &lt;, &gt;, &amp;로 엄격히 직렬화(Serialization)해야 합니다.

🚀 7. 문서 엔지니어링의 미래: 프롬프트에서 결정론적 스킬 생태계로

문서 자동화의 무게중심은 단순한 '스크립팅'에서 '지능형 에이전트 아키텍처'로 옮겨가고 있습니다. HWPX라는 개방형 표준의 확립은 폐쇄적인 관공서 문서 포맷을 소프트웨어 공학의 메인스트림으로 끌어올렸습니다. 이제 한글 문서는 데스크톱 오피스 프로그램 안에서 마우스로 하나하나 다듬는 수작업의 대상이 아니라, CI/CD 파이프라인에서 단위 테스트를 거치고 깃(Git)으로 형상 관리되는 프로그래밍 자산입니다.

특히 수학, 과학, 외국어 등 복잡한 기호와 정밀한 조판이 필수적인 교육 영역에서, AGENTS.md 규격을 통한 작업의 스킬화는 교사와 실무자들을 기계적인 서식 다듬기 노동에서 해방시키고 있습니다. 원본 문서를 100% 무손실로 복원하는 기술은 마법 같은 단일 프롬프트가 아니라, 파일 포맷의 기저를 정확히 꿰뚫는 스키마 이해와 이를 제어하는 결정론적 스킬 모듈화에서 출발합니다.

자주 묻는 질문

Q. HWP 파일을 단순히 확장자만 .hwpx로 변경해도 자동화 툴에서 인식되나요?
A. 불가능합니다. HWP는 바이너리 스트림 구조이고 HWPX는 ZIP 기반 XML 패키징 형식이므로, 단순 파일명 변경 시 내부 매니페스트를 찾을 수 없어 파싱 에러가 발생합니다. 정식 변환기나 한컴오피스의 다른 이름으로 저장을 거쳐야 합니다.

Q. 수학 문제지의 수식을 HWPX 내부에 삽입할 때 LaTeX 문법을 그대로 써도 되나요?
A. 그대로 쓰면 깨집니다. HWPX 내부의 <hp:equation> 엘리먼트는 한글 고유의 수식 스크립트 문법(예: {a} over {b})을 요구하므로, 에이전트 스킬 파이프라인 단계에서 LaTeX를 한글 수식 문법으로 트랜스파일해야 합니다.

Q. AGENTS.md를 활용하면 프롬프트 엔지니어링 대비 어떤 장점이 있나요?
A. 문서 생성 작업에 필요한 XML 스키마, 수식 치환 규칙, 서식 제약조건을 독립된 모듈식 스킬로 관리함으로써, 모델의 환각을 방지하고 코드 레벨에서 유효성 검증이 가능한 결정론적 출력을 보장합니다.

원본

https://www.threads.com/@limedaddy_8924/post/DeR69U8lKbw

https://m.blog.naver.com/ggalabolab/224441276241

https://youtu.be/uiVQFkH_Awc

함께 보면 좋은 글

댓글 0개