공공기관 보고서 작성 + HWPX 변환 스킬 (v3.6.12)

이 스킬의 목표: AI가 없던 시절 한글(hwp)을 쓰던 베테랑 보고서 작성자가 만든 것처럼, 독자 입장에서 가독성이 높고 핵심이 빠르게 읽히는 공공기관 보고서를 자동 생성한다.

디렉토리 구조

public-doc-to-hwpx/
├── SKILL.md                          ← 이 파일 (4단계 워크플로우)
├── scripts/                          ★ v3.5.0 — 4대 함정 자동 검사 + 통합 빌드
│   ├── make_skeleton.py              양식 hwpx → 빈 골격 변환 (새 양식 등록 시)
│   ├── fill_skeleton.py              메인 빌더 — 빈 골격 토큰을 값으로 치환
│   ├── fix_namespaces.py             ⚠️ 필수 후처리 (빠뜨리면 한글에서 안 열림)
│   ├── simulate_pages.py             ★ v3.5.0 갱신 — --values + --apply-to-values
│   ├── ensure_body_anchor.py         본문 시작 pageBreak="1" 강제 (풀버전)
│   ├── wrap_long_titles.py           ★ v3.6.0/3.6.4 — 표지 큰 제목 자간 압축 자동 해소
│   ├── fix_toc_dots.py               ★ v3.6.1/3.6.2/3.6.5 — 목차 점선 width 42000 통일 + lineseg 캐시 제거
│   ├── fix_gongmun_body.py           ★ v3.6.3 — 공문 본문 단락 자간 압축 자동 해소
│   ├── split_gongmun_paragraphs.py   ★ v3.6.4/3.6.6 — placeholder 강제 분리 (현재 비활성)
│   ├── fix_skeleton_defects.py       ★ v3.6.6/3.6.10 — Skeleton 양식 결함 자동 보정 (Ⅳ장 들여쓰기 + 수신자 라벨/입력 분리)
│   ├── expand_gongmun_body.py        ★ v3.6.7/3.6.8/3.6.9/3.6.10 — 공문 본문 모든 위계 동적 확장 + 빈 단락 제거 + 들여쓰기 통일
│   ├── normalize_1p_markers.py       ★ v3.6.11 신규 — 1p 보고서 마커 자동 정규화 (◦ 자동 추가 + BULLET 중복 제거)
│   ├── build_full.py                 ★ v3.5.0 — 풀버전 통합 빌드 워크플로우
│   └── validate.py                   구조 검증
├── templates/
│   ├── _skeleton.hwpx                폴백 베이스
│   ├── charpr_mapping.json           양식별 charPr 역할 → id 매핑표
│   ├── government/header.xml         관공서 charPr/paraPr/borderFill 정의
│   ├── format_1p/
│   │   ├── standard.hwpx             1p 보고서 표준 양식 (맑은 고딕)
│   │   ├── skeleton.hwpx             ★ 빈 골격 (35개 토큰)
│   │   ├── skeleton_mapping.json     ★ 토큰 ↔ 원본 매핑표
│   │   └── outline_guide.md          ★ v3.3.1 보고 목적별 11가지 표준 목차 가이드
│   ├── format_full/
│   │   ├── standard.hwpx             풀버전 보고서 표준 양식 (맑은 고딕, 표 10개)
│   │   ├── skeleton.hwpx             ★ 빈 골격 (127개 토큰 — 페이지번호 포함)
│   │   └── skeleton_mapping.json     ★ 토큰 ↔ 원본 매핑표
│   ├── format_gongmun/
│   │   ├── standard.hwpx             시행문 표준 양식 (굴림체, 표 셀 66개)
│   │   ├── skeleton.hwpx             ★ 빈 골격 (27개 토큰 — fwSpace 포함)
│   │   └── skeleton_mapping.json     ★ 토큰 ↔ 원본 매핑표
│   └── format_email/                 이메일 (텍스트 출력이라 골격 불필요)
└── references/
    ├── writing-principles.md         ★ 보고서 작성 원칙 (강의자료 + 사례 통합)
    ├── layout-rules.md               ★ 레이아웃 최적화 규칙
    ├── format-selection.md           양식 선택 결정트리
    ├── format-1p.md                  1p 보고서 가이드
    ├── format-full.md                풀버전 보고서 가이드
    ├── format-gongmun.md             시행문 가이드
    └── format-email.md               이메일 가이드

