bookforge — 주제 한 줄 → 상업도서급 한국어 전자책 PDF (Claude Code·Codex 스킬)

bookforge는 주제 한 줄(또는 완성 원고)을 받아 실제 단행본의 해부 구조 — 표지·차례·장 도비라·러닝 헤드·판권면 — 를 갖춘 상업도서급 PDF를 만드는 Claude Code·OpenAI Codex 겸용 에이전트 스킬이다. 콘텐츠는 마크다운으로만 쓰고 조판은 스타일 팩과 스크립트가 전담하며, 품질은 QC 게이트가 물리적으로 강제한다 — 게이트를 통과하지 못한 PDF는 final/에 존재할 수 없다.

한눈에 보기

프로젝트 성격: 전자책·PDF 책·책 조판을 생성하는 에이전트 스킬 (SKILL.md 라우터 — 모드 감지→파이프라인→서브 문서 포인터 구조).
고정 기준: main의 60dbb79de42fb0668613a5141a8eaa18a1346d5f (chore: strip local paths from style provenance, add usage guards, add .gitignore, 2026-08-11).
모드 2종: topic(주제→조사→목차→집필→조판) / manuscript(완성 원고→인제스트→조판).
스타일 6종: practical·insight·academic·essay·business·magazine — 각각 STYLE.md 규칙서 + theme.typ|theme.css + tokens.json을 갖는다. Typst 트랙 4종 + HTML→Chromium 트랙 2종(insight·magazine).
요구 사항: Typst 0.14+ / Python 3 + PyMuPDF + markdown-it-py / (HTML 트랙만) Playwright Chromium. 폰트는 OFL 5종 동봉.
라이선스 상태: README는 MIT를 선언하지만 GitHub API snapshot은 NOASSERTION — 출처 불일치로 기록하며 사실로 승격하지 않는다.
검증 상태: 설치·scaffold·build·QC 게이트·PDF 렌더·Playwright 실행은 수행하지 않았다. 예시 6종 PDF의 쪽수(28·30·35·32·28·25쪽)는 README 주장이다.

설치와 사용 (README 기준, 실행 안 함)

git clone https://github.com/gongnyang/bookforge.git
cd bookforge
ln -sfn "$PWD" ~/.claude/skills/bookforge
ln -sfn "$PWD" ~/.codex/skills/bookforge
ln -sfn "$PWD" ~/.agents/skills/bookforge

에이전트에게 자연어로 지시하면 스킬이 모드·스타일·분량을 스스로 정해 끝까지 진행한다. 수동 실행도 가능하다:

python3 scripts/scaffold.py mybook --style essay --title "제목" --length short
python3 scripts/build.py mybook        # → draft/book.pdf
python3 scripts/qc_gate.py mybook      # 게이트 통과 시에만 → final/mybook.pdf

파이프라인 (P0~P5)

SKILL.md가 체크리스트를 강제한다: P0 계약(모드·스타일·분량 확정→스캐폴드) → P1 콘텐츠(outline.json + chapters/ch-NN.md) → P2-3 빌드(build.py → draft/) → P4 게이트(qc_gate.py PASS → final/) → P5 시각 검수(contact_sheet.py로 표지·차례·도비라·본문을 직접 눈으로 확인 — “파일이 생성되었다는 것은 완료가 아니다”).

콘텐츠 계약: 각 장 파일 첫 줄 # {outline의 title} 일치 필수, ::: tip/info/warn/quote/stat/pull 콜아웃 디렉티브, 표 캡션은 표 바로 앞 문단의 [표] 제목 | 자료: 출처 한 줄, stat 수치는 같은 장 본문에 실재해야 한다(G10).

핵심 설계 — 품질 게이트가 물리적으로 강제한다

final/은 qc_gate.py만이 만들 수 있다. 게이트 순서: G10(렌더 전 인용·수치 실재 검사) → G1 렌더·분량 범위 / G2 폰트 전량 임베드 / G3 bbox 오버플로 0 / G4 목차·북마크↔실제 장 시작 쪽 정합 → G7-FRAME(판면 정합) / G7-BLANK(의도치 않은 빈 면) / G12(recto 맞춤 금지) / G11(사유 코드 무결성) / G7-TAIL·MID·DOC(꼬리 밀도 밴드) / G8(공기 채움·행송 편차) / G9(제목 고립·widow) / G6(시각 검수).

특히 G10-QUOTE는 “날조”를 렌더 전 md 검사로 차단한다 — 콜아웃(quote/stat)의 12자 이상 분절·수치 토큰이 같은 챕터 본문에 실재해야 하며, 공백·인용부호·콤마 정규화와 약/가량/내외 ±5% 근사만 허용된다. “박스에만 있는 숫자”는 날조로 판정된다.

배치 규칙서 (references/pagination.md) — 실측 기반의 채움·비움 규율

근거: 전통조판·알고리즘 실측·한국 상업본 PyMuPDF 실측 287유닛·매거진/리포트 조사 + 교차 비판 토론 3라운드. 표기: [실측]·[문헌]·[통념]. 핵심 전제: 완성된 글을 잘 나눈다. 채우거나 비우면 이유가 있어야 하고, 그 이유는 기계가 판정한다.

