# 프롬프트 구조 및 내용 해설
## (프롬프트) HTML 변환

---

## 이 프롬프트가 하는 일

04단계에서 완성된 본문 MD와 05단계에서 생성된 시각화 HTML 파일들을 하나의 보고서 HTML로 통합합니다. 이 HTML은 07단계 A4 보고서 퍼블리싱 렌더링 엔진(v82)의 직접 입력값이 됩니다.

단, 이 단계는 단순히 콘텐츠를 합치는 것이 아닙니다. 07단계 렌더링 엔진이 올바르게 동작하려면 특정 HTML 구조, CSS 스타일시트, JS 페이지네이션 엔진이 모두 포함되어야 합니다. 따라서 이 단계의 출력물은 **콘텐츠 통합 + 렌더링 인프라 탑재**를 동시에 수행한 완성형 HTML입니다.

---

## 전체 구성 한눈에 보기

| 순서 | 구성요소 | 역할 한 줄 요약 |
|:---:|---------|--------------|
| 1 | **절대 원칙** | 본문·시각화 내용 수정 금지 |
| 2 | **역할 정의** | AI의 작업 태도 설정 + 07단계 엔진과의 관계 명시 |
| 3 | **사전 준비** | 입력 파일 3가지 확인 |
| 4 | **STEP 1** | 본문 목차와 시각화 파일 매핑 |
| 5 | **STEP 2** | 표지·요약 내용 확인 |
| 6 | **STEP 3-A** | 07단계 렌더링 엔진 6대 원칙 |
| 7 | **STEP 3-B** | HTML 전체 구조 (raw-container + template + script) |
| 8 | **STEP 3-C** | CSS 전문 — A4 렌더링 스타일시트 |
| 9 | **STEP 3-D** | 본문 변환 규칙 — MD → HTML 매핑 |
| 10 | **STEP 3-E** | 시각화 삽입 규칙 |
| 11 | **STEP 3-F** | JS 렌더링 엔진 전문 — 페이지네이션 |
| 12 | **STEP 3-G** | JS 엔진 동작 요약 표 |
| 13 | **STEP 4** | 통합 결과 검토 (CSS/JS 포함 확인 추가) |
| 14 | **STEP 5** | 최종 파일 출력 보고 |

---

## 1. 절대 원칙

**이 프롬프트에서 하는 역할**

이 단계는 생성이 아닌 통합 단계입니다. 그런데 MD를 HTML로 변환하는 과정에서 AI가 가장 자주 저지르는 오류가 있습니다. 문장이 어색해 보이면 자연스럽게 다듬고, 긴 단락을 보기 좋게 요약하고, 중복처럼 보이는 문장을 슬쩍 삭제하는 것입니다. 이것은 모두 04단계에서 편집장이 확인하고 확정한 내용을 AI가 임의로 훼손하는 행위입니다.

"토씨 하나 바꾸지 않고"라는 표현은 이 원칙의 강도를 명확히 전달합니다. 오탈자가 있어도, 문장이 어색해도, 원본 그대로 옮기는 것이 이 단계의 유일한 임무입니다. 내용에 문제가 있다면 편집장이 판단하고 04단계로 돌아가서 수정해야 합니다. AI가 변환 과정에서 임의로 처리하면 안 됩니다.

시각화 HTML 코드를 수정하지 않는다는 원칙은 05단계에서 설계된 스타일과 구조가 삽입 과정에서 변형되는 것을 막습니다.

---

## 2. 역할 정의 — 07단계 엔진과의 관계를 명시하는 이유

**기존 해설에서 달라진 점**

기존 프롬프트는 "보고서 HTML 편집 전문가"라는 역할만 부여했습니다. 변경된 프롬프트는 여기에 07단계 렌더링 엔진(v82)이 어떤 구조를 요구하는지까지 미리 설명합니다.

**왜 이렇게 바뀌었는가**

06단계의 출력물은 사람이 읽는 문서가 아니라 07단계 JS 엔진이 처리하는 입력 데이터입니다. AI가 07단계 엔진의 요구사항을 모른 채 "보기 좋은 HTML"을 만들면, 정작 엔진이 파싱할 수 없는 구조가 나옵니다. 역할 정의에서 "이 HTML은 렌더링 엔진의 입력값"이라는 관계를 먼저 설정해야 이후 STEP 3의 구체적 지시들이 왜 그 형태여야 하는지 AI가 이해합니다.

---

## 3. STEP 1 — 본문 목차와 시각화 파일 매핑