examples/                             ★ v3.6.10 — values.json 예시
├── example_values_gongmun.json       시행문 예시 (모든 위계 활용)
├── example_values_full.json          풀버전 보고서 예시 (127슬롯)
└── example_values_1p.json            ★ v3.6.11 신규 — 1p 보고서 예시 (마커 정규화 검증)

CHANGES.md                            ★ v3.6.11 — 사용자용 변경 이력 (파일명 안정화)
RELEASE_CHECKLIST.md                  ★ v3.6.11 신규 — 버전 업데이트 체크리스트

v3.4.0 변경: v3.3.x 까지의 "모드 1 (자동 빌드, compose_doc.py)" 는 양식 시각 디자인을 보존하지 못해 deprecated 되었고, v3.4.0 부터는 빈 골격 채우기 단일 워크플로우 만 지원합니다. 관련 스크립트(compose_doc.py, layout_optimizer.py, format_builders.py, content_mapper.py, build_hwpx.py, hwpx_helpers.py) 는 모두 제거되었습니다.

★ 4단계 워크플로우 (반드시 이 순서로 진행)

① 콘텐츠 기초데이터 정리

사용자 요청을 AI가 이해하기 쉬운 구조로 정돈한다.

• Claude가 사용자 메시지 또는 입력 파일(.md/.docx/.pdf/.txt)에서 핵심 정보(제목 후보·배경·현황·해결안·일정·예산 등) 를 직접 추출
• 마크다운 헤딩(#, ##)을 섹션 구조로 변환
• 필요 시 kordoc MCP 도구로 입력 파일 파싱 가능

② 작성목적 및 서식 결정

Claude는 반드시 이 순서로 양식을 결정한다.

2-1. 사용자에게 참조 HWPX 파일이 있는지 먼저 묻는다

사용자에게 줄 메시지 (예시):
"보고서 양식을 결정하기 전에 한 가지 확인할게요.
이번에 따로 참고하실 .hwpx 파일이 있으신가요?

(없으셔도 됩니다. 1p 보고서·풀버전 보고서·시행문 모두 회사 표준
서식이 내장되어 있어 폰트·서식이 그대로 적용됩니다.)"

⚠️ HWTX 형식은 묻지 않는다. 내부적으로 어차피 HWPX 로 변환되므로, 사용자가 HWTX 를 가지고 있더라도 HWPX 로 저장해서 줄 것을 안내한다.

참조 파일이 있다고 답하면 → 사용자 파일 경로 수령 후 추가 질문 한 번 더:

사용자에게 줄 추가 질문 (예시):
"이 참조 파일을 어떻게 활용할까요?
  ① 서식만 적용 (폰트·문단·테두리 등) - 기본 권장
  ② 서식 + 내용·섹션 구성도 반영 (참조파일의 챕터/소제목 구조를 따라 콘텐츠를 재정렬)"

• ① 서식만 → 사용자 hwpx 를 make_skeleton.py 로 빈 골격(skeleton.hwpx) 으로 변환한 후, 그 골격에 콘텐츠를 매핑·빌드. 양식의 폰트·charPr·표·테두리·페이지헤더가 모두 보존됨.
• ② 서식+내용 → 위와 동일하게 빈 골격을 만들되, 참조파일의 섹션 헤딩·소제목·문구 패턴을 학습하여 사용자 콘텐츠를 그 구조에 맞춰 재정렬한 후 매핑. (예: 참조가 "추진배경 → 현황 → 개선안 → 일정" 구조라면 사용자 콘텐츠도 그 4단으로 매핑)

참조 파일이 없다고 답하면 → 별도 인자 없이 진행. 양식이 결정되는 즉시 해당 templates/<format>/standard.hwpx 가 자동으로 빌드 베이스가 된다.

💡 내장 표준 서식의 효과: 한 번 양식이 결정되면 그 양식의 폰트(맑은 고딕/굴림체 등), 글자속성 21~74개, 문단속성, 테두리채움 정의가 모두 보존된다. 즉 결과 hwpx 를 한글에서 열면 사용자가 정리해 둔 회사 표준 서식이 그대로 보인다.

2-2. 4개 양식 중 자동 추천 + 최종 확인

Claude 가 콘텐츠 분량·청자·목적을 분석해 양식을 자동 추천한다.

자세한 결정 트리는 references/format-selection.md 참조.

추천 결과를 사용자에게 1줄로 알리고 확인받는다:

"콘텐츠를 보니 1페이지 보고서가 적합해 보입니다.
이대로 진행할까요? (다른 양식: 풀버전 / 시행문 / 이메일)"

③ 지정 용도의 서식에 맞춰 콘텐츠 텍스트 수정

Claude 가 양식의 skeleton_mapping.json 을 참조하여 사용자 콘텐츠를 양식 슬롯에 매핑한다.

• 1p 보고서 → 부제·제목·작성자·요약문·□ 섹션(4개) 슬롯에 매핑
• 풀버전 → 표지·목차·요약페이지·본문 chapters(127 슬롯) 에 매핑
• 시행문 → 수신·제목·본문(서술식+개조식)·붙임·발신명의 슬롯(27개) 에 매핑
  • 본문-메타 분리 원칙: 수신자·발신자·결재선·시행번호·날짜·전화 같은 메타 정보는 빈 값으로 두고 한글에서 직접 채울 자리로 남김
• 이메일 → 제목·받는사람·결론·□ 섹션·서명 (텍스트 출력)

필수항목 누락 시 Claude 가 사용자에게 알리고 추가 정보를 요청한다.

마커 일관성 원칙: 양식 원본 텍스트(skeleton_mapping.json 의 original_text) 의 마커 패턴(◦, -, * 등) 을 그대로 따라 값을 채운다. 원본에 ◦ 가 있으면 우리 값에도 ◦ 를 직접 적고, 원본에 마커가 없으면 (paraPr 자동 들여쓰기) 마커 없이 텍스트만 넣는다.

④ 레이아웃 최적화 편집 (★ 가장 차별화된 부분)

Claude 가 슬롯에 값을 매핑하기 전에 다음을 직접 적용한다 (참고: references/layout-rules.md).

4-1. 자동 적용 (신뢰도 높음)

• ~와 관련된 → ~ 관련
• ~할 예정이었으나 이를 유예하였습니다 → ~ 예정 → 유예 (명사형 종결 — 1p·풀버전만, 아래 장르 가드 참조)
• 여러/많은/각/모든/수많은/대부분의/다양한 ~들 → 동일 단어에서 들 제거

4-2. 검토 권장 표시 (사용자 확인용)

• ~할 것으로 보입니다 → ~ 예상 / ~ 전망 (명사형 종결 — 1p·풀버전만)
• ~한 것으로 판단됩니다 → ~ 판단 / ~로 보임 (명사형 종결 — 1p·풀버전만)
• ~하는 것이 필요합니다 → ~가 필요합니다
• ~에 대한, ~ 중 하나인, ~의 ~의 ~ (의 연쇄)
• 사회적/경제적/정치적/행정적/조직적/기술적/사업적/업무적/제도적 + 명사
• 한 문장 46자 초과 (분리 후보)

⚠️ 장르 가드: 서술어 종결을 명사형(개조식)으로 바꾸는 변환 (~보입니다→예상, ~판단됩니다→판단, ~예정이었으나 유예→예정→유예)은 1페이지 보고서·풀버전 보고서에서만 발동한다. 시행문·이메일에는 미발동 — 서술어 완결 + 공손체(~하시기 바랍니다)가 규범이므로 명사형 종결로 바꾸면 격식 위반. 시행문·이메일에서 문장이 길면 명사형 압축 대신 문장 분리로 처리한다. (상세: references/layout-rules.md §8-1)

4-3. 페이지 걸침 점검

• 양식별 페이지당 라인 수 추정 (format_1p ≈ 37줄 / 여백 상25·하20, format_full ≈ 38–42줄 / 여백 상30·하25)
• 1p 보고서가 1쪽 초과하면 빌드 거부 + 압축 또는 양식 변경 권고
• 시행문이 1쪽 초과하면 별첨 분리 권고

4-4. 글머리 위계 일관성

• 양식별 권장 체계 (1p·이메일=A 체계 □○-*, 풀버전·시행문=B 체계 1.가.(1))
• 두 체계 혼용 시 경고

전체 작성 원칙은 references/writing-principles.md, 자동 적용 규칙은 references/layout-rules.md 에 정리되어 있다.

표준 빌드 워크플로우 (v3.4.0)

v3.4.0 부터는 빈 골격 채우기 단일 워크플로우 만 지원한다. v3.3.x 까지 존재하던 자동 빌드 모드(compose_doc.py) 는 양식 시각 디자인을 보존하지 못해 deprecated 되었다.

작동 원리

양식 hwpx 를 사전에 빈 골격(skeleton.hwpx) 으로 변환해 두고, 빌드 시 토큰 자리에 콘텐츠를 채워 넣는다.

• ✅ 양식의 표·테두리·음영·페이지헤더 등 모든 시각 구조 100% 보존
• ✅ 한글에서 열었을 때 양식 파일과 시각적으로 거의 동일한 결과
• ✅ 콘텐츠와 양식 디자인이 완전히 분리되어 양식만 교체하는 작업도 단순

표준 명령 시퀀스

풀버전 보고서 (권장: v3.5.0 통합 빌더)

cd <skill_dir>

# 한 줄로 4대 함정 검사 + 페이지번호 자동 매핑 + 후처리까지 완료
python3 scripts/build_full.py \
  --values my_values.json \
  --output result.hwpx
# 옵션: --strict (위반 발견 시 빌드 중단)

build_full.py 가 자동 수행하는 작업:

1. 입력 검사 — 목차 슬롯 위계, 빈 슬롯 비율, 본문 마커 중복 점검
2. 1차 빌드 (페이지번호 임시값)
3. 페이지 시뮬레이션 + values 자동 갱신
4. 2차 빌드 (페이지번호 반영된 최종본)
5. 후처리 (fix_namespaces + ensure_body_anchor + wrap_long_titles + fix_toc_dots + validate)
   • v3.6.0 wrap_long_titles: 표지 큰 제목이 14자 초과 시 자동으로 2단락 분리
   • v3.6.1/3.6.2/3.6.5 fix_toc_dots: 목차 점선(<hp:tab leader="3"/>) width 를 42000 으로 통일 + 점선이 든 단락의 <hp:linesegarray> 캐시 제거하여 한글2018 이 폰트 메트릭으로 재계산하도록 위임
   • 한글2018·한컴뷰어 양 환경에서 표지 제목·목차 점선이 동일하게 렌더링됨

1p 보고서·시행문 (기존 방식)

# 단계 ① 매핑 JSON 확인 → 슬롯이 몇 개 있고 어떤 의미인지 파악
cat templates/format_1p/skeleton_mapping.json

# 단계 ② 콘텐츠를 양식 슬롯에 맞게 매핑한 values.json 작성

# 단계 ③ 빈 골격에 값 채우기
python3 scripts/fill_skeleton.py \
  --skeleton templates/format_1p/skeleton.hwpx \
  --values my_values.json \
  --output result.hwpx

# 단계 ④ 후처리 + 검증
python3 scripts/fix_namespaces.py result.hwpx
python3 scripts/fix_gongmun_body.py result.hwpx   # ★ v3.6.3 (시행문만 — 본문 자간 압축 해소)
python3 scripts/validate.py result.hwpx

💡 v3.6.3 권장: 시행문(공문) 빌드 시 fix_gongmun_body.py 후처리를 항상 실행합니다. 공문 양식 본문 단락은 단일 lineseg(horzsize=49108) 로 저장되어 한글2018 의 자간 압축 동작을 유발하므로, 이 후처리가 단일 lineseg 단락의 linesegarray 를 제거하여 한글이 폰트 메트릭으로 자동 재계산하도록 위임합니다.

1p 보고서는 본문 셀 구조가 다르므로 영향 없음 (호출해도 매칭 0건으로 무영향).

풀버전 보고서 (구식 — 수동 분리 모드, 권장하지 않음)

python3 scripts/fill_skeleton.py --skeleton templates/format_full/skeleton.hwpx --values my_values.json --output result.hwpx
python3 scripts/fix_namespaces.py result.hwpx
python3 scripts/simulate_pages.py result.hwpx --mapping templates/format_full/skeleton_mapping.json --values my_values.json --apply-to-values
python3 scripts/fill_skeleton.py --skeleton templates/format_full/skeleton.hwpx --values my_values.json --output result.hwpx
python3 scripts/fix_namespaces.py result.hwpx
python3 scripts/ensure_body_anchor.py result.hwpx
python3 scripts/validate.py result.hwpx

values.json 예시 (풀버전 보고서)

{
  "표지_제목": "전사적 AI역량 강화 추진계획",
  "표지_부제": "- AX 시대 인적자원 혁신을 위한 -",
  "보고일": "2026. 5. 11.",
  "기관명": "○○공사",
  "본부부서명": "AI혁신처",
  "장01_제목": " 추진배경 및 필요성",
  "본문_절_001": " □ AX 시대 도래로 전사적 AI 리터러시 확보 필수",
  "본문_항목_001": " 글로벌 기업 89% 이상이 AI 도입을 이미 진행 중",
  "본문_세부_001": "   - 4조 4천억 달러 규모 생산성 향상 잠재력 보유",
  "본문_주석_001": "       ※ 단, 성숙 단계 기업은 1~6%에 불과"
}

새 양식을 빈 골격으로 만들 때

# 사용자가 templates/format_<name>/standard.hwpx 를 두면
python3 scripts/make_skeleton.py templates/format_<name>/standard.hwpx
# → templates/format_<name>/skeleton.hwpx + skeleton_mapping.json 자동 생성

양식별 빠른 가이드

자세한 내용은 각 references 파일 참조. 여기서는 핵심만.

format_1p (1페이지 보고서)

• 구성: 부제 → 제목 → 음영 박스(요약) → □ 대제목(3–4개) → ○ 본문 → - 세부
• 분량: 1쪽 강제 (37줄 이내 — 1p 여백 상25·하20 기준 실효 상한)
• 우수예시: ○○기관 협력사업 실무협의 보고, 신규 사업 제휴 검토결과 보고
• 가이드: references/format-1p.md (양식 일반 가이드)
• 목차 구성 가이드: templates/format_1p/outline_guide.md (v3.3.1 신규)
  • 보고 목적별 11가지 유형의 표준 목차 (현황·동향 / 검토·의사결정 / 계획 / 문제해결 / 이슈·리스크 / 결과·성과 / 회의 안건 / 회의 결과 / 행사 / 제휴·협력 / 예산·구매)
  • 4절 기본형 / 5절 확장형 / 3절 압축형 골격
  • 양식의 4섹션 슬롯(text_004~023) 과 목차 절의 대응표
  • 1페이지 보고서 빌드 시 목차를 먼저 이 가이드에서 선택한 후 슬롯에 매핑하는 것이 표준 워크플로우

format_full (풀버전 보고서)

• 구성: 표지 → 목차 → 보고내용 요약(1쪽) → 본문(Ⅰ.1.가.(1)(가)) → 별첨
• 분량: 5–30쪽
• 우수예시: 스마트 편의점 개발 추진계획(2020.7., 25p)
• 가이드: references/format-full.md

format_gongmun (시행문)

• 구성: 발신기관 → 수신·경유·제목 → 본문(서술식+개조식) → 붙임 → 발신명의 → 메타데이터
• 분량: 1–3쪽 (1쪽이 표준)
• 글머리: 반드시 1. → 가. → 1) → 가) → (1) → (가) → ① → ㉮
• 결문: ~하기 바랍니다, ~하여 주시기 바랍니다
• 가이드: references/format-gongmun.md