불변식 5개: INV-1 목표 쪽수는 조판의 입력이 아님(분량은 원고 단계 총행수로 판정, 산출물 쪽수에 하드 게이트 없음) / INV-2 기본값은 꽉 참(flushbottom) / INV-3 비움은 이름을 가진다(구조 파생 면제 또는 pageroles.json 사유 코드로만 정당화) / INV-4 본문 행송은 상수(feathering 금지) / INV-5 엔진은 콘텐츠를 생성하지 않는다(G10 HARD FAIL).
모드 이원화: REFIT(기존 원고 재배치 — 절 병합·분할 금지, 최소 개입) vs PLAN(신규 생산 — 절별 목표 행수 q 계량·구조 수술 허용).
실측이 확정한 조판 사실: 자간(tracking)과 어간(spacing)은 엔진 입장에서 같은 레버(페이지별 행수 배열까지 등가), 행간·문단 간격은 미세 레버가 아니라 계단 스위치(안 넘으면 1비트도 안 변하고 넘으면 면 용량 ±1행이 튐), 총행수를 바꾸는 레버는 자간/어간/폰트크기/판면폭뿐.
레버 사다리 L0~L6: 줄바꿈 재계산(무제한) → 어간 [80%,125%] → 자간(하드캡은 폰트 사이드베어링에서 산출 — Noto Serif KR −20/1000em) → 탄성 슬롯 → 요소 이동 → 원고 국소 개입. 그리디 조정은 비단조라 실패 → 실패 장만 자간/어간 ±2% 격자 전수 탐색 + 편차 최소 해 선택.
꼬리 밴드: 행수 < 6은 사유 코드로도 구제 불가(HARD). reach HARD 하한 practical/insight/academic/business 0.45, essay/magazine 0.35. 상업본 287유닛 중 채움률 0.31 미만 0건 — “3~4줄 면”은 상업 단행본에 존재하지 않는 상태다.
사유 코드 채널 6종: PART_DIVIDER / FULL_BLEED_PLATE / EXEC_SUMMARY / ESSAY_BREATH / MAGAZINE_WHITESPACE / TOC_TAIL — 각 코드는 기계 선행조건 미충족 시 코드 자체가 FAIL(도장 방지). 인쇄 관습(RECTO_ADJUST·SIGNATURE_PAD·ENDPAPER)은 단면 전자책에서 재현 시 오히려 FAIL(G12).

스타일 팩과 예시 6종

스타일	정체성	판형	엔진	예시 (README 주장)
practical	IT·실용 활용서	153×225	Typst	『바로 쓰는 프롬프트 패턴 24』 28쪽
insight	기술 동향 리포트	182×257	HTML→Chromium	『온디바이스 AI 2026』 30쪽
academic	학술 단행본 (신국판·3선표)	153×225	Typst	『게임이론의 기초』 35쪽
essay	미니멀 에세이 (사륙판·먹 1도)	128×188	Typst	『퇴근길의 문장들』 32쪽
business	컨설팅 백서 (navy 시스템)	200×280	Typst	『중소기업 AI 도입 전략』 28쪽
magazine	트렌드 매거진 (에디토리얼 그리드)	200×265	HTML→Chromium	『TREND BRIEF』 25쪽

생성 이미지 정책(art-policy): 표지·본문 아트는 무텍스트 생성 이미지만 사용하고 모든 글자는 조판 레이어가 벡터로 얹는다. 생성 이미지가 실린 책은 캡션·판권면에 표기한다.

공식 사실·해석·미검증 범위

고정 커밋에서 직접 확인한 것

SKILL.md 라우터의 P0~P5 체크리스트와 콘텐츠 계약 문법(::: tip/stat 디렉티브, 표 캡션 규칙)
topic 모드의 조사→목차 설계(스타일별 장 구조·분량 산정 short 5~~7장×2,000~~3,000자)→장별 집필 절차
pagination.md의 5개 불변식·REFIT/PLAN 이원화·레버 사다리·꼬리 밴드·사유 코드 6종·게이트 G1~G12 정의
저장소 구조(112 entries: 96 files/16 dirs), 스타일 팩 6종의 STYLE.md 존재와 크기, OFL 폰트 5종 동봉
스타일 자동 선택 표(SKILL.md P0) — 사용자가 지정하지 않으면 “질문하지 않고” 내용 성격으로 결정

저장소가 주장하지만 재현하지 않은 것

예시 6종 PDF의 완성도·쪽수(28·30·35·32·28·25쪽)와 내지 미리보기 품질
QC 게이트 12종이 실제 PDF에서 동작한다는 것 (qc_gate.py 소스는 캡처했지만 실행 안 함)
Typst 0.14+ / PyMuPDF / Playwright 조합의 실제 호환성
상업본 287유닛 실측 데이터의 재현성 (규칙서의 근거 주장)

이번 ingest에서 하지 않은 것

스킬 설치(심링크), scaffold/build/qc_gate/contact_sheet 실행
예시 PDF 다운로드·렌더·시각 검수, Typst/Chromium 렌더링
generate 아트 파이프라인, 폰트 임베드 검증
README 예시 쪽수와 실제 PDF의 대조

description	표지·차례·장 도비라까지 갖춘 상업도서급 전자책 PDF를 만드는 Claude Code·Codex 겸용 에이전트 스킬 — 6 스타일 팩·실측 기반 배치 규칙서·밀도 QC 게이트.
tags	ai-coding, productivity, claude-code, publishing, python, open-source
aliases	bookforge, 북포지

LLM Wiki

탐색기