**왜 매핑 테이블을 먼저 만드는가**

시각화 파일이 여러 개일 때 어느 파일이 어느 절에 들어가는지 먼저 정리하지 않으면 삽입 누락이나 위치 오류가 발생합니다. 매핑 테이블을 편집장이 확인함으로써 삽입 위치가 의도와 맞는지 검증합니다.

---

## 4. STEP 2 — 표지·요약 내용 확인

**표지와 요약을 이 단계에서 입력하는 이유**

표지의 작성자·날짜·소속은 문서 내용과 무관한 정보로 편집장이 직접 지정해야 합니다. 요약(Executive Summary)은 전체 본문이 완성된 이후에야 작성 가능한 내용입니다. 04단계에서 본문을 생성할 때는 전체가 완성되지 않은 상태이므로 이 단계에서 처음 입력합니다.

---

## 5. STEP 3 — 통합 HTML 생성

STEP 3은 이 프롬프트의 핵심 단계이며, 7개 하위 절(3-A ~ 3-G)로 구성됩니다. 각 절이 존재하는 이유를 순서대로 해설합니다.

---

### 5-A. 렌더링 엔진 6대 원칙 (3-A)

**왜 06단계 프롬프트에 07단계 엔진의 동작 원칙을 미리 명시하는가**

06단계 AI가 HTML을 만들 때, 07단계 엔진이 어떤 규칙으로 페이지를 나누는지 모르면 엔진과 충돌하는 구조를 만들 수 있습니다. 예를 들어 엔진은 H1 태그에서만 페이지를 나누는데(H1 Only Break), AI가 H2에서도 `page-break-before`를 삽입하면 중복 분할이 발생합니다. AI가 표를 `<div>`로 감싸면 엔진의 Smart Fit(표 축소)이 해당 표를 감지하지 못합니다.

6대 원칙을 미리 보여주는 이유는 "이 규칙을 AI가 직접 구현하라"는 것이 아닙니다. "이 규칙이 이미 엔진에 구현되어 있으니, 당신은 엔진이 처리할 수 있는 깨끗한 구조만 만들라"는 뜻입니다. AI의 역할 경계를 명확히 하는 것입니다.

| 원칙 | 06단계 AI가 지켜야 할 사항 |
|------|------------------------|
| Deep Sanitization | box-content 안에 불필요한 class/style을 넣지 말 것 (엔진이 제거함) |
| H1 Only Break | 페이지 나눔 관련 CSS를 삽입하지 말 것 (엔진이 처리함) |
| Orphan Control | 제목 뒤에 빈 태그를 넣지 말 것 (엔진이 제목 위치를 자동 조정함) |
| Smart Fit | 표/그림을 원본 크기 그대로 넣을 것 (엔진이 축소 판단함) |
| Gap Filling | 빈 공간 채우기를 시도하지 말 것 (엔진이 자동 처리함) |
| Visual Standard | 여백·캡션 위치를 직접 지정하지 말 것 (CSS가 처리함) |

---

### 5-B. HTML 전체 구조 (3-B)

**HTML이 3개 영역으로 나뉘는 이유**

변경된 프롬프트는 출력 HTML의 구조를 ① raw-container, ② page-template, ③ script 세 영역으로 명시합니다.

**① raw-container가 `display: none`인 이유**

raw-container는 화면에 직접 표시되는 영역이 아닙니다. JS 렌더링 엔진이 이 안의 콘텐츠를 읽어서 A4 페이지(.sheet)로 재조립한 뒤 body에 추가합니다. 렌더링이 완료되면 raw-container는 JS에 의해 삭제됩니다. 즉, 원본 데이터의 임시 저장소 역할입니다.

**② page-template이 `<template>` 태그인 이유**

HTML5의 `<template>` 태그는 브라우저가 렌더링하지 않지만 JS에서 `content.cloneNode(true)`로 복제할 수 있는 특수 태그입니다. 엔진이 A4 페이지를 하나 만들 때마다 이 템플릿을 복제하여 헤더·본문·푸터 구조를 가진 sheet를 생성합니다. 이 구조 덕분에 모든 페이지가 동일한 레이아웃을 유지합니다.

**box-cover / box-toc / box-summary / box-content 4개 박스로 나누는 이유**

