이 레포가 무엇을 하는 물건인가.
당신이 Claude에게 "이력서 만들어줘", "이 리서치를 장문 보고서로 정리해줘"라고 하면, 내용은 잘 나오지만 결과물은 매 세션마다 회색·평면·제각각 레이아웃으로 흘러간다. Kami는 이 표류를 막기 위해 "색은 이것만, 폰트는 한 종류, 여백은 이렇게"라는 단 하나의 제약 규칙 세트를 만들어 두고, 에이전트가 그 규칙대로만 조판하도록 만든다.
Kami는 실행되는 "앱"이 아니라 스킬 파일(Markdown 지시서) + HTML 템플릿 + 검증 스크립트의 묶음이다. Claude Code/Desktop에 설치하면, Claude가 SKILL.md의 절차를 읽고 9가지 템플릿 중 알맞은 것을 골라 빈칸을 채운 뒤 WeasyPrint로 PDF를 렌더링하고, 페이지 수·폰트·색 위반 여부까지 자동 점검해 내보낸다.
Kami는 문서 조판(document typesetting) 스킬이다. 9가지 문서 타입(원페이저·장문·레터·포트폴리오·이력서·슬라이드·종목 리포트·체인지로그·랜딩페이지)을 하나의 디자인 언어로 통일한다. 따뜻한 양피지 캔버스(#f5f4ed), 잉크블루 단일 강조색(#1B365D), 세리프 위계, 빽빽한 편집 리듬이 그 언어다. tw93의 3부작 — Kaku(書く, 코드 작성)·Waza(技, 습관 훈련)·Kami(紙, 문서 전달) — 중 "문서"를 맡는다.
SKILL.md(절차·규칙을 적은 Markdown)와 그것이 참조하는 템플릿·스크립트·레퍼런스다. 자연어 요청이 들어오면 에이전트가 description의 트리거를 보고 스스로 스킬을 발동(auto-trigger)한다. 별도 슬래시 명령이 필요 없다.트렌딩 이유 · "AI 문서 생성" 일반 대비 장점.
2026년 현재 누구나 Claude로 문서를 뽑지만, 결과물이 "AI가 만든 티가 나는 밋밋함"에서 못 벗어난다. Kami가 스타를 모으는 이유는 이 "AI 슬롭(slop)" 문제를 디자인 제약을 데이터·규칙으로 박제해 풀었기 때문이다. 첫째 9개 문서 타입 × 3개 언어(EN/CN/KO) 템플릿, 둘째 에이전트가 따를 만큼 단순하되 출하 품질을 보장할 만큼 엄격한 규칙, 셋째 PDF/PPTX/Marp/랜딩페이지까지 다중 출력, 넷째 렌더 검증 자동화(페이지 수·폰트·색 위반 점검)다.
| 비교 항목 | 맨손 AI 문서 생성 | Kami 스킬 |
|---|---|---|
| 디자인 일관성 | 세션마다 제각각 | 10개 불변 규칙(invariants)으로 고정 |
| 색 사용 | 다채로운 회색·임의 색 | 양피지 + 잉크블루 단일 강조색 |
| 폰트 | 기본 산세리프 | 언어별 세리프 1종(Charter/TsangerJinKai/Source Han Serif K) |
| 출력 포맷 | 주로 Markdown/텍스트 | PDF(WeasyPrint)·PPTX·Marp·인터랙티브 랜딩페이지 |
| 다이어그램 | 외부 도구·Mermaid | 14종 인라인 SVG 다이어그램 내장 |
| 품질 보증 | 사람이 눈으로 확인 | build.py --verify로 페이지·폰트·색 자동 검증 |
| 다국어 | 임의 | EN/CN/KO 전용 템플릿 + CJK 폰트 폴백 복구 |
LLM에게 "보기 좋게 만들어줘"라고만 하면, 매 호출마다 다른 색 팔레트·다른 폰트 크기·다른 여백이 나온다. 저자(tw93)의 동기가 정확히 이것이었다 — 미국 주식 리서치 리포트를 Claude로 쓸 때마다 "회색·평면, 매번 다른 레이아웃"이 나와 읽고 싶지 않은 페이지가 됐다. 능력의 문제가 아니라 제약의 부재가 문제였다.
Kami는 색·타이포·간격·그림자 규칙을 CHEATSHEET.md·references/design.md·tokens.json으로 외부화했다. 에이전트는 이 "한 줄짜리 제약 언어"를 읽고 가장 가까운 템플릿을 골라 빈칸만 채운다. 거기에 scripts/build.py --verify가 WeasyPrint로 실제 렌더링한 뒤 페이지 수 상한·임베드 폰트·오프팔레트(off-palette) 색을 점검한다. "단순하게, 그러나 출하 가능하게"가 설계 철학이다.
조판 엔진(파이썬)·문서 표현(HTML/CSS)·배포(스킬 패키지) 각각.
Kami의 "백엔드"는 서버가 아니라 로컬에서 HTML을 PDF로 굽는 파이썬 스크립트 묶음이다. 핵심은 WeasyPrint(HTML/CSS → PDF)와, 렌더 결과를 검사하는 검증 모듈들이다. 모든 무거운 의존성은 선택적(optional)으로 처리해, 없어도 그래픽 없이 동작하도록 설계됐다.
| 요소 | 역할 |
|---|---|
| Python 3.12 | 빌드·검증·패키징 스크립트 전체 언어(CI 기준 3.12). |
WeasyPrint | 핵심. HTML+CSS를 인쇄 품질 PDF로 렌더링. 문서·슬라이드의 기본 출력 경로. |
pypdf | 렌더된 PDF의 페이지 수·임베드 폰트 검사(검증 게이트). |
Pygments (선택) | 코드 블록 구문 강조. 없으면 코드는 흑백으로 렌더(여전히 동작). |
python-pptx (선택) | slides.py로 편집 가능한 PPTX 생성(요청 시에만). |
pdffonts | 임베드 폰트 확인 — 1차 폰트 대신 폴백만 쓰였으면 경고. |
| cairo / pango / harfbuzz | Linux에서 WeasyPrint가 런타임에 링크하는 네이티브 그래픽 라이브러리. |
| 요소 | 역할 |
|---|---|
| HTML 템플릿(9종 ×3 언어) | {{PLACEHOLDER}} 자리에 에이전트가 내용을 채우는 조판 골격. |
| CSS 디자인 토큰 | tokens.json/styles.css — 색·타입·간격을 변수로. 템플릿 간 동기화 검사 대상. |
| 인라인 SVG 다이어그램(14종) | 아키텍처·플로우·간트·도넛·캔들스틱 등. <figure>에 드롭인. |
| 랜딩페이지(스크린 우선) | 갤러리 캐러셀·히어로 진입 애니메이션·반응형(880/480px)·prefers-reduced-motion. |
| Marp 변형 | Markdown 우선 슬라이드(assets/templates/marp/) — 요청 시. |
| 언어별 세리프 | EN=Charter, CN=TsangerJinKai02, JA=YuMincho, KO=Source Han Serif K. 페이지당 1종. |
| 요소 | 역할 |
|---|---|
| 스킬 패키지 | scripts/package-skill.sh → dist/kami.zip. 대용량 CJK 폰트는 제외해 경량화. |
| 설치 채널 | npx skills add tw93/kami · Claude Code 플러그인 마켓 · Claude Desktop ZIP 업로드. |
.claude-plugin/ | 플러그인 매니페스트 — 마켓플레이스 등록용 메타데이터. |
| 폰트 복구 | scripts/ensure-fonts.sh — 설치본에서 누락된 CJK 폰트를 로컬→jsDelivr CDN 순으로 복구. |
| 업데이트 체크 | scripts/check-update.sh — 하루 1회 읽기전용 버전 확인(데이터 미전송, 오프라인 무해). |
| CI(GitHub Actions) | check.yml — 린트·토큰 동기화·테스트·렌더 검증·패키지 감사. release.yml — 릴리스 ZIP 자동 발행. |
| 랜딩페이지 호스팅 | vercel.json — Vercel 정적 배포(다국어 index + hreflang). |
@page·페이지 나눔·인쇄 색보정 등 "종이"를 1급 시민으로 다룬다. Kami가 슬라이드·문서를 PDF로 굽는 기본 경로이며, 이 때문에 CSS에 WeasyPrint 특유의 제약(예: 태그 배경에 rgba() 쓰면 사각형이 이중으로 그려지는 버그)이 디자인 규칙으로 박혀 있다.자연어 요청 → 의도 추출 → 템플릿 선택 → 빈칸 채움 → 렌더 → 검증.
Kami의 "런타임"은 에이전트(Claude)가 SKILL.md를 단계별로 따라가는 과정 그 자체다. 사용자가 "원페이저 만들어줘"라고 하면, 에이전트는 ① 업데이트 체크 → ② 브랜드 프로필 로드 → ③ 언어 판별 → ④ 의도 4축 추출 → ⑤ 결정 트리로 문서 타입 선택 → ⑥ 템플릿의 {{PLACEHOLDER}} 채움 → ⑦ build.py로 PDF 렌더 → ⑧ 페이지·폰트·색·밀도 검증의 순서로 작동한다. 핵심은 "디자인 결정을 매번 새로 하지 않고, 규칙 문서에서 읽어 온다"는 점이다.
Kami가 천재적인 부분은, 보통 사람이라면 코드(컴포넌트 라이브러리)로 만들 디자인 시스템을 에이전트가 읽고 따르는 "규칙 문서 + 빈칸 템플릿"으로 표현했다는 점이다. 이것은 "실행 가능한 코드"가 아니라 "에이전트가 준수할 계약(contract)"이다.
CHEATSHEET.md 첫머리의 10개 규칙이 Kami의 헌법이다. ① 배경은 양피지 #f5f4ed, 순백 금지 ② 강조색은 잉크블루 #1B365D 하나 ③ 모든 회색은 따뜻한 톤(노란-갈색 기), 차가운 블루그레이 금지 ④ 페이지당 세리프 1종 ⑤ 세리프 굵기 500 고정, bold 금지 ⑥ 행간 규칙(제목 1.1~1.3 / 본문 1.5~1.55) ⑦ 자간 규칙 ⑧ 태그 배경은 solid hex만(rgba 금지) ⑨ 깊이는 ring/whisper 그림자만, hard drop shadow 금지 ⑩ 이탤릭 금지. 이 "금지 목록"이 곧 품질 보증이다.# 출력을 만들기 전, 계약을 잠근다:
language · template · output format · page target ·
visual acceptance check · verification command
# 황금률: 새 템플릿/CSS/의존성/스크립트 플래그를
# "현재 요청으로 만족 못 할 때"만 추가한다.
Use the nearest existing template and verification path.
# 우선순위(낮을수록 약함):
explicit prompt > editorial judgment > habit notes
> frontmatter defaults > built-in defaults이 계약은 에이전트가 "임의로 새 디자인을 발명"하는 것을 막는다. 가장 가까운 기존 템플릿·검증 경로를 재사용하라는 강제 규칙이 일관성을 만든다.
| 패턴 | Kami에서의 구현 |
|---|---|
| 제약 주도 설계 | "무엇을 금지하는가"를 10개 불변 규칙으로 명문화. 자유도↓ → 품질 하한 보장. |
| 토큰 단일 진실원 | tokens.json의 색·타입 값을 모든 템플릿이 공유. --sync로 드리프트 검사. |
| 템플릿 = 빈칸 | 로직 없는 {{PLACEHOLDER}} 골격. 에이전트는 "내용만" 채운다. |
| 렌더 후 검증 게이트 | WeasyPrint 렌더 → 페이지/폰트/색/밀도 자동 점검. 사람 눈 대신 스크립트가 거름. |
| 의도 추출(silent) | 목적·청중·제약·성공기준 4축을 배경에서 점검. 2개+ 불명확할 때만 1줄 질문. |
| 4계층 컨텍스트 | 명시 프롬프트 > 편집 판단 > 습관 > 기본값. 브랜드 프로필은 "빈칸만 조용히 채움". |
| 우아한 성능 저하 | Pygments 없으면 흑백, CJK 폰트 없으면 폴백 복구. 없어도 깨지지 않음. |
Kami를 "신입에게 '아무거나 예쁘게'가 아니라, 회사 디자인 가이드 1장을 쥐여 주는 아트 디렉터"로 생각하자. "색은 잉크블루 하나만, 폰트는 이 세리프 하나만, 그림자 금지"라고 못 박으면, 신입(에이전트)이 매번 다른 취향을 발명할 여지가 없다. 결과는 "누가 만들어도 같은 톤"이 된다. 자유를 빼앗아 일관성을 얻는 거래 — 이것이 제약 시스템의 본질이다.
규칙 문서(루트 MD)·템플릿(assets)·검증 스크립트(scripts) 3축.
① CHEATSHEET.md의 10대 불변 규칙으로 "디자인 헌법" 파악 → ② SKILL.md의 Step 0~3·결정 트리로 "에이전트가 어떻게 판단하나" → ③ assets/templates/에서 템플릿 하나(예: one-pager-ko.html)를 열어 {{PLACEHOLDER}} 구조 확인 → ④ references/tokens.json으로 색·타입 토큰의 단일 진실원 → ⑤ scripts/verify.py로 "어떻게 자동 검증하나". 핵심 통찰은 이 다섯에 다 있다.
에이전트 스킬 + 디자인 시스템 + PDF 파이프라인에서 무엇을 배우나.
Kami는 "실행 코드 없이도 복잡한 능력을 에이전트에게 줄 수 있다"는 살아 있는 사례다. 핵심은 SKILL.md의 description 트리거 → 단계별 절차 → 실행 계약(execution contract) 구조다. 특히 "새 템플릿/의존성을 함부로 만들지 말고 가장 가까운 것을 재사용하라"는 스코프 잠금 규칙이, LLM이 매번 다른 걸 발명하는 것을 막는 결정적 장치임을 배울 수 있다.
SKILL.md처럼 ① description 트리거 ② 단계별 절차 ③ "하지 말 것" 금지 목록 ④ 출력 검증 한 줄로 구성된 미니 스킬 지시서를 한 페이지로 써 보라."예쁘게"는 측정 불가지만 "잉크블루 외 색 금지"는 측정 가능하다. Kami는 tokens.json(색·타입 단일 진실원) + lint.py(오프팔레트 색 검출)로 디자인 규칙을 자동으로 검사 가능한 형태로 바꿨다. "변하는 부분(내용)은 빈칸으로, 안 변하는 부분(디자인)은 토큰·규칙으로"의 모범 사례다.
tokens.json 형태(키-값 JSON)로 추출하고, "이 팔레트를 벗어나는 색이 있으면 경고"하는 20줄짜리 파이썬 린터를 짜 보라.웹 개발자에게 가장 실용적인 학습 포인트. "브라우저 화면"이 아니라 "종이"를 1급 시민으로 다루는 CSS(@page·break-inside:avoid·인쇄 색보정·페이지 나눔)를 Kami 템플릿에서 그대로 배울 수 있다. WeasyPrint 특유의 함정(rgba 태그 배경 이중 사각형 버그 → solid hex로 우회)도 실전 지식이다.
pip install weasyprint pypdf 후, Kami의 resume-en.html을 python -c "from weasyprint import HTML; HTML('resume-en.html').write_pdf('out.pdf')"로 직접 PDF로 구워 보고, pdffonts out.pdf로 어떤 폰트가 임베드됐는지 확인하라.Kami는 사람 눈 대신 verify.py(페이지 수·폰트)·checks.py(밀도·고아 텍스트·placeholder 잔존)로 품질을 강제한다. 특히 "템플릿에 {{PLACEHOLDER}}가 안 채워진 채 남았는가", "마지막 페이지가 25% 이상 비었는가" 같은 검사는 "AI가 빈칸을 깜빡하거나 어색하게 채우는" 실패를 자동으로 잡아 낸다. CI(check.yml)에 묶여 모든 PR에서 돌아간다.
{{ 로 시작하는 미채움 placeholder가 남아 있으면 exit 1"을 반환하는 검증 스크립트를 만들고, 그걸 GitHub Actions에서 PR마다 돌리도록 워크플로 YAML을 작성하라.설치는 한 줄, PDF 렌더에만 그래픽 라이브러리가 필요하다.
| 항목 | 요구사항 |
|---|---|
| 에이전트 | Claude Code(플러그인은 v2.1.142+) · Claude Desktop · 또는 ~/.agents/를 읽는 호환 에이전트(Codex·OpenCode·Pi). |
| 설치 | npx skills add tw93/kami -a claude-code -g -y 한 줄. Desktop은 kami.zip 업로드. |
| PDF 렌더(핵심) | Python 3.12 + pip install weasyprint pypdf --break-system-packages. Linux는 cairo/pango/harfbuzz 네이티브 라이브러리 필요. |
| 코드 강조(선택) | pip install Pygments. 없으면 코드 블록은 흑백(렌더는 정상). |
| PPTX(선택) | python-pptx — 편집 가능한 슬라이드가 명시적으로 필요할 때만. |
| CJK 폰트 | 대용량 폰트는 패키지에서 제외. ensure-fonts.sh가 로컬→jsDelivr CDN 순으로 복구. |
| 네트워크 | 설치·폰트 복구·업데이트 체크에만. 렌더 자체는 오프라인 가능. |
| 랜딩페이지 배포(선택) | Vercel/Netlify 등 정적 호스팅. vercel.json·sitemap.xml·llms.txt 동반 파일 제공. |
Kami의 모든 무거운 의존성은 optional_deps.py를 거치는 선택 의존성이다. Pygments가 없으면 코드는 흑백으로, CJK 폰트가 없으면 폴백 폰트로, WeasyPrint가 없으면 명확한 설치 힌트와 함께 우아하게 실패한다. "최소 설치로 핵심은 동작, 추가 설치로 품질 향상"이라는 점진적 설계다.
난이도별 5단계 — 설치부터 스킬 확장까지.
Claude Code/Desktop에 Kami를 설치하고 이력서를 만들어줘(또는 build me a resume)라고 요청해, 양피지·잉크블루·세리프의 PDF 이력서를 받아 본다. 같은 내용을 "맨손"으로 요청한 결과와 나란히 비교해 제약 시스템의 효과를 체감한다.
CHEATSHEET.md의 10대 불변 규칙을 읽고, Kami가 만든 PDF에서 ① 배경이 순백이 아닌 양피지인가 ② 강조색이 잉크블루 하나뿐인가 ③ 그림자/이탤릭이 없는가를 직접 확인한다. 규칙 하나를 골라 "왜 이렇게 제약했는가"를 한 문단으로 설명해 본다.
pip install weasyprint pypdf Pygments 후, 레포의 scripts/build.py resume-en 또는 --verify resume-en을 돌려 PDF를 생성하고 페이지 수·임베드 폰트 검증 출력을 읽는다. 그다음 템플릿 CSS의 색 하나를 팔레트 밖 값으로 바꾸고 build.py --check가 오프팔레트 경고를 잡아내는지 확인한다.
assets/diagrams/에서 architecture.html 또는 timeline.html의 <svg> 블록을 추출해, long-doc-ko.html의 <figure> 안에 드롭인한다. references/diagrams.md의 선택 가이드·안티패턴 표를 먼저 읽고, Kami 토큰 색에 맞게 SVG 색을 조정해 본다.
기존 9개에 없는 문서 타입(예: "주간 보고서") 템플릿을 가장 가까운 기존 템플릿을 복제해 만들고, shared.py의 TEMPLATES에 등록한 뒤 checks_thresholds.json에 페이지 상한을 추가한다. build.py --check 린트와 --verify 렌더 검증을 모두 통과시켜, 토큰 동기화·페이지 상한 게이트를 직접 경험한다.
6주 코스 — 에이전트 스킬 기초부터 디자인 시스템 자동화까지.
| 주차 | 주제 | 실습 · 참고 |
|---|---|---|
| 1주차 | 에이전트 스킬 개념 — SKILL.md 구조·description 트리거·auto-trigger | Kami SKILL.md 정독 · Anthropic Agent Skills 문서 |
| 2주차 | 제약 주도 디자인 — 불변 규칙·디자인 토큰 | CHEATSHEET.md·tokens.json 분석 · 미니 린터 구현 |
| 3주차 | HTML→PDF 인쇄 CSS — @page·페이지 나눔·인쇄 색보정 | WeasyPrint 문서 · resume.html·long-doc.html CSS |
| 4주차 | 검증 자동화 — 렌더 후 페이지/폰트/색/밀도 점검 | verify.py·checks.py·lint.py 정독 |
| 5주차 | 인라인 SVG 데이터 시각화 — 14종 다이어그램·차트 | assets/diagrams/·references/diagrams.md 안티패턴 |
| 6주차 | 패키징·배포·CI — 스킬 ZIP·플러그인 마켓·GitHub Actions | package-skill.sh·.github/workflows/ · 본인 스킬 발행 |
본문·소스에 나온 용어 빠른 참조.
| 용어 | 의미 |
|---|---|
| Kami (紙·かみ) | 일본어 "종이". 완성된 아이디어가 내려앉는 표면 = 문서 디자인 시스템. |
| Agent Skill | 에이전트에게 작업 수행법을 알려주는 지시서 패키지(SKILL.md + 자산). |
| constraint system | "금지 목록"으로 품질 하한을 보장하는 설계. UI 프레임워크와 반대. |
| 10 invariants | Kami의 디자인 헌법 — 양피지·단일 강조색·세리프 1종·bold/이탤릭 금지 등. |
| WeasyPrint | HTML+CSS → 인쇄 품질 PDF 렌더 라이브러리. Kami의 기본 출력 경로. |
| design tokens | tokens.json의 색·타입·간격 값. 모든 템플릿이 공유하는 단일 진실원. |
| execution contract | 출력 전 잠그는 계약(언어·템플릿·포맷·페이지·검증). 임의 발명 방지. |
| verify / check / sync | build.py 모드 — 렌더 검증 / CSS 규칙 린트 / 토큰 동기화 검사. |
| off-palette | 허용 팔레트를 벗어난 색. lint.py가 자동 검출. |
| placeholder | 템플릿의 {{값}} 빈칸. 미채움 잔존 시 checks.py가 경고. |
| graceful degradation | 선택 의존성이 없어도 핵심은 동작(코드 흑백·폰트 폴백)하는 점진적 설계. |
| brand profile | ~/.config/kami/brand.md — 이름·브랜드색·기본값을 빈칸만 조용히 채움. |
| Kaku·Waza·Kami | tw93 3부작 — 코드 작성 / 습관 훈련 / 문서 전달. |
| Marp | Markdown으로 슬라이드를 쓰는 방식. Kami의 슬라이드 변형 중 하나. |
SKILL.md · CHEATSHEET.md · references/design.md · references/diagrams.mdnpx skills add tw93/kami -a claude-code -g -y · 플러그인 마켓 /plugin marketplace add tw93/kami