AI-native PowerPoint 디자인 시스템 — 67개 레이아웃 · Harness Engineering · BLOCK_ARC 차트 · QA 파이프라인 · Python 런타임

Copyright © 2024-2026 Kaku Li. Apache 2.0 라이선스 하에 배포됩니다. 자세한 내용은 NOTICE를 참조하세요.

영어 · 中文说明 · Harness 가이드

표지 (Cover Page)	전략 분석 (Strategy Analysis)	데이터 대시보드 (Data Dashboard)
4열 프레임워크 (4-Column Framework)
컬러 시스템 (Color System)
요약 보고서 (Executive Summary)

pip install python-pptx lxml

import sys, os
sys.path.insert(0, os.path.expanduser('~/.workbuddy/skills/mck-ppt-design'))
from mck_ppt import MckEngine
...

AI 에이전트 (AI Agent)	상태 (Status)
WorkBuddy / Codebuddy
✅ 네이티브 스킬 (mck-ppt-design )
Claude / Claude Code
✅ SKILL.md를 스킬로 로드
Cursor / Continue
✅ 프로젝트 규칙으로 추가
모든 LLM (Any LLM)
✅ SKILL.md를 컨텍스트로 제공

v2.3.3-harness의 새로운 기능 — 스킬을 단순한 vibe-coding 방식에서 기계가 읽을 수 있는 게이트(gates)를 갖춘 구조화된 5단계 생성 방식으로 전환합니다.

Harness가 없을 때는 3,967줄 전체의 SKILL.md가 매번 로드되었고, AI가 즉시 코드로 건너뛰어 렌더링 이후에야 오류를 발견했습니다. Harness를 사용하면 컨텍스트가 점진적으로 로드되고, 콘텐츠 생성 전에 구조가 고정되며, 게이트(gates)가 AI의 자기 평가가 아닌 Python 스크립트로 실행됩니다.

차원 (Dimension)	Harness 미사용 시	Harness 사용 시
컨텍스트 로드 (Context load)	매번 3,967줄 (~6k 토큰)	245줄 엔트리 → 단계별 로드 (~800 토큰)
...	8/12 콘텐츠 슬라이드

QA 점수에 관한 참고 사항: Harness를 사용하지 않은 덱의 점수가 더 높게 나왔는데, 이는 더 단순한 레이아웃을 사용했기 때문입니다 (QA 규칙이 적게 트리거됨). Harness 덱은 더 풍부한 레이아웃(donut, matrix_2×2, value_chain)을 사용하여 더 많은 QA 체크를 노출했습니다. QA 점수는 콘텐츠 품질이 아닌 레이아웃의 건전성(layout health)을 측정하며, 이 둘은 서로 다른 차원입니다.

┌─────────┐ ┌────────────────┐ ┌───────────────────┐ ┌──────────────────┐ ┌──────────┐
│ S1 │──▶│ S2 ⭐ │──▶│ S3 ⭐ │──▶│ S4 ⭐⭐ │──▶│ S5 │
│ Brief │ │ Structure │ │ Content │ │ Render + QA │ │ Deliver │
...

단계	입력 (Input)	출력 (Output)	게이트 (Gate)
S1 Brief	사용자 요청 (User request)	brief.md (대상, 목표, 소요 시간, 메시지)	AI 자가 점검: 3개 필드가 비어 있지 않음
S2 Structure	brief.md	outline.json (슬라이드별 레이아웃 + 인사이트)	AI 자가 점검: 커버 슬라이드 존재, 레이아웃 유효성, 제목이 문장 형태인지 확인
S3 Content	outline.json	content.json (카피, 데이터, 출처)	→ gate_check_s3.py gate_s3.json
S4 Render+QA	content.json	.pptx + gate_result.json	→ gate_check.py gate_result.json
S5 Deliver	gate_result.json (passed: true)	최종 .pptx + experiences/ 업데이트	완료를 선언하기 전 gate_result.json을 읽을 것

S3 Gate — 렌더링 전 콘텐츠 감사 (Content audit):

