19 KiB
프롬프트 구조 및 내용 해설
(프롬프트) 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 작업이 아니라 브라우저 실행으로 대체되는 구조입니다.