format_email (이메일 — 텍스트 출력)

• 구성: 제목 → 받는사람·참조 → 인사 → 결론(두괄식) → □ 섹션 → 마무리 → 서명
• 분량: 본문 200–500자
• 출력: .md 또는 .txt (HWPX 빌드 안 함, 메일 본문 복붙용)
• 가이드: references/format-email.md

작성 원칙 (writing-principles.md 요약)

자세한 내용은 references/writing-principles.md 를 읽을 것.

핵심 5원칙:

1. 두괄식 — 결론·요약을 첫 3줄 안에. 1p 보고서는 음영 박스로 압축.
2. 개조식 — 키워드 중심, 글머리·번호로 짧게 끊기. 서술식은 시행문 본문 도입부에서만.
3. 한 문장 한 핵심 — 한 문장에 두 개 정보 = 분리. 문장 길이는 3구간(≤35 안전 / 35–45 검토 / 46자↑ 강제분리, layout-rules.md §1).
4. 명사형 제목 — ~와 관련된 ~ → ~ 관련 ~ 또는 단순화.
5. 적의를 보이는 것들 4종 점검 — -적, 의, 것, 들. 빼도 의미 유지되면 빼라.

⚠️ Critical Rules (반드시 준수)

위 1–6은 v2v3.0.1 의 규칙 그대로, 7–8은 v3.0 추가, 9–10은 v3.1 추가, 11은 v3.2 신규 규칙, 12–15는 v3.5.0 신규 규칙, 16은 v3.6.0 신규 규칙, 17은 v3.6.1 신규 규칙, 18은 v3.6.3 신규 규칙, 19는 v3.6.5 신규 규칙, 20은 v3.6.6/3.6.10 신규 규칙, 21은 v3.6.73.6.9 신규 규칙, 22는 v3.6.10 신규 규칙, 23은 v3.6.11 신규 규칙, 24는 v3.6.12 신규 규칙.