python ~/.workbuddy/skills/mck-ppt-design/references/scripts/gate_check_s3.py \"./ppt-project-foo/content.json ./ppt-project-foo/" 

점검 항목 (모두 자동 수행, AI 판단 없음):

• four_column / executive_summary / meet_the_team 항목은 3-튜플 (num, title, desc) 형태여야 함
• matrix_2x2 사분면은 3-튜플 (label, bg_color, desc) 형태여야 함 — 정확히 4개
• process_chevron 단계는 5개 이하, 레이블에 \n이 포함되지 않아야 하며, 설명(desc)은 50자 이하일 것
• donut / pie 세그먼트는 6개 이하
• grouped_bar 카테고리는 6개 이하, 시리즈(series)는 3개 이하
• 모든 콘텐츠 슬라이드는 비어 있지 않은 source를 포함해야 함
• 액션 타이틀(Action titles)은 완전한 문장 형태여야 함 (> 10자)

출력 gate_s3.json:

{
"passed": true,
"verdict": "PASS — 可进入 S4 渲染",
...

S4 Gate — 렌더링 후 QA:

python ~/.workbuddy/skills/mck-ppt-design/references/scripts/gate_check.py \"./output.pptx ./ppt-project-foo/" 

모든 QA 오류를 user_code (수정 필수) 또는 engine_bug (화이트리스트 처리, 서면 증거 필요)로 분류합니다. passed = user_code_errors == 0입니다. AI는 이를 무시하거나 덮어쓸 수 없습니다.

출력 gate_result.json:

{
"passed": true,
"overall_score": 92,
...

실제 실행에서 관찰된 가장 흔한 세 가지 실패 모드:

스크립트를 실행하지 않고 "Gate passed"라고 선언하는 경우 — AI가 자가 평가를 바탕으로 통과를 선언함. 해결책: gate_result.json을 반드시 읽을 것

. 파일이 존재하지 않는다면, 게이트(gate)가 실행되지 않은 것임. S3 "머릿속으로 확인했다"— 정신적 검토(Mental review)는 매번 API 형식 오류를 놓침. 해결책: gate_check_s3.py 실행

. 오늘 발생한 3개의 API 형식 버그는 모두 스크립트에 의해 포착되었으며, 셀프 리뷰(self-review)로는 하나도 잡지 못함. 탈출구로서의 "engine_bug"— AI가 게이트를 통과하기 위해 사용자 오류를 엔진 버그(engine bug)로 재분류함. 해결책: gate_check.py 내의 ENGINE_BUG_WHITELIST에 추가

이는 AI의 판단이 아닌 코드임. 서면 증거가 있는 경우에만 화이트리스트(whitelist)에 추가할 것.

~/.workbuddy/skills/mck-ppt-design/
├── SKILL.md # 엔트리 (~245행): 흐름 + 엄격한 규칙 + 인덱스
│ (Harness 도입 전에는 3,967행이었음)
...

v2.0의 근본적인 변화:

연산(compute)의 약 80%를 GPU (LLM 추론)에서 CPU (결정론적 Python 실행)로 이동함.

v1.x에서는 모든 좌표, 모든 색상, 모든 간격 값이 모델에 의해 토큰 단위(token-by-token)로 생성되었습니다. 단 하나의 도넛 차트(donut chart)를 만드는 데 2,800번의 add_rect() 호출이 필요했으며, 각 호출은 GPU로 계산된 토큰이었습니다. 30슬라이드 분량의 덱(deck)은 40,000~60,000개의 출력 토큰을 소모하며 차트당 약 2분이 걸렸습니다.

v2.0은 이러한 결정론적인 작업을 Python으로 추출합니다: eng.donut()

→ 20개의 AI 토큰 → 2,745행의 CPU 실행.

구분	v1.x (순수 GPU)	v2.0 (GPU + CPU)
연산 분할 (Compute split)	~100% GPU	~20% GPU (의사결정) + ~80% CPU (실행)
차트 렌더링 (Chart rendering)	add_rect() 스태킹 (100–2,800개 도형)	BLOCK_ARC 네이티브 아크 (3–4개 도형)
30슬라이드 덱당 출력 토큰	40,000–60,000	9,000–12,000
차트 생성 시간	~2분	<1초
파일 크기 (차트 중심)	2–5 MB	0.5–1 MB

┌──────────────────────────────────────────────────────────┐
│ L5 Harness Engineering (v2.3.3-harness) │
│ 5단계 흐름 · 4개 게이트 · 3계층 지식 │
...

실제 운영 환경(production) 사용을 통해 얻은 13가지 규칙:

#	규칙 (Rule)	방지 항목 (What It Prevents)
1	커넥터(connectors)를 절대 사용하지 말 것	커넥터 p:style로 인한 파일 손상 (File corruption)
2	항상 _clean_shape()를 호출할 것	그림자/3D 아티팩트 (Shadow/3D artifacts)
3	저장 후 full_cleanup()을 실행할 것	잔류 테마 효과 (Residual theme effects)
4	CJK(한중일) 텍스트에 set_ea_font()를 설정할 것	한자가 상자(boxes)로 렌더링되는 현상
5	add_line() 대신 add_hline()을 사용할 것	커넥터 기반 선(line)으로 인한 복구 프롬프트 발생
6–8	오버플로(Overflow) + 간격(spacing) + 동적 크기 조정 (dynamic sizing)	텍스트 겹침, 콘텐츠 누락
9	원형 차트에는 BLOCK_ARC 사용 필수	사각형 블록 비대화 (Rect-block bloat)
10	피어 폰트 일관성 (Peer font consistency)	동일 행 내 도형 간 서로 다른 폰트 크기
...

├── SKILL.md # Harness 엔트리 (~245행, 기존 3,967행)
├── mck_ppt/ # Python 런타임 (runtime) 엔진
│ ├── engine.py # 67개 레이아웃 메서드 (methods)
...

버전 (Version)	날짜 (Date)	주요 내용 (Highlights)
v2.3.3-harness	2026-05-03	Harness Engineering: SKILL.md 3,967→245행; 3계층 지식 분할; 기계 판독 가능한 S3/S4 게이트 (gate_check.py, gate_check_s3.py); experiences/ 자기 개선 루프 (self-refinement loop); 안티 패턴 (anti-pattern) 경고
v2.3.3	2026-04-09	레이아웃 개선, 통합 컬러 팔레트, 레거시(legacy) 레이아웃 5개 제거
v2.3.2	2026-03-25	DeckBuilder 스토리라인 생성기; stacked_bar 수정; chart_legend_overflow QA 규칙; 33슬라이드 AI 엔터프라이즈 데모
v2.3.1	2026-03-24	numbered_list_panel을 위한 동적 행 높이 (Dynamic row height); text_line_collision QA 규칙
v2.3.0	2026-03-24	생성 후 검토 + 자동 수정 파이프라인 (auto-fix pipeline); 피어 폰트 조화 (peer font harmonization); 14개 오류 → 0개
v2.2.0	2026-03-23	AI 커버 이미지 파이프라인 (Hunyuan 2.0 + rembg)
v2.0.5	2026-03-21	table_insight (#71), 아이콘 라이브러리, 통합 릴리스
v2.0	2026-03-19	BLOCK_ARC 차트, Python 런타임 엔진, 3계층 아키텍처 (three-tier architecture)
v1.9	2026-03-12	9가지 운영 가드레일 (production guard rails)
v1.0	2026-03-02	초기 릴리스

|
|
위 버튼을 클릭하여 글로벌 커뮤니티에 참여하세요 |

중국어 문서 펼치기

이번 업데이트의 핵심은 새로운 레이아웃을 추가하는 것이 아니라, AI가 PPT를 만드는 방식을 "감(feeling) 기반"에서 "엔지니어링(engineering) 기반"으로 전환하는 것입니다.

SKILL.md가 3,967행에서 245행으로 슬림화되었습니다. 기존에는 모든 내용을 전체 로드(~6,000 tokens)했으나, 이제는 진입점(entry point)이 245행에 불과하며 각 단계에서 필요한 파일만 온디맨드(on-demand)로 로드합니다(~800 tokens부터 시작).

5단계 프로세스 + 기계 판독형 게이트키핑 (Machine-readable Gatekeeping). PPT 하나를 생성하는 과정은 더 이상 "한 문장 → 즉시 코드 작성"이 아니라 다음과 같습니다:

• S1 요구사항 정의 → brief.md 작성
• S2 구조 설계 → outline.json 작성 (각 페이지의 레이아웃과 인사이트 문장 확정)
• S3 내용 채우기 → content.json 작성 → gate_check_s3.py 실행
• S4 렌더링 + QA → .pptx 생성 → gate_check.py 실행
• S5 인도(Delivery) → gate_result.json 읽기 → passed: true 확인 후 인도

게이트키핑은 AI의 구두 판단이 아니라 Python 스크립트입니다. 이것이 가장 핵심적인 변화입니다. 이전에는 AI가 "7개의 오류는 모두 엔진 설계 방식이므로 게이트를 통과합니다"라고 말하며 스스로에게 완료 인증서를 써줄 수 있었습니다. 하지만 이제는 gate_check.py를 실행하여 출력된 gate_result.json의 passed 필드가 user_code_errors == 0이라는 Python 불리언(Boolean) 값에 의해 결정되므로, AI가 이를 우회할 수 없습니다.

차원	Harness 없음	Harness 있음
인사이트 제목 비율	0/7 (모두 "주제어" 태그)	8/12 (숫자 판단이 포함된 완전한 문장)
레이아웃 다양성	~5종	9종 (donut/matrix_2x2/value_chain 등)
섹션 구조	10페이지 평면 구성	15페이지 (3개 섹션 + 구분 페이지)
QA 점수	95 (단순한 레이아웃으로 규칙 트리거 적음)	92 (복잡한 레이아웃으로 더 많은 콘텐츠 포함)

QA 점수가 높다고 해서 품질이 좋은 것은 아닙니다. Harness가 없는 버전은 더 단순한 레이아웃을 사용하여 QA 규칙을 적게 트리거했기 때문에 점수가 더 높았습니다. 반면 Harness 버전은 더 풍부한 레이아웃(donut, 4분면 매트릭스, 가치 사슬 등)을 사용하며 인사이트 밀도가 훨씬 높습니다.

"패턴화된 문제"를 수정할 때마다 AI는 experiences/ 디렉토리의 해당 파일에 기록합니다. 다음에 PPT를 만들 때 AI는 S3 단계에서 이 파일들을 읽어 동일한 유형의 오류를 능동적으로 방지합니다:

• experiences/overflow.md — 텍스트 넘침 경험 (6개)
• experiences/chart-limits.md — 차트 데이터 세그먼트 제한 (2개)
• experiences/layout-pitfalls.md — 레이아웃별 주의사항 (5개)
• experiences/cjk-issues.md — CJK(한중일) 렌더링 문제 (2개)

v2.0의 본질은 연산량의 약 80%를 GPU(대규모 언어 모델 추론)에서 CPU(결정론적 Python 실행)로 이전하는 것입니다.

도넛 차트 하나를 만드는 데 2,800번의 add_rect() 호출이 필요했던 것이 단 1줄의 eng.donut()으로 바뀌었습니다. 이로 인해 약 2분 걸리던 GPU 추론이 1초 미만의 CPU 실행으로 단축되었으며, 파일 크기는 5MB에서 0.5MB로 줄어들었습니다.

# v1.x: AI가 각 사각형의 좌표를 출력 (2800+ tokens)
for angle in range(0, 360):
    add_rect(slide, x + cos(angle)*r, y + sin(angle)*r, ...)
...

pip install python-pptx lxml
# WorkBuddy / Codebuddy에 설치: skill 마켓에서 mck-ppt-design 검색
# 또는 수동 설치: cp -r /path/to/mck-ppt-design ~/.workbuddy/skills/