07단계 엔진은 각 박스를 다른 방식으로 처리합니다. cover는 별도 레이아웃으로 표지를 생성하고, toc는 목차를 자동 그룹화하며, summary는 넘침 시 자간을 자동 압축하고, content는 H1 기준으로 페이지를 분할합니다. 4개 박스를 구분하지 않으면 엔진이 표지에 페이지 번호를 넣거나, 본문에 목차 압축 로직을 적용하는 등의 오동작이 발생합니다.

---

### 5-C. CSS 전문 (3-C)

**왜 CSS를 "수정하지 마십시오"로 고정하는가**

이 CSS는 단순한 스타일이 아니라 JS 렌더링 엔진과 밀접하게 연동된 설정값들을 포함합니다.

예를 들어 `.sheet`의 `width: 210mm; height: 297mm`는 A4 물리 규격이고, JS의 `CONFIG.maxHeight: 970`은 이 높이에서 상하 여백 20mm를 뺀 본문 가용 높이입니다. CSS에서 여백을 25mm로 바꾸면 JS의 maxHeight와 불일치하여 콘텐츠가 넘치거나 빈 공간이 생깁니다.

`.atomic-block`의 `break-inside: avoid`는 엔진의 Smart Fit 로직과 연동됩니다. `.highlight-box`의 스타일은 `detox()` 함수의 하이라이트 박스 감지 조건과 맞물립니다. 하나를 바꾸면 다른 쪽이 깨지는 구조이므로 CSS를 고정하는 것입니다.

**색상 체계(CSS Custom Properties)의 설계 의도**

`--primary: #006400`(짙은 녹색), `--accent: #228B22`(포레스트 그린), `--light-green: #E8F5E9`(연한 녹색)의 3단계 색상 체계는 보고서 전체의 시각적 통일성을 유지합니다. H1의 border-bottom, H2의 border-left, 표 헤더의 배경색이 모두 이 변수를 참조합니다. 색상을 바꾸고 싶다면 CSS 변수 값만 수정하면 전체 문서에 일괄 적용되도록 설계되어 있습니다.

**주요 CSS 구성 요소와 역할**

| CSS 영역 | 역할 | JS와의 연동 |
|----------|------|-----------|
| `.sheet` | A4 용지 규격 정의 | `CONFIG.maxHeight`와 연동 |
| `.page-header`, `.page-footer` | 여백 20mm 내 헤더/푸터 배치 | `createPage()`가 텍스트 주입 |
| `.body-content` | 본문 영역 위치 고정 | `renderFlow()`가 높이 측정 기준으로 사용 |
| `h1, h2, h3` | 제목 스타일 + `white-space: nowrap` | 엔진의 제목 자동 축소 로직과 연동 |
| `p, li` | 본문 텍스트 기본 스타일 | 엔진의 자간 최적화(Squeeze) 대상 |
| `.toc-*` | 목차 레벨별 스타일 | `formatTOC()`가 클래스를 자동 부여 |
| `.highlight-box` | 강조 박스 표준 스타일 | `detox()`의 박스 감지·변환 대상 |
| `.atomic-block` | 분할 불가 블록 | 엔진이 통째로 다음 페이지로 이동 |
| `.squeeze`, `.toc-squeeze` | 압축 모드 스타일 | 엔진이 넘침 감지 시 동적 적용 |
| `#box-summary` 전용 스타일 | 요약 페이지 자간/행간 축소 | Smart Squeeze 로직과 연동 |
| `@media print` | 인쇄 시 그림자 제거, 여백 초기화 | 브라우저 인쇄 → PDF 변환 대응 |

---

### 5-D. 본문 변환 규칙 (3-D)

**왜 box-content 안에 class/style을 붙이지 말라고 하는가**

JS 렌더링 엔진의 `detox()` 함수는 SVG, 목차, 표지, 하이라이트 박스를 제외한 모든 요소의 class와 style을 제거합니다. 06단계 AI가 열심히 `class="paragraph"` `style="color:blue"`를 붙여도 엔진이 전부 지워버립니다. 불필요한 작업을 지시하지 않기 위해 "붙이지 마십시오"로 명시합니다.

단, `highlight-box` 클래스는 예외입니다. `detox()`의 화이트리스트에 `highlight-`가 포함되어 있어 이 클래스는 보존됩니다. 04단계 본문에서 강조 박스로 지정된 영역이 있다면 `<div class="highlight-box">` 로 감싸야 합니다.

**`<!-- page X -->` 주석을 제거하는 이유**