참조 파일이 있을 때 워크플로우 (kordoc 활용)

사용자가 hwpx 참조 파일을 주면 (v3.4.0 기준 — 빈 골격 채우기 단일 방식):

# 1단계: 포맷 검증 (kordoc MCP 도구 사용 — 사용 가능한 경우)
# kordoc:detect_format → 'hwpx' 확인

# 2단계: 빈칸·플레이스홀더 점검
# kordoc:parse_document 로 마크다운 변환 후 {{제목}} 같은 패턴 탐지

# 3-A: 빈칸이 있으면 (양식형) → 템플릿 치환 워크플로우
zip_replace('reference.hwpx', 'output.hwpx', {
    '{{제목}}': '...', '{{날짜}}': '...', '{{부서}}': '...'
})
subprocess.run(['python3', 'scripts/fix_namespaces.py', 'output.hwpx'])

# 3-B: 빈칸이 없으면 (서식 추출형) → 빈 골격으로 변환 후 콘텐츠 채우기
subprocess.run([
    'python3', 'scripts/make_skeleton.py',
    'reference.hwpx',                          # 사용자 양식
    '--output-dir', 'templates/format_user/',  # 빈 골격 + 매핑표 생성
])
# 그 다음 표준 빌드 워크플로우 적용 (fill_skeleton → fix_namespaces → validate)

