리포트를 쓸 때 도식을 넣고 싶은데 매번 포기했어요. Mermaid로 그리면 브랜드 톤이 안 맞고 한글이 깨지고, 직접 그리자니 도식 몇 개에 반나절이 날아갔거든요. 그래서 텍스트와 표로만 채운 리포트가 쌓였습니다.
그러다 x.com에서 diagram-design이라는 Claude Code 스킬을 봤어요.
보자마자 유용하겠다 싶었습니다. 저희 내부에도 bbojjak-card라는 도식 스킬이 있긴 한데, 템플릿이 funnel·비교·플로우·계단·변환·노드 여섯 유형으로 정해져 있어요. 카드 한 장짜리 도해에는 좋은데 리포트에 들어갈 아키텍처나 사분면, 잔존 곡선 같은 건 만들 수가 없었습니다. diagram-design은 27가지 타입을 지원하더군요. 아키텍처, 시퀀스, 상태 머신, ER, 타임라인, 스윔레인, 사분면, 레이더, 플라이휠, 트리, 조직도, 벤, 피라미드, 막대·선 그래프, 간트, 산점도까지요.
문제는 영문 기준으로 만들어져 있다는 점이었어요. 폰트도 작고 한글 제목은 회색으로 뭉개졌습니다. 그래서 8일에 걸쳐 여섯 세션, 약 7시간 반 동안 Codex CLI와 함께 이 스킬을 뜯어고쳤어요.
전체 순서는 이랬습니다.
결과부터 말하면, 지금은 도식 4~6개가 들어간 HTML 리포트를 한 세션에 뽑습니다. 리포트가 정말 읽기 수월해졌어요.
문서에 적힌 색과 실제 사이트 색이 달랐어요
발견한 diagram-design 스킬의 설치는 심볼릭 링크로 했습니다. ~/.claude/skills/와 ~/.codex/skills/ 양쪽이 같은 원본 폴더를 가리키게요. Codex가 두 링크의 inode까지 대조해서 진짜 같은 파일인지 확인해 줬어요. 이 구조 덕분에 이후 8일 동안 한 곳만 고치면 Claude Code와 Codex 양쪽에 동시 반영됐습니다. 이걸 안 했으면 매번 두 번씩 고쳤을 거예요.
그다음이 브랜드 온보딩이었어요. 스킬에서 제공하는 기능인데, 도식화 하는 것을 브랜드의 디자인 시스템에 맞게 해주는 첫 설정을 하는 절차입니다.
이제 diagram-design을 온보딩해줘. 우리 사이트에 맞게
웹사이트: https://www.gpters.org/
디자인 시스템은 aitk의 /setup-design 이라는 스킬을 살펴보면 더 디자인 세부 사항이 있어.여기서 예상 못 한 게 나왔습니다. Codex가 정적 HTML만으로는 실제 렌더링 색을 알 수 없다면서 인앱 브라우저로 렌더된 CSS를 직접 열어봤는데, 문서와 실물이 어긋나 있었어요.
문서 값 vs 실제 운영 사이트
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
항목 문서 값 실제 사이트 채택
━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Primary/action/link #EF6020 #EB5A10 #EB5A10
간격 체계 8px 4px 4px문서만 믿었으면 미묘하게 다른 오렌지로 도식을 8일 내내 뽑았을 겁니다. 간격도 문서에는 8px이라고 적혀 있는데 최신 토큰 파일은 4px로 바뀌어 있었고, 이 4px이 diagram-design의 그리드와 마침 일치했어요.
적용 전에 변경안을 먼저 보여주더군요. 승인하고 나서 한 가지가 궁금해 물어봤습니다.
그렇게 해줘. 그리고 그렇게 했을때 전역 유저에게 영향을 주는지,
코덱스 말고 클로드 코드에는 영향을 주는지도 확인해줘답이 명확했어요. 이 Mac의 모든 프로젝트에는 영향이 있고(심볼릭 링크 원본이니까), 다른 사람에게는 영향이 없고, Claude Code는 같은 원본을 보므로 똑같이 반영됩니다. 기존 예제 파일과 GPTers 사이트 자체는 그대로예요.
"이쁜데 글씨가 너무 작아요"
온보딩 결과를 테스트하려고 도식 하나를 만들어 달라고 했습니다. 방금 진행한 온보딩 과정 자체를 8개 노드 플로우차트로 그려줬는데, 보자마자 걸리는 게 있었어요.
다이어그램이 이쁘고 좋은데, 폰트 사이즈가 다이어그램 사이즈에 비해서 너무 작아서
작게 줄여서 어디에 넣기가 어려워.
이런 폰트 사이즈를 키우는 방법이 diagram-design 자체에서 제공되는 것이 있을까?스 킬 문서를 다 뒤진 결과 그런 프리셋은 없었습니다. 그럼 기본 폰트를 키우면 될까 싶었는데, Codex가 그건 위험하다고 했어요. 기본값을 건드리면 기존 결과물이 전부 깨지니까요. 대신 선택형 embed / large-text 변형을 따로 추가하는 쪽을 제안했습니다.
구현 방식이 마음에 들었어요. SKILL.md에는 자동 선택 조건만 몇 줄 넣고, 상세 규칙은 별도 참조 파일로, 뼈대는 템플릿 파일로, 검증용 예시는 또 따로 뒀습니다. 본문이 비대해지지 않게 나눈 거죠. 목표 폭을 안 주면 520px을 기본으로 쓰고, 640px 이하거나 "작은 카드 / Notion / 썸네일 / 슬라이드 일부"를 언급할 때만 이 변형이 걸립니다. 기본 변형은 손대지 않았어요.
이 단계에서 한 번 헛돌았습니다. 520px 캡처에서 제목 줄바꿈이 이상하게 나왔는데, DOM을 재보니 폭은 정확히 520px이고 SVG 크기도 정상이었어요. 웹폰트 로딩 타이밍 문제였고, 로딩 완료를 기다린 뒤 다시 캡처하니 정상이었습니다. 템플릿 문제가 아니라는 걸 수치로 확인한 뒤에야 넘어갔어요.
서브에이전트가 PASS를 안 줬어요
이제 진짜 되는지 봐야 했습니다.
실제 테스트를 해보자.
원래의 작은 폰트, 수정한 큰 폰드 비교할 수 있는 다이어그램을
27개 타입 중에서 3-4 만들어서 제대로 되는지 확인해줘. 검수는 서브에이전트가 하도록 해줘.Codex가 고른 4종이 영리했어요. Flowchart(분기 라벨), Architecture(기술 서브라벨), Quadrant(축·항목 라벨), Timeline(날짜·이벤트 라벨). 각각 다른 종류의 "작은 글씨 문제"를 드러내는 타입들입니다. 같은 문제만 네 번 확인하면 의미가 없으니까요.
본인 검수에서는 4종 다 통과했다고 했어요. 그런데 서브에이전트에게 넘기니 실제 위반을 세 건 잡아냈습니다.
서브에이전트가 잡아낸 위반
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 지적 조치
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1 390px급 화면에서 640 뷰박스가 너무 작아짐 임베드 뷰박스를 560px로
2 사분면 축 이름이 타입 규칙 위반 문법 수정
3 타임라인 날짜 위치가 타입 규칙 위반 문법 수정검수를 다른 에이전트에게 맡기라고 한 게 제일 값싸게 얻은 이득이었어요. 만든 쪽은 자기가 만든 걸 통과시키는 경향이 있습니다.
겹침 문제 — 폰트만 줄이면 안 됩니다
며칠 뒤 스크린샷을 하나 붙여서 물었습니다.
플로차트 1번을 보면 "문서로 유지"하는 노드와 "사례를 한 번 작성" 노드가 겹쳐져 있어.
이런 경우 폰트 크기를 줄이고 노드 크기를 줄여서 겹치지 않게 하는
그것을 보장할 수 있게 하는 그런 방안은 없을까?Codex는 먼저 제 스크린샷이 한 버전 이전 파일이라고 짚었어요. 지표가 18.5px / 14.8px인데 현재 파일은 14.8px / 11.1px이고 그 두 노드는 이미 떨어져 있다고요. 그러면서도 지적 자체는 맞다고 했습니다. 사람 눈으로만 확인하면 언제든 재발하니까, 스킬에 최소 간격 규칙과 자동 충돌 검사를 넣는 편이 확실하다는 거였어요.
제가 방법을 하나 던졌습니다.
이전 버전처럼 노드 20px 로 하되, 겹치는 노드가 생기면
더 작은 폰트로 바꾸는 과정을 반복하는 그런 식으로 구현하면 어떨까 하는데?여기서 제 생각이 틀렸다고 정정해 줬어요. 폰트만 반복해서 줄여도 SVG 박스 크기는 고정이라 충돌이 그대로 남는다는 거였습니다. 그래서 이런 경로가 나왔어요.
핵심은 세 가지입니다. 폰트와 노드 크기를 함께 재계산할 것, 무한 반복 대신 읽기 하한을 둘 것, 하한에 닿으면 폰트 대신 배치를 바꿀 것.
자동 충돌 검사기를 만들 때도 그냥 만들고 끝내지 않았어요. 제가 붙인 스크린샷과 같은 겹침을 의도적으로 실패시키고, 수정된 레이아웃은 통 과하는지를 확인했습니다. 검사기 자체를 검사한 셈이죠.
한글 제목이 가냘픈 진짜 이유
리포트를 실제로 뽑아 보니 섹션 제목이 회색으로 뭉개졌어요. 원인을 찾는 데 시간이 걸렸는데, 알고 보니 스킬이 지정한 폰트 세 종이 전부 라틴 전용이었습니다. 한글 글리프가 아예 없었어요.
지정 폰트와 한글 렌더 결과
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
역할 지정 폰트 한글이 실제로 어떻게 렌더되나
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
제목 Instrument Serif 제네릭 serif → macOS AppleMyungjo
큰 제목에서 획이 가늘고 자간이 벌어져 뭉갬
본문 Geist system-ui → Apple SD Gothic Neo
읽히긴 하지만 의도한 타이포가 아님
고정폭 Geist Mono ui-monospace → 자간·자폭이 깨짐핵심은 브라우저가 글리프 단위로 폴백한다는 점이었습니다. 한 줄 안에서 라틴과 한글이 서로 다른 폰트로 렌더되는 거예요.
위쪽이 수정 전입니다. "AI"는 Instrument Serif로, "시대의 제품 찾기"는 시스템 명조로 렌더돼요. 두 폰트의 굵기가 다르니 한 줄 안에서 무게가 어긋납니다. 그게 "가냘프다"의 정체였어요.
이건 저 혼자서는 못 찾았을 거예요. "한글이 좀 흐리네" 하고 폰트를 통째로 바꿨다가 라틴 쪽 디자인을 망쳤겠죠.
해결책도 반직관적이었습니다. 후보 다섯 종을 실제로 렌더해 비교한 뒤 Noto Serif KR weight 600을 골랐는데, 제목의 font-weight는 400 그대로 뒀어요.
Instrument Serif는 weight가 400 하나뿐인 폰트입 니다. 제목을 600으로 올리면 라틴에 합성 볼드가 걸려서 큰 사이즈에서 획이 뭉개져요. 그래서 CSS 쪽은 400으로 두고 Noto Serif KR만 600 파일 하나를 로드했습니다. 그러면 브라우저가 라틴에는 원본 400을, 한글에는 실제로 디자인된 600을 씁니다. 합성 없이요.
작업 도중에 함정이 하나 더 나왔어요. 폰트 선언이 템플릿 다섯 개에만 있는 게 아니라 예제 HTML 95개에도 복제돼 있었습니다. 템플릿만 고치면 옛 예제를 보고 만든 다음 결과물이 다시 깨지죠. 총 97개 파일을 일괄 치환하고 대표 샘플만 렌더해서 확인했어요.
검증 방식도 마음에 들었습니다. 영문 예시 하나를 수정 전후로 PNG 해시까지 비교해서 완전히 같음을 확인했어요. 한글은 고쳤고 라틴은 1px도 안 건드렸다는 증거입니다.
그리고 큰 폰트를 기본값으로
마지막으로 순서를 뒤집었어요.
큰 폰트를 기본으로 하고 명시적 요구가 있을때 혹은 다이어그램이 복잡해서
노드가 많을 때만 작은 폰트로 하는 걸로 하자.20/16px이 기본이 되고, 16/12px은 제가 작게 요청하거나 노드가 7~9개인 복잡한 도식일 때만 쓰입니다. 노드 6개 이하에서 겹치면 폰트를 줄이지 말고 배치와 캔버스를 먼저 조정하도록 규칙을 박았어요.
AITK에 배포하는 과정에서도 세 번 막혔습니다. AITK는 AI-Toolkit 약자로 지니파이 회사 내에서 스킬을 함께 공유하는 시스템입니다.
배포 중 만난 에러 3건
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
에러 원인 해결
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
HTTP 400 서버는 changelog를 요구하는데 배포 API를 직접 호출해
CLI가 그 필드를 안 보냄 변경 사유 포함
HTTP 413 HTML 갤러리 일괄 업로드가 수정 대상 파일만
용량 제한 초과 분리 업로드
껍데기 원격 원본을 부르는 경량 라우터만 본문·템플릿·검사기를
배포본 올라가 있었음 함께 올려 의존 제거최종적으로 AITK 1.2.10이 claude_code와 codex 양 플랫폼으로 올라갔고, 첨부 파일 45개까지 붙었어요. 로컬 두 경로의 파일 해시도 대조해서 같은 걸 보고 있는지 확인했습니다.
이렇게 만든 리포트들
고쳐 놓고 나서 실제 리포트에 써봤어요. 몇 장만 보여드릴게요.
사분면 타입입니다. 축 라벨, 사분면 이름, 각 칸의 서브텍스트가 전부 다른 크기로 들어가는데 겹침 없이 정리됐어요. 강조는 오른쪽 위 한 칸에만 걸립니다.
같은 리포트의 피라미드 타입입니다. 5층 사다리꼴이 정확히 맞물리고 층마다 제목·부제 두 줄이 들어가요.
이쪽은 플라이휠(루프) 타입이에요. 원형 배치에 실선·점선 두 종류의 연결이 섞이고, 가운데 검은 블록이 누적 자산을 표현합니다. 이런 건 Mermaid로는 못 그려요.
세 장의 타입이 전부 다릅니다. 사분면, 피라미드, 루프. 이게 27종을 지원한다는 말의 실질이에요. 그리고 세 장 모두 같은 색·같은 폰트·같은 간격 체계를 씁니다. 스킬 하나에 브랜드를 한 번 먹여 놓으면 그다음부터는 알아서 나와요.
결과
Before / After
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
항목 Before After
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
리포트 도식 톤이 안 맞아 포기 인라인 SVG 4~6개가 들어간
→ 텍스트와 표로만 HTML 리포트
도식 종류 내부 스킬 6유형 27유형 (사분면·피라미드·
(카드형 도해) 루프·간트·산점도 등)
한글 제목 시스템 명조로 폴백돼 라틴은 원본 400,
회색으로 뭉갬 한글은 Noto Serif KR 600
노드 글씨 축소 삽입하면 못 읽음 기본 20/16px, 겹칠 때만
자동으로 16/12px
겹침 확인 눈으로 보고 그때그때 수정 자동 충돌 검사 후 재배치까지
도구 간 일관성 — Claude Code·Codex 어느
쪽에서 불러도 같은 결과수치보다 체감이 컸어요. 리포트가 정말 읽기 수월해졌습니다. 긴 설명 세 문단으로 버티던 자리에 도식 한 장이 들어가니, 저도 다시 읽을 때 훨씬 편해요.
8일 걸렸지만 실제 작업 시간은 약 7시간 반이었습니다. 하루에 30분씩 붙어 있던 날도 있고, 4시간 몰아친 날도 있었어요.
직접 써보실 분들께
고친 버전을 GitHub에 올려뒀습니다. MIT 라이선스라 누구나 받아서 쓰실 수 있어요.
원본은 cathrynlavery/diagram-design이고, 이 포크에는 한글 폰트 폴백, 20/16px 큰 글꼴 기본, 노드 충돌 자동 검사, Embed 변형이 더해져 있습니다. 브랜드 색은 GPTers 기준으로 맞춰져 있으니 온보딩을 다시 돌려서 각자 브랜드로 바꾸시면 돼요.
설치는 심볼릭 링크 한 줄입니다. Claude Code와 Codex 양쪽 다 되고요.
git clone https://github.com/livekthgpters/diagram-design.git ~/dev/diagram-design
ln -s ~/dev/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design
ln -s ~/dev/diagram-design/skills/diagram-design ~/.codex/skills/diagram-design지피터스 멤버라면 AITK에서 diagram-design으로 바로 받으실 수도 있어요.
AI 활용 팁!
심볼릭 링크를 먼저 걸어두세요. 이게 제일 값싼 이득이었어요. ~/.claude/skills/와 ~/.codex/skills/가 같은 원본을 가리키게 해두면 8일 동안 한 번만 고치면 됩니다. 스킬을 여러 도구에서 쓸 계획이면 첫날에 하세요.
검수는 다른 에이전트에게 맡기세요. 만든 에이전트는 자기 결과물에 관대합니다. 서브에이전트가 잡아낸 세 건은 본인 검수에서 다 통과했던 항목이었어요.
"확인했어"를 못 믿을 때는 검증 방법을 지정하세요. 코드만 보고 완료 보고하지 말고 실제로 렌더해서 스크린샷 남기라고 요구하면 결과가 달라집니다. 저는 "수정 전후 PNG 해시 비교"까지 받았어요.
폰트가 흐리면 폰트를 바꾸기 전에 원인을 물어보세요. 저는 "한글이 흐리다"에서 시작했는데 진짜 원인은 글리프 단위 폴백이었습니다. 원인을 모르고 폰트를 통째로 갈면 잘 되던 부분까지 망가져요.
이 방식은 다이어그램 말고도 씁니다. 브랜드 톤이 있는 사내 문서 템플릿, 슬라이드 스킨, 이메일 템플릿처럼 "남이 만든 걸 우리 것으로 맞춰야 하는" 작업 전부에 같은 순서가 통해요. 다만 전제가 하나 있습니다. 결과물을 실제로 렌더해서 볼 수 있어야 해요. 눈으로 확인할 수 없는 결과물이면 이 방식의 절반이 안 돌아갑니다.
바로 쓸 수 있는 프롬프트
[스킬 이름] 스킬을 우리 브랜드에 맞게 온보딩해줘.
웹사이트: [우리 사이트 URL]
디자인 시스템 참고: [디자인 문서나 스킬 경로]진행 조건:
1. 문서에 적힌 값과 실제 사이트에 렌더된 값이 다를 수 있으니, 브라우저로 실제 CSS를 확인해서 교차검증해줘. 다르면 실물을 우선하고 차이를 표로 보여줘.
2. 적용 전에 변경안을 먼저 보여주고 내 승인을 받아.
3. 이 변경이 영향을 주는 범위를 구분해서 알려줘 — 내 모든 프로젝트 / 다른 사용자 / 다른 AI 도구.
4. 적용 후 결과물 1개를 실제로 만들어서 렌더링 스크린샷으로 검증해줘. 코드만 보고 완료 보고하지 마.
5. 검수는 별도 서브에이전트가 독립적으로 하게 해줘. 네가 놓친 규칙 위반을 찾도록.
[대괄호] 부분을 본인 상황에 맞게 바꾸세요. 4번과 5번을 빼면 결과 품질이 확 실히 떨어집니다.