04단계에서 절 단위로 생성할 때 AI가 페이지 구분 주석을 삽입하는 경우가 있습니다. 페이지 분할은 07단계 JS 엔진이 콘텐츠 높이를 측정하여 자동으로 수행하므로, 수동 페이지 마커는 불필요합니다. 남겨두면 엔진 동작에 영향을 주지는 않지만 raw-container에 불필요한 노드가 생겨 `getFlatNodes()`의 처리 효율이 떨어집니다.

---

### 5-E. 시각화 삽입 규칙 (3-E)

**`<figure class="atomic-block">`으로 감싸는 이유**

렌더링 엔진의 `renderFlow()` 함수는 노드 유형을 판별할 때 `FIGURE` 태그이거나 `atomic-block` 클래스를 가진 요소를 "분할 불가 블록"으로 인식합니다. 이 블록은 페이지를 넘어갈 경우 통째로 다음 페이지로 이동하며, Smart Fit 로직에 의해 15% 이내 넘침이면 85%로 축소됩니다.

시각화를 `<figure class="atomic-block">`으로 감싸지 않으면 엔진이 이를 일반 텍스트로 취급하여 중간에서 잘라버릴 수 있습니다. 차트나 다이어그램이 반으로 잘리는 것을 방지하기 위해 이 래핑이 필수입니다.

**`<figcaption>`으로 캡션을 배치하는 이유**

CSS에서 `figcaption`에 `text-align: center`와 `font-size: 9.5pt`가 지정되어 있습니다. 또한 `detox()` 함수는 `FIGURE` 태그 내부의 `h3, h4, .chart-title`을 `display: none`으로 숨깁니다. 이는 시각화 내부에 이미 제목이 있을 때 캡션과 중복되는 것을 방지하기 위한 로직입니다. 따라서 캡션은 시각화 내부 제목이 아닌 `<figcaption>` 태그로 통일해야 합니다.

**시각화의 `<style>`과 `<script>`를 이동하는 이유**

시각화 HTML 파일은 단독 실행을 위해 자체 `<style>`과 `<script>`를 포함합니다. 여러 시각화를 하나의 HTML에 합칠 때 이를 그대로 두면 스타일이 충돌하거나 스크립트가 중복 실행됩니다. `<style>`은 `<head>`로, `<script>`는 렌더링 엔진 `<script>` 앞으로 모아서 충돌을 방지합니다.

**클래스명에 절 번호 prefix를 붙이는 이유**

각 시각화가 `.container`, `.box` 같은 일반적인 클래스명을 사용할 경우, 여러 시각화를 합치면 서로의 스타일이 덮어씌워집니다. `.viz-1-2-container`처럼 절 번호를 prefix로 붙이면 각 시각화의 스타일이 독립적으로 유지됩니다.

---

### 5-F. JS 렌더링 엔진 전문 (3-F)

**왜 JS도 "수정하지 마십시오"로 고정하는가**

이 JS는 CSS의 수치, HTML의 id/class 명, 그리고 4개 박스 구조와 정밀하게 맞물려 동작합니다. 대표적인 의존 관계는 아래와 같습니다.

| JS 코드 | 의존 대상 |
|---------|---------|
| `CONFIG.maxHeight: 970` | CSS `.sheet` height 297mm - 상하 여백 40mm |
| `document.getElementById('box-cover')` | HTML `<div id="box-cover">` |
| `document.getElementById('page-template')` | HTML `<template id="page-template">` |
| `node.classList.contains('highlight-box')` | CSS `.highlight-box` 스타일 |
| `node.classList.contains('atomic-block')` | CSS `.atomic-block` break-inside 규칙 |
| `body.classList.add('toc-squeeze')` | CSS `.toc-squeeze` 압축 스타일 |

JS를 수정하면 이 의존 관계가 깨져 페이지 분할 오류, 표지 누락, 목차 깨짐 등이 발생합니다. 06단계 AI의 역할은 엔진을 개선하는 것이 아니라, 엔진이 처리할 수 있는 콘텐츠를 만드는 것입니다.

**엔진의 핵심 함수별 역할**

| 함수 | 역할 | 실행 시점 |
|------|------|---------|
| `detox()` | 모든 요소의 class/style 제거 + 표준 스타일 재적용. SVG 내부 제외. 하이라이트 박스 자동 변환 | 노드 평탄화 시 각 요소에 적용 |
| `formatTOC()` | box-toc 내 H1/H2/H3 분석 → toc-lvl-1/2/3 클래스 리스트 자동 생성 | getFlatNodes()에서 toc 처리 시 |
| `getFlatNodes()` | 중첩된 div/section 구조를 평탄화하여 1차원 노드 배열로 변환 | renderFlow() 호출 전 |
| `renderFlow()` | Place→Squeeze→Check→Split 4단계로 노드를 A4 페이지에 순차 배치 | 각 섹션(toc, summary, body) 렌더링 시 |
| `createPage()` | page-template을 복제하여 새 A4 sheet 생성. cover는 별도 레이아웃 적용 | renderFlow()에서 페이지 넘침 시 |

