Claude Code 다이어그램 스킬 diagram-design, 한글 라벨에서 먼저 부딪히는 5가지

Claude Code 다이어그램 스킬 diagram-design, 한글 라벨에서 먼저 부딪히는 5가지

cathrynlavery/diagram-design은 Claude Code와 Codex, Pi에서 함께 쓰는 다이어그램 스킬이에요. 편집 디자인 규율로 27종을 그려주지만, 한글 라벨은 기본 폰트에 글리프가 없어 시스템 폰트로 대체됩니다.

결론부터 말하면, 이 스킬은 "예쁜 다이어그램 생성기"보다 "브랜드 색과 폰트를 강제하는 작도 규율"에 가깝죠. 그래서 한국어 문서에 붙이는 순간 폰트라는 관문이 먼저 나타나요.

"우리 팀 문서에도 그냥 붙이면 되나요?" 트렌딩 1위 소식을 본 분들이 가장 먼저 던지는 질문이죠. 당연한 걱정이에요. 도입 비용이 명령어 두 줄이라도, 결과물이 우리 문서 톤과 어긋나면 결국 손으로 다시 고치게 되니까요.

오늘은 이 스킬이 실제로 하는 일, 확산 숫자의 실체, 문서마다 다른 종류 표기, 한국어 환경에서 걸리는 지점, 그리고 Mermaid나 D2 사이에서 어디에 놓을지를 순서대로 짚어볼게요.

Mermaid를 버리는 도구가 아니라, 다시 그려주는 도구

가장 흔한 오해부터 정리할게요. 이 스킬은 Mermaid를 대체하지 않아요. /diagram-design:import-mermaid와 /diagram-design:import-drawio 명령으로 기존 Mermaid와 draw.io 원본을 입력으로 받아 자기 디자인 시스템으로 다시 그립니다(저장소 README).

Mermaid를 버리는 도구가 아니라, 다시 그려주는 도구

이미지 출처: github.com

즉 이미 쌓아둔 Mermaid 자산을 버릴 이유가 없어요. 저장소에는 남기고, 발표 자료나 웹 게시물처럼 보기 좋아야 하는 자리에만 재작도해서 쓰는 방식이죠.

설치도 Claude Code에만 묶여 있지 않아요. Claude Code, Codex, Pi 세 에이전트가 같은 스킬 파일을 공유하는 표준 Agent Skill 패키지예요.

# Claude Code
/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design

재작도할 때 조절하는 값은 네 가지예요. 특히 Detail 다이얼은 원본이 얼마나 살아남는지를 직접 정하죠.

import이 끝나면 무엇이 병합되고 삭제됐는지 적은 기록(fidelity ledger)이 함께 나와요. 12 source nodes → 8 drawn 같은 식이죠. 이 기록을 확인하는 습관이 뒤에서 말할 사실 검증과 직결됩니다.

하루 스타 2,855개, 그리고 같은 시기에 몰린 인접 프로젝트

확산 속도는 실제로 가팔랐어요. 2026-08-13 08:47 UTC 기준 GitHub 일간 트렌딩에서 전체 언어 1위였고, 그날 받은 스타는 2,855개였습니다. 2위 저장소(227개)의 약 12.6배죠.

트렌딩 1위의 의미: 하루 동안 새로 받은 스타 수가 전체 언어 저장소 중 가장 많다는 뜻입니다. 누적 인지도가 아니라 그날의 유입 속도를 보여주는 지표이고, 며칠 단위로 순위가 바뀝니다.

흥미로운 건 이 급등이 혼자 일어난 사건이 아니라는 점이에요. 같은 문제의식을 가진 프로젝트가 최근 열흘 사이 Hacker News에 연달아 올라왔거든요. 아래는 각 스레드가 받은 점수(points)입니다.

여러 팀이 비슷한 시기에 같은 불만을 건드렸다는 신호죠. "Mermaid 결과물이 못생겼고 배치를 잡을 수 없다"는 이야기가 임계점을 넘은 겁니다.

다만 한 가지는 분명히 해둘게요. Hacker News에 diagram-design 저장소 자체를 다룬 스레드는 0건이고, 소개는 주로 X와 뉴스레터를 타고 퍼졌어요. 일본어권 소개 게시물(@L_go_mrk, 2026-08-07)이 좋아요 532개, 댓글 8개를 받은 정도가 관측된 규모예요. Reddit 반응은 이번 조사 환경에서 수집에 실패해 확인하지 못했고요. 지금은 깊은 기술 토론보다 "예쁘다, 바로 쓰겠다"는 초기 반응 국면으로 보는 게 정확해요.

