HWPX 서식은 어디서 가져오는 거야? 강의계획서 템플릿 문제를 추적한 과정
2026.05.31
📒 소개
앞선 글에서는 제가 작게 만든 강의준비 파이프라인을 다시 살펴보며, 특정 강의에만 맞는 구조에서 벗어나 범용적으로 사용할 수 있는 파이프라인으로 바꾸고 싶었던 이유를 정리했습니다.
이번 글은 그다음 과정입니다.
처음 만든 파이프라인은 강의계획서와 교안 PPTX를 만드는 흐름으로 시작했습니다. 이후 hwpx.skill을 먼저 붙이면서, 기존에 만들지 못했던 HWPX 강의계획서까지 생성할 수 있도록 보강했습니다.
그런데 HWPX 파일은 생성되었지만, 막상 한글에서 열어보니 문제가 있었습니다.
내용은 들어가는데, 글꼴·정렬·레이블 스타일이 원하는 원본 양식처럼 유지되지 않았습니다.
처음에는 단순히 “템플릿을 다시 만들면 되겠지”라고 생각했습니다. 하지만 파이프라인을 범용적으로 쓰려면, 파일이 생성되는 것만으로는 부족했습니다.
그래서 먼저 이 질문을 던졌습니다.
“이 HWPX 서식은 도대체 어디서 가져오는 거야?”
이번 글은 HWPX 서식 오류를 계기로, 파이프라인이 어떤 파일을 기준으로 문서를 만들고 있는지 추적하고 수정한 과정입니다.
▶️ 진행 방법
어떤 도구를 사용했고, 어떻게 활용하셨나요?
이번 과정에서 사용한 도구는 다음과 같습니다.
도구 | 활용 방식 |
|---|---|
Claude Code Plan Mode | 바로 수정하지 않고 원인과 수정 계획을 먼저 확인 |
hwpx.skill | HWPX 내부 구조 확인 및 템플릿 생성 흐름에 활용 |
Python | 원본양식 기반 템플릿 생성 스크립트 작성 |
한컴오피스 한글 | 생성된 HWPX 파일을 직접 열어보며 확인 |
Git | 수정 전후를 커밋으로 남겨 복구 기준점 확보 |
이번에는 “파일이 생성되었는가?”보다 “생성된 파일이 실제 제출용 문서처럼 열리고 보이는가?”를 기준으로 확인했습니다.
사용한 프롬프트 1: 서식 문제 원인 확인
강의계획서.md를 hwp 파일로 만들 때 글꼴이나 정렬이 유지되지 않고 있어.
현재 생성되는 HWPX 파일의 서식이 왜 깨지는지 원인을 분석해줘.
바로 수정하지 말고, 먼저 어떤 파일을 기준으로 서식을 가져오고 있는지 확인해줘.
처음에는 막연하게 템플릿을 다시 만들면 될 것 같았습니다. 하지만 중요한 것은 “어떤 템플릿을 기준으로 만들고 있는지”를 확인하는 일이었습니다.
그래서 다시 이렇게 물었습니다.
현재 파이프라인에서 강의계획서.md 파일을 강의계획서.hwp 파일로 만들 때
내용의 서식을 어떤 파일을 참고로 해서 채워 넣는 거야?
이 질문이 결정적이었습니다.
확인 결과, 기존 파이프라인은 제가 원하는 원본양식이 아니라 서식참고본.hwpx를 기준으로 데이터를 채우고 있었습니다.
제가 실제로 원하는 기준 파일은 01_강의계획서_원본양식.hwpx였습니다.
원인: 참조 파일의 스타일 ID가 달랐다
HWPX 파일을 풀어서 XML을 비교해보니, 데이터가 들어가는 셀의 스타일 ID가 달랐습니다.
항목 | 기존 | 원하는 |
|---|---|---|
데이터 셀 스타일 ID |
|
|
결과 | 레이블 스타일과 섞여 서식이 어색함 | 본문 스타일 유지 |
겉으로는 숫자 하나 차이였지만, 이 값 때문에 글꼴과 정렬이 원하는 형태로 유지되지 않았습니다.
사용한 프롬프트 2: 원본양식 기반 템플릿 만들기
01_강의계획서_원본양식.hwpx를 기준으로 템플릿을 새로 만들어줘.
조건은 다음과 같아.
1. 원본양식의 표 구조와 스타일은 유지해줘.
2. 데이터가 들어갈 셀의 텍스트만 비워줘.
3. 본문 셀의 스타일은 원본양식 기준으로 유지해줘.
4. lesson-prep 파이프라인에서 기본 HWPX 템플릿으로 사용할 수 있게 해줘.
5. 전체 적용 전에 테스트 파일을 먼저 생성해줘.
이 요청을 바탕으로 make_template.py를 만들었습니다.
흐름은 단순했습니다.
원본 HWPX 양식 열기
↓
데이터 셀 텍스트만 제거
↓
표 구조와 스타일 유지
↓
강의계획서_템플릿.hwpx 생성
수정하면서 발견한 문제들
생성된 파일을 한글에서 직접 열어보니, 추가 문제가 계속 발견되었습니다.
문제 | 원인 | 해결 |
|---|---|---|
HWP에서 열리자마자 닫힘 | 빈 셀에 | 빈 셀 처리 시 |
“강사명”, “정원” 레이블이 안 보임 |
| 데이터 셀과 레이블 셀 좌표 분리 |
레이블이 굵게 보이지 않음 | 일부 레이블 스타일 ID가 기대와 다름 |
|
표 아래 여백이 많음 | 내용만큼만 표 높이가 잡힘 | 마지막 행 높이를 자동 확장 |
쪽나눔이 부자연스러움 | 표를 임의로 나누는 방식 |
|
이 과정에서 가장 도움이 된 것은 코드 로그가 아니라, 실제로 파일을 열어보고 “이상한 부분”을 하나씩 확인한 일이었습니다.
🎁 결과와 배운 점
결과
HWPX 생성 흐름을 다음처럼 수정했습니다.
항목 | 수정 전 | 수정 후 |
|---|---|---|
기준 서식 |
|
|
데이터 셀 스타일 | 레이블 스타일과 섞임 | 본문 스타일 유지 |
레이블 표시 | 일부 사라짐 또는 굵기 미적용 | 정상 표시되도록 보정 |
표 높이 | 아래 여백이 남음 | 1페이지에 자연스럽게 맞춤 |
쪽나눔 | 임의 분리 방식 | 셀 단위 자연 분할 방식 |
이제 HWPX 강의계획서가 단순히 생성되는 수준을 넘어, 실제 제출용 문서에 더 가까운 형태로 만들어지게 되었습니다.
✨ 배운 점과 나만의 꿀팁
이번 과정에서 가장 크게 배운 것은 이것입니다.
자동화 결과가 이상할 때는 “고쳐줘”보다 “어디서 가져오는 거야?”를 먼저 물어봐야 한다.
서식 문제는 단순히 예쁘게 보이느냐의 문제가 아니었습니다. 어떤 파일을 기준으로 삼고 있는지, 어떤 스타일 ID를 사용하고 있는지, 어떤 셀을 데이터 셀로 인식하는지가 모두 연결되어 있었습니다.
저에게 가장 도움이 되었던 질문은 이 세 가지였습니다.
이 서식은 어떤 파일에서 가져오는 거야?
이 값은 어느 XML에 들어 있어?
이 셀은 데이터 셀이야, 레이블 셀이야?
또 하나의 팁은 생성된 파일을 반드시 원래 프로그램에서 열어보는 것입니다.
HWPX는 생성 로그만 봐서는 문제를 알기 어려웠습니다. 한글에서 직접 열어봐야 줄 충돌, 레이블 누락, 표 높이, 쪽나눔 같은 문제가 보였습니다.
과정 중에 어떤 시행착오를 겪었나요?
처음에는 문제를 너무 단순하게 봤습니다.
서식이 깨진다
→ 템플릿을 새로 만들면 된다
하지만 실제 과정은 이랬습니다.
서식이 깨진다
→ 어떤 파일을 기준으로 쓰는지 확인한다
→ 참조 파일이 원하는 양식과 다르다
→ XML 스타일 ID를 비교한다
→ 원본양식 기반 템플릿을 만든다
→ 한글에서 직접 열어본다
→ linesegarray, 셀 좌표, 레이블 스타일, 표 높이, 쪽나눔을 차례로 수정한다
겉으로는 단순한 서식 문제였지만, 실제로는 HWPX 템플릿의 기준 파일을 다시 잡는 작업이었습니다.
도움이 필요한 부분이 있나요?
아직 더 고민하고 싶은 부분도 있습니다.
기관별 HWPX 양식이 달라질 때 템플릿을 어떻게 쉽게 추가할지
여러 HWPX 양식 중 적절한 양식을 자동 선택할 수 있을지
셀 좌표가 달라져도 안정적으로 데이터를 채울 수 있을지
HWPX 파일을 직접 열어보기 전에 구조 오류를 자동 감지할 수 있을지
앞으로의 계획이 있다면 들려주세요.
이번 글에서는 HWPX 서식 문제를 해결하는 과정을 정리했습니다.
다음 글에서는 전체 파이프라인을 실제로 검증한 과정을 정리하려고 합니다.
특히 다음 글의 핵심은 이것입니다.
파일이 생성되었다고 성공은 아니다. 조용히 누락되는 실패를 잡아야 한다.
단일 차시와 다차시 강의를 실제로 생성해보면서, 다차시 HWPX에서 일부 차시 내용이 조용히 빠지는 문제를 발견했고, 이를 막기 위해 코드 가드와 검증 기준을 추가했습니다.
도움 받은 글
이번 글은 앞서 작성한 글에서 이어지는 내용입니다.
작게 만든 강의준비 파이프라인, 이제 범용화가 필요했다
모각에서 공유받은 hwpx.skill 패키지를 내 파이프라인에 붙이기
작게 만든 강의준비 파이프라인, 이제 범용화가 필요했다
특히 hwpx.skill 덕분에 HWPX 내부 구조를 직접 확인하고, 제 파이프라인에 맞게 템플릿을 다듬을 수 있었습니다.
이번 과정에서 가장 크게 남은 문장은 이것입니다.
“어디서 가져오는 거야?”라는 질문 하나가 막연한 계획을 정확한 원인 분석으로 바꿨다.




"어디서 가져오는 거야?"라는 질문 하나로 서식 문제의 핵심을 찾아내신 과정이 중요했네요. 스타일 ID 하나 차이를 추적해서 원본양식 기반 템플릿으로 전환하신 흐름도 깔끔하구요. 파일을 직접 열어보며 linesegarray부터 쪽나눔까지 차례로 잡아내신 꼼꼼함이 느껴지네요. 휴일에 연구많이 하시는군요 ㅎ