sakyowon 위키

AI에게 스크립트 경로만 주고 한글 문서 만들기 — 원본 추적, python-hwpx, 서식 규칙 후처리

7 min read

요약

다른 자리에서 AI가 만들어 둔 “한글 문서 생성 스크립트”의 경로 한 줄만 붙여 주고 “이 내용을 한글파일로 만들어”라고 했을 때, AI가 ① 그 파일이 어느 저장소의 어느 가지(branch)에 있는지 찾아내고 ② 빌더를 설치해 실행하고 ③ 우리 조직의 서식 규칙(본문·표 12pt, 표는 쪽 넘김 가능, 셀은 왼쪽 정렬)을 뒤에서 덧입혀 ④ 실제 한글로 열어 10쪽을 눈으로 확인한 절차다. 결과물은 세무사 인터뷰 질문지 44문항(마을협동조합 세무자료 자동 이관·공동구매 설계용)이다.

왜 이 기술인가

  • AI 세션은 여러 곳(다른 PC, 웹, 다른 사람의 계정)에서 병행된다. 한 세션이 만든 파일을 다른 세션에 넘길 때 경로만 남고 파일은 없는 일이 흔하다. 특히 AI가 만든 작업 가지(claude/… 브랜치)는 main에 합쳐지지 않은 채 남기 쉽다.
  • 생성 스크립트는 “내용”의 원본이지만, 그 스크립트가 만든 문서의 서식은 그 세션의 기본값이다. 조직이 정한 규칙(글자 크기, 표 배치)은 스크립트를 고치지 않고도 산출물에 일괄 적용할 수 있어야 반복 작업이 줄어든다.
  • “XML이 유효하다”와 “한글에서 잘 보인다”는 다르다. 표가 쪽 경계에서 잘리는 문제는 열어 봐야만 보인다.

단계별 따라하기

1. 파일이 없으면 저장소의 모든 가지를 뒤진다

로컬 폴더·다운로드·다른 클론에 없으면 GitHub API로 조직 전체를 훑는다. gh CLI가 인증돼 있어야 한다.

for r in $(gh repo list <조직> --limit 50 --json nameWithOwner --jq '.[].nameWithOwner'); do
  for b in $(gh api "repos/$r/branches?per_page=50" --jq '.[].name'); do
    gh api "repos/$r/git/trees/$b?recursive=1" --jq '.tree[].path' | grep -i "<파일명 일부>" \
      && echo "== $r @ $b"
  done
done

이번에는 로컬에 없던 파일이 deka2026/solidarity-intelligence-wiki의 claude/tax-accountant-interview-questions-4xi2is 가지에만 있었다. 찾은 파일은 클론하지 않고 바로 받는다.

gh api -H "Accept: application/vnd.github.raw" "repos/<owner>/<repo>/contents/<경로>?ref=<브랜치>" > 파일

2. 빌더를 설치해 그대로 한 번 돌린다

스크립트 첫 줄의 from hwpx.document import HwpxDocument는 python-hwpx 패키지다.

pip install python-hwpx
python tax-accountant-interview-questions.build.py out.hwpx

먼저 원본 그대로 만들어 두면, 뒤에서 규칙을 적용한 판과 비교할 기준이 생긴다. 이번 원판은 본문 10.5pt·표 셀 10pt, 표는 “글자처럼 취급”이었다.

3. 조직 규칙을 산출물에 덧입힌다

hwpx는 ZIP 안의 XML이다. 세 가지를 고치면 된다.

규칙어디를 고치나무엇으로
본문·셀 12ptContents/header.xml의 <hh:charPr … height="1050">실제 쓰이는 id만 height="1200" 이상으로
긴 표가 쪽을 넘어 이어지게Contents/section0.xml의 <hp:pos treatAsChar="1" …>treatAsChar="0" (자리차지)
셀 글자 사이가 벌어지지 않게셀 문단의 paraPrIDRef양쪽 정렬 paraPr을 왼쫽 정렬 사본으로 복제해 셀 문단만 그쪽을 가리키게

이 셋을 한 번에 하는 후처리기가 hwpx-powershell-edit 스킬의 scripts/hwpx_house_rules.py다.

python hwpx_house_rules.py out.hwpx out_12pt.hwpx
# {'raised_charpr': {...}, 'tables_inflow': 13, 'cell_paras_left': 297, ...}

글자를 키우면 좁은 열의 제목(“번호”)이 두 줄로 접힌다. 이번에는 스크립트의 열 폭 비율(0.9 → 1.15)만 살짝 고쳐 다시 빌드했다.

4. 한글로 열어 쪽 단위로 본다

한글 COM으로 열어 쪽수를 세고 PDF로 뽑은 뒤, PyMuPDF로 쪽별 그림을 한 장(접촉 시트)에 모아 본다. 빈 쪽, 표가 쪽번호를 덮는 곳, 잘린 행이 한눈에 드러난다. 사용자의 한글이 이미 열려 있으면 절대 강제 종료하지 않는다 — 새로 뜬 프로세스만 다루는 스크립트를 쓴다.

powershell -NoProfile -ExecutionPolicy Bypass -File pagecount_auto.ps1 -HwpxPath "out_12pt.hwpx" -Pdf

이번 결과: A4 10쪽, 표 13개가 모두 쪽 경계에서 정상 분할.

교훈

  1. 경로는 힌트이고 파일은 증거다. 경로가 안 열리면 “없다”고 답하지 말고 저장소의 가지까지 훑는다. AI 세션이 만든 가지는 main에 없는 게 기본이다.
  2. 원판을 먼저 그대로 만든다. 규칙 적용판과 나란히 놓아야 무엇이 바뀌었는지 설명할 수 있다.
  3. 서식 규칙은 후처리로 분리한다. 스크립트 저자와 규칙 소유자가 다를 때, 스크립트를 고치는 대신 산출물에 규칙을 덧입히면 어느 빌더의 산출물에도 같은 도구가 통한다.
  4. 표는 “자리차지”여야 쪽을 넘는다. 글자처럼 취급된 표는 통째로 밀리고 넘치는 행이 잘린다. XML 검증은 이걸 잡지 못한다.
  5. 열어 본 것만 완료다. 쪽수·PDF·접촉 시트까지가 검수다.

참고

  • hwpx-powershell-edit 스킬(sakyowon-ai 레포 skills/): 경로 G “외부 빌더 산출물에 사내 규칙 적용”, scripts/hwpx_house_rules.py, scripts/pagecount_auto.ps1
  • 위키 레슨 AI와-함께-한글문서-빨간펜-교정하기 — 같은 hwpx 구조를 교정 용도로 다룬 글
  • 원본 문서: 세무사 인터뷰 질문지(마을협동조합 세무자료 자동 이관 체계와 서비스 공동구매), 사회혁신교육원 2026-09-11
  • 문서 정리 = 데카(deka2026)

그래프 뷰