27종인가 29종인가, 저장소 안의 숫자부터 맞춰보기

인용하기 전에 반드시 확인할 지점이에요. 종류 개수가 문서마다 다르게 적혀 있거든요.

정확한 표현은 27종입니다. 소개문에만 29로 남아 있어요. 빠르게 커지는 프로젝트에서 흔한 증상이고, 인용할 때는 원문에서 다시 세어보는 편이 안전하죠.

27종은 구조와 설계(architecture, layers, tree 등), 흐름과 동작(flowchart, sequence, swimlane 등), 데이터 모델(er, medallion 등), 비교와 포지셔닝(quadrant, venn, radar 등), 시간축(timeline, gantt), 차트(bar, line, scatter), 특수 타입으로 나뉘어요. 여기에 부품 4종(주석, 손그림 필터, 터미널 창, 단색 아이콘 55종)이 별도로 붙고, 각 타입은 밝은 최소본과 어두운 최소본, 전체 편집본 3가지 변형으로 제공되죠.

저장소 안 파일 구성도 성격을 잘 보여줘요. 문서보다 예제 HTML이 많은 구조입니다.

설계의 핵심은 점진적 공개예요. 에이전트가 처음엔 스킬 설명만 보고, 요청이 맞으면 SKILL.md(37,408바이트)를 읽고, 그다음 필요한 타입 파일 하나만 더 읽죠. 타입이 늘어도 한 번에 읽는 양은 그대로라는 뜻입니다. 예제 HTML 한 개의 크기는 중앙값 11KB 수준이라 다이어그램 하나가 이메일 첨부만큼 가벼운 셈이고요.

한글 라벨에서 먼저 부딪히는 5가지

여기가 국내 실무의 핵심이에요. 템플릿이 불러오는 폰트는 Instrument Serif, Geist, Geist Mono 셋뿐인데, Google Fonts 서브셋을 직접 조회해 보니 한글 영역(U+AC00)이 하나도 없었습니다.

결과가 어떻게 될까요. 한글 라벨은 시스템 기본 폰트로 대체 렌더돼요. 라틴 문자는 Geist, 한글은 macOS면 Apple SD Gothic Neo, Windows면 맑은 고딕으로 섞여 나오죠. 이 스킬이 내세우는 폰트 3종 고정 규율이 한글 구간에서만 깨지고, 보는 사람의 운영체제에 따라 결과가 달라집니다.

한국어 문서에 붙일 때 순서대로 부딪히는 지점을 정리하면 이래요.

1. 폰트 교체가 첫 단계예요. references/style-guide.md의 폰트 토큰을 Pretendard나 Noto Sans KR로 바꾸고, 템플릿의 Google Fonts 링크도 함께 손봐야 하죠. 홈페이지 색을 자동으로 읽어오는 브랜드 온보딩만으로는 템플릿 기본값이 바뀌지 않아요.
2. PNG 내보내기에 별도 설치가 필요합니다. Playwright와 Chromium을 따로 깔아야 하고, 수백 MB짜리라 가벼운 환경에서는 부담이 되죠.
3. 완전한 오프라인은 아니에요. README도 "Google Fonts를 제외하면 네트워크 요청 없음"이라 적어 뒀습니다. 폐쇄망 발표라면 폰트를 로컬로 임베드해야 하고요.
4. 버전 이력은 남지만 변경 내역은 읽기 어려워요. HTML 파일이라 git에 들어가는 건 장점인데, 인라인 SVG 좌표가 통째로 바뀌어서 diff를 사람이 읽기는 사실상 어렵죠. Mermaid 텍스트의 "한 줄 바꾸면 한 줄 변경" 장점은 포기하는 셈입니다.
5. 직접 손본 스타일은 덮어써질 수 있어요. style-guide.md를 수정할 계획이면 저장소를 복제해 심링크로 연결하는 편집형 설치가 안전합니다. README가 직접 경고하는 부분이에요.

검증 게이트는 기하를 보지, 사실을 보지 않는다

이 저장소가 흔한 프롬프트 모음과 다른 지점은 검사 장치죠. CI가 Linux, Windows, macOS 세 환경에서 돌고, 확정된 설계 결정은 별도 기록 5건으로 남아 있어요.

