이 스킬의 역할
덱을 문서가 아닌 빌드 대상으로 취급합니다:
| 아티팩트 | 역할 |
|---|---|
template.pptx | 툴체인 — 슬라이드가 아키타입 카탈로그입니다. 항상 필수. |
deck.mdx | 소스 — 누구나 편집하는 유일한 파일 |
assets/*.svg | 생성된 아트, 동시에 소스 — 디자인 없이 내용만 |
deck.pptx | 빌드 아티팩트 — 매번 전체 재생성됨 |
deck.pdf + 페이지 미리보기 | 실제 사람이 보는 것 — 레이아웃이 드러나는 유일한 곳 |
각 출력 슬라이드는 템플릿 슬라이드의 복제본이며 내용만 교체되므로 템플릿 디자인이 바이트 단위로 유지됩니다. 처음부터 새로 레이아웃하는 경우는 없습니다.
엔진: scripts/deck.py (절대 경로로 호출).
색상 변경 (모든 pptx; 빌드된 덱의 경우 template.pptx를 재염색하고 재빌드): scripts/ppt_keycolor_changer.py, 절차와 프리셋은 references/recolor.md — 탐색, 명도 매핑, 확인, 교체, 검증.
상시 지침
- 참조 템플릿 없이 빌드하지 마세요. 내장된 덱 디자인이나 폴백은 없습니다. 사용자가
.pptx를 주지 않았다면 중단하고 요청하세요 — 다른 방식으로 슬라이드를 조립하지 말고, 일반 덱을 제공하지 말고, 템플릿을 임의로 만들지 마세요. 엔진도 거부하지만, 그 요청은 어떤 작업보다 먼저 당신이 해야 합니다. - 소스 파일은
deck.mdx이며, 절대deck.md가 아닙니다. 이 파일은 읽히는 것이 아니라 컴파일됩니다. 엔진은 다른 확장자를 거부합니다. - 작성 전에 카탈로그를 조회하세요. 템플릿을 추측하여
deck.mdx를 작성하지 마세요.catalog를 실행하고 출력된 슬롯 ID에 맞춰 작성하세요. - 출력 pptx를 직접 편집하지 마세요. 다음 빌드 시 재생성됩니다. 수정은
deck.mdx에 반영하세요. build전에 항상check를 실행하고 사용자에게 경고를 보여주세요. 오버플로우 경고는 빽빽한 텍스트와 읽을 수 없는 슬라이드 사이의 경고입니다.- 가시성이 우선, 깔끔함이 아닙니다.
| transparent는 이미지 내용이 슬라이드 위에서 읽을 수 있을 때 옳습니다.check는 그렇지 않을 때 알려주며, 그때는 이미지 뒤에 패널을 배치하는 것이 더 나은 답입니다. 더 깔끔해 보인다고 해서 투명성을 선택하지 마세요. - 내용을 자를 때는 반드시 알리세요.
check가 백분율을 보고하므로, 그 값을 사용자에게 알리고| fit을 제안하세요. 그림의 절반이 사라지는 것은 테이블 행이 슬라이드 밖으로 나가는 것과 같은 결함입니다. - 그림 슬롯의 아트를 바이너리로 직접 작성하지 마세요. SVG로 작성하여 덱이 텍스트로부터 재현 가능하도록 유지하세요. 누군가 붙여넣은 PNG는 재생성, 재색상, diff 검토가 불가능합니다.
- 덱은 사람이 읽는 것이므로, 직접 확인하세요. 렌더러를 사용할 수 있을 때는
build대신render로 마무리하세요 — 레이아웃 감사와 페이지 미리보기만이 텍스트 충돌을 발견할 수 있는 유일한 곳입니다. 렌더러를 사용할 수 없다면 레이아웃을 확인한 것처럼 암시하지 말고 보고서에 명확히 알리세요. - 아키타입을 임의로 만들지 마세요. 맞는 템플릿 슬라이드가 없다면 그렇게 말하고, 내용을 수정할지 템플릿을 확장할지 물어보세요 — 근사하지 마세요.
- 무시하기로 선택한 경고도 보고하세요. 괜찮다고 판단한 오버플로우 경고도 최종 보고서에 포함되어야 합니다 — 사용자가 실제로 슬라이드를 볼 사람입니다.
- 차트는 읽기 전용입니다. 선택한 아키타입에 차트가 있을 때는 이 사실을 명시하세요. 사용자가 PowerPoint에서 차트를 편집하지 않는 한 템플릿의 숫자가 그대로 전달됩니다.
프로세스
0단계 · 참조 템플릿 확보
템플릿이 없으면 다른 모든 것보다 먼저 .pptx를 요청하세요:
"레퍼런스 템플릿 pptx를 주세요. deck-builder는 템플릿 슬라이드를 복제하는 방식이라, 템플릿 없이는 만들 수 있는 슬라이드가 없습니다."
템플릿에 대한 설명, 비슷해 보이는 덱, 나중에 제공하겠다는 약속으로 진행하지 마세요.
1단계 · 템플릿 카탈로그 조회
python3 /abs/path/scripts/deck.py catalog \
--template "template.pptx" --output "deck.catalog.md"
모든 아키타입을 @s1…@sN으로 출력하며, 각각의 슬롯, 템플릿에 현재 표시된 내용, 용량 추정치를 보여줍니다. 다른 모든 작업보다 먼저 읽으세요.
2단계 · 아키타입에 내용 매핑
내용이 없으면 사용자에게 요청하세요. 그런 다음 md를 작성하기 전에 슬라이드당 한 줄 계획을 보여주세요:
1. @s1 표지 — 제목 + 부제
2. @s3 요약 — 불릿 3개 + 한 줄 결론
3. @s7 숫자 — 표 4행
계획에 대한 승인을 받으세요. 잘못된 아키타입 선택이 가장 비용이 큰 실수입니다. 잘못된 표현이 아닙니다.
3단계 · deck.mdx 작성
---
template: template.pptx
template_hash: 5f84440a3521 # 카탈로그에서 가져옴 — 덱을 템플릿 구조에 고정
output: deck.pptx
---
## @s3
title: 분기 요약
text1:
- 응답 p99 **2.1s → 340ms**
- 배포 실패율 12% → 0.4%
table1:
| 지표 | 이전 | 이후 |
| p99 | 2.1s | 340ms |
pic1: assets/arch.svg
notes: 숫자의 출처를 먼저 말할 것
text5: !drop
그림은 맞춤 모드를 사용합니다 — | fit은 이미지 전체를 유지하고, 기본값 fill은 잘라냅니다 — 그리고 | transparent는 PNG 배경을 제거합니다. 생략한 슬롯은 템플릿 내용을 유지합니다.
전체 구문 — 슬롯 형식, !drop, notes:, 인라인 강조, 개요 수준, 그리고 template_hash가 방지하는 것 — 은 references/mdx-syntax.md에 있습니다. 첫 슬라이드를 작성하기 전에 읽으세요.
3b단계 · 덱에 필요한 아트 생성
그림 슬롯의 아트는 .svg로, 템플릿 색상과 프레임의 정확한 pt 크기로 작성하세요 — 둘 다 catalog가 출력합니다. 이는 덱의 다른 부분과 마찬가지로 소스가 되며, 빌드 시 PNG로 래스터화됩니다.
규칙, 근거 및 작업 예시: references/generated-art.md.
4단계 · 검사
python3 /abs/path/scripts/deck.py check --deck deck.mdx
오류는 수정해야 합니다. 경고는 판단 영역입니다 — 무시하기로 결정한 것까지 포함하여 모든 경고를 표면화하세요.
| 측정 항목 | 기준 |
|---|---|
| 테이블이나 텍스트가 슬라이드 밖으로 나감 | 슬라이드 가장자리 — 오류, 손실된 행 이름 표시 |
| 템플릿이 한 줄로 유지하는 슬롯에 비해 너무 긴 줄 | 해당 슬롯의 자체 프레임(em 단위). 한글은 라틴 문자와 다르게 계산됨 |
| 슬롯이 템플릿이 넣은 양보다 훨씬 적게 담음 | 템플릿 자체 볼륨 — 프레임이 그만큼 그려졌고 슬라이드에 구멍이 생김 |
| 텍스트가 디자인보다 아래로 내려감 | 템플릿 자체 줄 수와 그 아래에 있는 것 |
| 크롭 손실, 유효 dpi, 팔레트 이탈, 붙여넣은 박스 테두리 | 프레임, 화면 및 템플릿 팔레트 |
| 그림 위의 텍스트 | 실제로 뒤에 있는 픽셀: 큰 글씨 3:1, 본문 4.5:1 |
텍스트 위에 그려진 그림은 오류입니다 — 텍스트가 이미지 뒤에 가려집니다.
여기의 모든 추정치는 절대 기준보다 템플릿 자체 내용에 대해 보정됩니다. 대부분의 프레임은 이미 줄 바꿈이 일어나는 텍스트를 담도록 그려졌기 때문입니다. 약 한 줄 미만의 여백은 정적 추정치로 해결할 수 없습니다: 오직 6단계만이 이를 해결합니다.
5단계 · 빌드
python3 /abs/path/scripts/deck.py build --deck deck.mdx [--output out.pptx] [--strict]
동일한 deck.mdx는 항상 바이트 동일한 pptx를 생성합니다.
6단계 · 렌더링 및 확인
python3 /abs/path/scripts/deck.py render --deck deck.mdx
빌드, LibreOffice를 통한 변환, 모든 페이지의 PNG 미리보기 작성, 렌더링된 지오메트리 감사 — overlap (두 텍스트 프레임 충돌), bunched (한 프레임 내 줄 간격이 해당 프레임의 정상보다 좁아 텍스트가 상자를 넘어선 경우), off-slide (렌더러가 잘라냄). 깨끗함은 깨끗함입니다: 감사는 프레임 간 비교하고 각 프레임의 중간값에 대해 피치를 측정하므로, em 박스가 100% 라인을 초과하는 CJK 폰트가 오류를 일으키지 않습니다.
render는 먼저 렌더러가 가지고 있지 않은 템플릿의 서체를 알려줍니다. 대체된 폰트는 모든 줄을 다시 감싸므로, 해당 폰트가 설치될 때까지 미리보기의 줄 바꿈은 덱의 것이 아닌 대체 폰트의 것입니다 — 수정 방법은 단어를 줄이는 것이 아니라 폰트를 설치하는 것입니다. pptx 자체는 항상 올바른 서체를 지정합니다.
미리보기는 레이아웃을 위해 읽고, 간격을 위해 읽지 마세요. LibreOffice는 CJK와 라틴 문자 사이에 기본적으로 패딩을 추가하므로, 평균 42분은 미리보기에서 평균 42 분으로 렌더링되지만 pptx는 원래 문자열을 유지합니다. 간격을 결함으로 처리하기 전에 빌드된 파일에서 <a:t>를 확인하세요.
렌더러는 PATH 상의 soffice 또는 DECK_RENDER_DOCKER=<image>입니다. 둘 다 없으면 render는 레이아웃을 확인한 척하지 않고 거부합니다 — 그 사실을 말하고 build로 폴백하세요.
출력 템플릿
빌드 후 보고서:
빌드 완료 — <출력 경로>
슬라이드 <N>개 · 템플릿 <이름> · 이미지 <M>개 삽입
렌더 검사 — 겹침 0건 (또는: 3페이지 제목이 본문과 겹칩니다)
아키타입 사용
@s1 ×1 표지
@s3 ×4 본문
확인 필요
· 3번 슬라이드 title 58자 (프레임 ~39자/줄) — 두 줄로 넘어갑니다
· 5번 슬라이드 chart1 — 차트 수치는 템플릿 값 그대로입니다
다음 수정은 deck.mdx만 고치고 다시 build 하세요. 출력 pptx는 손대면 날아갑니다.
Claude의 역할 / 사용자의 역할
| Claude | 사용자 |
|---|---|
| 참조 pptx 요청, 없으면 진행 거부 | 템플릿(필수) 및 원시 내용 제공 |
catalog 실행, 슬롯 맵 읽기 | 아키타입 목록 검토 |
| 슬라이드별 아키타입 계획 제안 | 계획 승인 또는 재배열 |
deck.mdx 작성 및 수정 | 원할 때마다 직접 deck.mdx 편집 |
check 실행, 모든 경고 보고 | 오버플로우 경고의 중요성 결정 |
render 실행, 미리보기 확인, 충돌 보고 | pptx 열기, 필요시 차트 편집 |
제약 사항
약속할 수 있는 것을 바꾸는 여섯 가지:
| 제약 | 결과 |
|---|---|
| 새 레이아웃 없음 | 모든 슬라이드는 복제본입니다. 아키타입이 없는 내용은 PowerPoint에서 템플릿을 확장해야 합니다 — 근사하지 말고 그렇게 말하세요. |
| 템플릿은 필수 | 내장 디자인이나 폴백 없음. |
| 차트는 쓰기 불가 | build는 템플릿의 숫자를 그대로 둡니다. 그림 슬롯에 SVG를 사용하세요. |
| 프레임은 이동하지 않음 | 짧게 쓰면 간격이 남습니다. check가 보고하며, 템플릿만이 간격을 줄일 수 있습니다. |
| 레이아웃 확인에는 렌더러 필요 | check는 추정하며 한 줄 미만의 여백을 해결할 수 없습니다. render만이 충돌을 볼 수 있습니다. |
| 가독성은 PNG에서만 확인 | JPEG나 SVG 배경 위의 텍스트는 점수가 매겨지지 않습니다. 상속된 텍스트 색상은 그대로 둡니다. |
전체 표와 각 제약이 어느 단계에서 발견되는지: references/limits.md.
관련 스킬
write:plans(문서 목적) — 슬라이드에 매핑하기 전에 내용 개발think:untangle-thoughts— 흩어진 노트를 2단계에 필요한 슬라이드별 구조로 정리