doc-figure

제안서·공문서·사업기획안에 넣을 삽도를 스타일 고정 그림으로 만드는 Claude Code 스킬 — 한글이 깨지지 않는다. API 키도, 설치도 필요 없다.

Korean-first figure generator for government/business documents: code-rendered diagrams where Hangul labels, numbers, and grid alignment are exact by construction. No API key, no install.

English README · MIT License

---

왜 만들었나

문서에 넣을 조직도 하나를 이미지 모델에 시키면 이렇게 돌아온다.

• 한글 라벨이 한글처럼 생긴 무의미한 획이 된다
• "48억원"이 "4B억윈"이 된다
• 부문 4개를 요구했는데 3개나 5개가 나온다
• 표의 행·열이 어긋난다

고쳐 달라고 다시 시켜도 다른 데가 깨진다. 확산모델의 구조적 한계라서 프롬프트로는 못 넘는다.

doc-figure는 반대로 간다. 글자·수치·정렬은 전부 코드가 그린다. 텍스트는 사양(spec)에 쓴 원문 그대로 DOM에 놓이므로, 글자가 깨지는 일이 구조적으로 불가능하다.

30초 시작 — 설치 없음

git clone https://github.com/parkjui92/doc-figure.git

Claude Code에서:

doc-figure/ 폴더 참고해서 추진체계도 그려줘. 총괄은 정책기획관, 부문은 조사분석·제도개선·성과관리 3개, 자문위원회 붙여줘.

브라우저로 열리는 HTML 한 장이 나온다. 인쇄(PDF)하거나 캡처해서 문서에 넣으면 된다.

크롬과 파이썬이 있으면 PNG를 자동으로 뽑을 수도 있다.

cd doc-figure
python3 scripts/render_figure.py examples/org-chart.json -o 그림_01.png --verify

[doc-figure] ✓ 그림_01.png  (2932x937)  template=org-chart  preset=gov-navy
[verify] ✓ spec 텍스트 20건 전부 DOM에 실재 (글자 깨짐 0)

템플릿 11종

timeline-gantt — 일정·간트	timeline-tracks — 다중 트랙 연표
flow-process — 단계 프로세스	decision-flow — 판정 게이트 + 탈락 분기
org-chart — 추진체계·조직	structure-block — 계층 구성도
layer-stack — 상·하 2단 스택	concept-argument — 논증 도해
comparison-matrix — 비교표	matrix-heatmap — 3단 판정 히트맵
pipe-mapping — 레인–세그먼트 병목 매핑

각 그림의 사양은 examples/에 JSON으로 들어 있다. 그대로 고쳐 쓰면 된다.

프리셋 3벌

문서 종류에 따라 옷을 갈아입는다. 템플릿은 그대로, 색·모서리·그림자만 바뀐다.

gov-navy — 제안서·연구보고서
mono-formal — 공문서·내부 보고 흑백 인쇄·팩스를 거쳐도 3단 판정이 구분되도록 명도 차만으로 위계를 만든다
accent-plan — 사업기획안·민간 제안 강조색이 붉은 경고가 아니라 따뜻한 주황이다. 기획안에서 강조는 문제 지적이 아니라 핵심 제안이기 때문

python3 scripts/render_figure.py examples/matrix-heatmap.json --preset mono-formal -o out.png

스킬로 설치하기

SKILL.md가 들어 있어 Claude Code 스킬로 바로 쓸 수 있다.

git clone https://github.com/parkjui92/doc-figure.git ~/.claude/skills/doc-figure

이후 "삽도 그려줘", "추진체계도", "이 보고서에 넣을 그림 만들어줘" 같은 요청에 자동으로 걸린다.

문서를 통째로 주면 어디에 어떤 그림이 필요한지 먼저 짚어 제안하고, 승인한 것만 그린다.

검증

레포가 약속한 것을 실제로 지키는지 스스로 검사한다.

bash scripts/selftest.sh

── ① 프리셋 토큰 정합 ──      38개 토큰 × 프리셋 3벌 · 이름 집합 일치
── ② 템플릿 하드코딩 색 ──    프리셋을 빠져나가는 색 없음
── ③ 설치 0 경로 ──           자기완결 HTML 생성 (외부 요청 0)
── ④ 예시 스키마 ──           예시 11건 · 템플릿 11종 · 프리셋 3벌
── ⑤ 렌더 + 텍스트 검증 ──    11종 전부 글자 깨짐 0
  통과 15 · 실패 0

--verify는 spec의 모든 텍스트가 렌더 결과에 실재하는지 대조한다.

다만 --verify 통과가 "그림이 멀쩡하다"는 뜻은 아니다. 텍스트의 존재만 보므로 라벨끼리 겹치거나 캔버스 밖으로 밀린 것은 잡지 못한다. 결과는 반드시 눈으로 확인한다. (이 저장소를 만드는 동안 실제로 그런 사례가 나왔고, 그래서 pipe-mapping에 라벨 단 분리 기능이 들어갔다.)

필요한 것

기본 경로 (HTML)	없음. 브라우저만 있으면 된다
정밀 경로 (PNG)	크롬 + 파이썬 3. pillow가 있으면 여백을 자동으로 잘라낸다 (없어도 렌더는 된다)
외부 API	없음. 키를 요구하지 않는다

크롬 경로가 다르면 export CHROME_BIN="/path/to/chrome".

하지 않는 일

• 본문 표 조판 — 표는 문서 편집기가 그린다. 이 저장소는 도식 이미지 전용이다
• 사진풍 자유 일러스트 — 이미지 모델용 프롬프트 규격까지만 제공한다 (references/image-prompt-spec.md)
• 범용 차트 라이브러리 대체 — 산점도·회귀선이 필요하면 matplotlib을 쓴다

문서

템플릿 스키마 11종	필드 명세와 함정
문서 유형 매핑	어떤 문서에 무엇을 몇 장
프리셋 사양	토큰 38개, 새 프리셋 만들기
이미지 프롬프트 규격	자유형 삽화가 필요할 때
설치·확장	템플릿 추가하기

라이선스

MIT. 자유롭게 쓰고 고치고 재배포해도 된다.