다만 경계가 있어요. 이 게이트들은 기하와 접근성, 안전성을 봐요. 라벨 내용이 사실인지는 검사하지 않습니다. Audience 다이얼을 executive로 올리면 Auth Service / JWT · RS256 · :8443이 Sign-in으로 줄어드는데, 기술 문서에서는 이 축약이 사실을 뭉갤 수 있죠.

그래서 실무 규칙은 단순해요. 대외 발행물이라면 다이어그램 라벨도 본문 수치와 대조하는 팩트체크 대상으로 다루고, fidelity ledger에서 무엇이 삭제되고 병합됐는지 확인하는 것. 도구가 검증해 주는 범위와 사람이 봐야 하는 범위를 나눠 두면 "AI가 틀린 걸 만들면 어쩌나" 하는 불안이 관리 가능한 절차로 바뀌죠.

Mermaid, D2, draw.io 사이에서 어디에 놓을까

경쟁 축을 착각하면 도입 판단이 어긋나요. 배치 알고리즘 경쟁이 아니라 발행물 품질 경쟁이거든요.

Mermaid, D2, draw.io 사이에서 어디에 놓을까

이미지 출처: github.com

Mermaid의 한계는 취향 문제가 아닙니다. 영국 정부 디지털서비스가 Mermaid 채택 전 남긴 아키텍처 결정 기록은 노드 자동 배치를 제어할 수 없다는 점, 연결선이 박스 뒤로 숨거나 겹친다는 점을 명시했어요. 여기에 격리된 렌더링 영역 때문에 외부 CSS로 스타일을 덮어쓰기 어렵다는 구조적 제약이 더해지고요.

그러니 판단 기준은 이렇게 잡으면 돼요. 저장소 안에서 개발자끼리 보는 도식이면 Mermaid로 충분하고, 제안서와 발표 자료, 블로그처럼 우리 브랜드 톤이 걸리는 자리에만 재작도를 붙이는 것. 두 도구를 놓고 고르는 게 아니라 역할을 나누는 문제죠.

마무리

정리하면 diagram-design은 Claude Code와 Codex, Pi에서 쓰는 다이어그램 작도 규율이에요. 27종을 지원하고(소개문 표기는 29), Mermaid와 draw.io 원본을 입력으로 받아 브랜드 색과 폰트에 맞춰 다시 그립니다. 2026-08-13 08:47 UTC 기준 하루 스타 2,855개로 GitHub 일간 트렌딩 1위에 올랐고, 같은 시기 인접 프로젝트가 여럿 등장할 만큼 수요가 확인된 영역이죠.

국내 팀이라면 순서가 하나 더 붙어요. 폰트 토큰을 Pretendard 계열로 바꾸는 작업을 첫 단계로 두는 것. 이걸 건너뛰면 라틴 문자와 한글이 다른 폰트로 섞여 나오고, 보는 사람 환경에 따라 결과가 달라집니다.

천천히 검토하셔도 됩니다. 궁금한 지점이 생기면 그때 원문 저장소에서 해당 숫자를 다시 확인해 보세요.

자주 묻는 질문 (FAQ)

Q: Claude Code가 아니라 Codex를 쓰는데 그대로 설치되나요?

네, 같은 스킬 파일을 Claude Code와 Codex, Pi가 공유하는 구조라 각 도구의 플러그인 명령으로 설치할 수 있어요. Claude Cowork는 조직 마켓플레이스 미러링이 따로 필요합니다.

Q: 한글 라벨을 쓰려면 무엇부터 바꿔야 하나요?

references/style-guide.md의 폰트 토큰을 Pretendard나 Noto Sans KR로 교체하고, 템플릿의 Google Fonts 링크도 같이 바꿔야 해요. 기본 폰트 3종에는 한글 글리프가 없어서 그대로 쓰면 시스템 폰트로 대체 렌더됩니다.

Q: 기존 Mermaid 문서를 전부 옮겨야 하나요?

옮길 필요는 없어요. import 명령이 Mermaid 원본을 입력으로 받아 다시 그리는 방식이라, 저장소 안 도식은 Mermaid로 두고 발표 자료나 웹 게시물처럼 보기 좋아야 하는 자리에만 재작도해서 쓰면 됩니다.

참고 자료

• cathrynlavery/diagram-design 저장소
• diagram-design 라이브 갤러리
• GitHub 일간 트렌딩
• Google Fonts Geist 서브셋 응답
• GOV.UK 아키텍처 결정 기록 ADR-006 (Mermaid 한계)
• Show HN: Line9 (Mermaid 렌더링 엔진)
• D2 공식 저장소