---

### 5-G. JS 동작 요약 표 (3-G)

**왜 프롬프트 사용자에게 엔진 내부 동작을 설명하는가**

3-F의 JS 코드는 약 300줄이며, 프롬프트를 사용하는 사람(편집장)이 코드를 직접 읽을 것을 기대할 수 없습니다. 그러나 엔진이 어떤 순서로 무엇을 하는지 모르면 문제가 생겼을 때 원인을 파악할 수 없습니다.

예를 들어 "요약 페이지 글자가 너무 작다"는 문제가 발생했을 때, 동작 요약 표가 없으면 300줄 코드를 읽어야 합니다. 표가 있으면 "5번: summary에 Smart Squeeze 적용" → "CSS의 `.squeeze` 스타일 확인"으로 즉시 추적이 가능합니다.

이 표는 코드를 읽지 않아도 "무엇이 어떤 순서로 일어나는지"를 파악할 수 있게 해주는 디버깅 지도입니다.

---

## 6. STEP 4 — 통합 결과 검토

**기존 해설에서 달라진 점**

기존 검토 항목은 본문 누락, 시각화 삽입, 구조 태그, 목차 구조, 출처 태그의 5가지였습니다. 변경된 프롬프트에서는 3가지 항목이 추가되었습니다.

| 추가된 검토 항목 | 검증 대상 | 누락 시 발생하는 문제 |
|---------------|---------|------------------|
| **CSS 포함** | 3-C절의 A4 렌더링 스타일시트 전문 | 브라우저에서 열면 서식 없는 텍스트만 표시됨. JS 엔진이 높이 계산을 잘못하여 페이지 분할 오류 발생 |
| **JS 포함** | 3-F절의 페이지네이션 렌더링 엔진 전문 | raw-container가 `display: none`인 채로 남아 화면에 아무것도 표시되지 않음 |
| **폰트 임포트** | `@import url('...Noto+Sans+KR...')` | 시스템 기본 폰트로 렌더링되어 한글 자간·행간이 틀어지고, JS의 높이 측정값이 달라져 페이지 분할 위치가 어긋남 |

**`[근거없음]` 항목을 수정하지 않고 그대로 포함하는 이유**

`[근거없음]`으로 표기된 항목은 편집장이 추가 자료로 보완할지, 해당 내용을 삭제할지 판단해야 하는 항목입니다. AI가 임의로 처리하지 않고 편집장에게 알려서 최종 판단을 받습니다.

---

## 7. STEP 5 — 최종 파일 출력 보고

**기존 해설에서 달라진 점**

기존 출력 보고에는 장·절 수, 시각화 수, 표지·목차·요약 포함 여부만 있었습니다. 변경된 프롬프트에서는 CSS 포함 여부와 JS 포함 여부가 추가되었습니다.

**CSS/JS 포함을 출력 보고에 명시하는 이유**

이전 프롬프트에서 06단계 출력물은 콘텐츠만 담긴 HTML이었고, CSS와 JS는 07단계에서 별도로 적용하는 구조였습니다. 변경된 프롬프트에서는 06단계 출력물 자체가 완성형 HTML(콘텐츠 + CSS + JS)입니다. 따라서 출력 보고에 "이 파일을 브라우저에서 열면 A4 보고서가 자동 렌더링됩니다"라는 안내와 함께 CSS/JS 탑재 여부를 확인 항목으로 포함합니다.

**다음 단계 안내가 달라진 이유**

기존에는 "07 A4 보고서 퍼블리싱 프롬프트에 이 HTML을 입력하십시오"였습니다. 변경된 프롬프트에서는 렌더링 엔진이 이미 HTML에 포함되어 있으므로, "이 HTML을 브라우저에서 열면 A4 보고서가 자동 렌더링됩니다. Chrome 인쇄(Ctrl+P)로 PDF 저장이 가능합니다"로 안내가 바뀌었습니다. 즉, 07단계가 별도의 AI 작업이 아니라 브라우저 실행으로 대체되는 구조입니다.