문제 발생 시 자가 진단

Platform Notes

Claude (이 스킬) — 권장 호출 패턴

# Claude 가 사용자와 대화 중일 때:
# 1. 콘텐츠 정리 (대화 기반 또는 파일 입력)
# 2. 사용자에게 참조 hwpx 여부 질문
# 3. 양식 추천 + 확인 (1p/full/gongmun/email)
# 4. skeleton_mapping.json 참조하여 values.json 작성
# 5. fill_skeleton.py → fix_namespaces.py → validate.py 실행
# 6. (풀버전만) simulate_pages.py → ensure_body_anchor.py 적용
# 7. 결과 .hwpx 를 사용자에게 제시

Cursor / Codex (.cursor/rules)

description: "HWPX 작성 시 public-doc-to-hwpx v3.4 사용"
globs: ["*.hwpx", "*.md", "*.docx"]
---
1. SKILL.md 의 4단계 워크플로우를 따른다
2. 표준 빌드 워크플로우는 fill_skeleton → fix_namespaces → validate
3. ALWAYS run fix_namespaces.py after fill_skeleton.py
4. 1p 보고서는 outline_guide.md 의 11가지 유형 중 매칭되는 목차 선정
5. 1p 양식 1쪽 초과 시 풀버전 변경 권고 (자동 변경 금지)

n8n / Cowork

트리거: 파일 업로드 또는 텍스트 입력
노드1: Python 실행 → fill_skeleton.py
노드2: Python 실행 → fix_namespaces.py + validate.py
노드3: 결과 .hwpx 다운로드
노드4: 슬랙/메일 발송

변경 이력 (Changelog)