AI 에이전트에게 "회사 톤"의 다이어그램을 그리게 하는 스킬, diagram-design

출처: Cathryn Lavery (GitHub 저장소 README)
원문: https://github.com/cathrynlavery/diagram-design
작성자: 팔복소프트-김팔복

한눈에 보기

• Claude Code, Codex, Factory Droid, Pi 등 코딩 에이전트에 설치하는 다이어그램 생성 스킬이 GitHub에서 32.2k 스타를 모았다.
• 아키텍처, 시퀀스, ER, 간트, Sankey, DB 스키마 등 39가지 유형을 자체 완결형 HTML+SVG 파일로 만들어 준다. 기본 출력에는 JavaScript도, 외부 이미지도 없다.
• 회사 홈페이지 URL 하나로 배경색·본문색·강조색·폰트를 추출해 모든 다이어그램에 적용하는 브랜드 온보딩이 핵심 기능이다.
• 이미 갖고 있는 draw.io 파일이나 Mermaid 블록을 읽어 같은 내용을 이 디자인 시스템으로 다시 그려 준다. 변환이 아니라 "재작도"다.
• 출력 형식(html/svg/png), 크기(문서/슬라이드/SNS/인쇄), 노드 수, 독자 수준을 다이얼처럼 따로 조절할 수 있다.
• 접근성(WCAG AA 대비, role="img", <title>/<desc>)이 기본 포함되며, 애니메이션은 옵션이고 기본값은 정적이다.
• MIT 라이선스.

배경

Claude Code나 Codex 같은 코딩 에이전트에는 "스킬(Agent Skill)"이라는 확장 방식이 있다. 마크다운으로 작성된 지침·참고 문서·스크립트를 묶어 두면, 에이전트가 관련 요청을 받았을 때만 해당 문서를 읽고 그대로 따른다. 이 저장소는 그 스킬 형식으로 만들어진 다이어그램 전용 지침서다. 에이전트가 "그림을 그리는 도구"를 새로 얻는 것이 아니라, "그림을 이렇게 그려라"는 규칙집을 읽는 구조라는 점을 이해하면 나머지가 쉽게 읽힌다.

주요 내용

무엇을 해결하려는 프로젝트인가

작성자 Cathryn Lavery는 자신의 블로그와 회사(BestSelf.co)를 운영하면서 아키텍처 스케치나 순서도가 필요할 때마다 AI에게 요청했는데, 돌아오는 것은 사이트 분위기와 전혀 맞지 않는 둥근 상자 뭉치였다고 한다. Figma에서 30분을 씨름하거나 그냥 다이어그램을 포기하는 일이 반복되자, 처음부터 편집 디자인 품질을 내도록 지침을 고정한 스킬을 만든 것이 이 프로젝트의 출발점이다.

그래서 이 스킬의 정체성은 "많은 기능"보다 "강한 제약"에 있다. 강조색은 하나, 시선을 끌 요소는 다이어그램당 1~2개, 1px 실선 테두리, 그림자 금지, 모서리 반경 최대 10px, 모든 좌표·너비·간격은 4의 배수. 작성자는 이 4px 그리드가 "AI가 만든 티"를 없애는 결정적 요소라고 설명한다.

"가장 품질을 높이는 조치는 대개 삭제다. 모든 노드는 자기 자리를 증명해야 한다." — Cathryn Lavery, README 중

브랜드 온보딩: URL 하나로 토큰 추출

가장 눈에 띄는 기능이다. "onboard diagram-design to https://우리회사.com"이라고 요청하면 에이전트가 홈페이지를 가져와 주요 팔레트와 폰트 스택을 뽑고, 이를 paper(배경), ink(본문), muted(보조), accent(강조), link 같은 의미 역할에 매핑한 뒤 변경안을 보여 준다. 승인하면 references/style-guide.md에 기록되고 이후 모든 다이어그램이 이 값을 읽는다.

이 과정에서 본문색과 배경색의 WCAG AA 대비를 자동 검사해, 다이어그램 크기(9~12px)에서 기준을 못 넘기면 조정값을 제안한다. 여러 고객사를 상대하는 경우를 위해 브랜드를 이름 붙인 프로필로 저장하고, 프로젝트 폴더에 .diagram-design 마커 파일로 어느 프로필을 쓸지 지정하는 기능도 있다.

또 하나 눈여겨볼 장치가 "첫 실행 게이트"다. 새 프로젝트에서 처음 다이어그램을 만들 때 스타일 가이드가 기본값이면 에이전트가 멈추고 온보딩을 할지, 토큰을 직접 붙여넣을지, 기본값으로 갈지 묻는다. 기본 스킨 그림이 브랜드 프로젝트에 조용히 섞여 들어가는 사고를 막기 위한 설계다.

draw.io / Mermaid 재작도와 네 가지 다이얼

기존 자산을 버리지 않아도 된다는 점이 실무적으로 중요하다. .drawio, .drawio.png, .drawio.svg(압축 페이로드 포함)와 .mmd, 마크다운 안의 mermaid 펜스 블록을 텍스트로만 파싱해(렌더링·네트워크 접근 없음) 구성 요소·관계·그룹·방향만 가져오고, 원본의 좌표·색·폰트·자동 레이아웃은 버린다.

재작도가 끝나면 무엇을 합쳤고, 접었고, 버렸는지 적은 "fidelity ledger"를 함께 출력한다. 원본을 아는 사람이 보면 어차피 눈치챌 테니 먼저 밝히겠다는 태도다.

내보내기와 애니메이션

기본 산출물은 더블클릭으로 열리는 HTML 한 장이지만, /diagram-design:export-diagram 명령으로 SVG(Google Fonts 삽입)나 PNG(Playwright + Chromium, 기본 2배 해상도)로 뽑을 수 있다. 2.3 버전부터는 큐·병목·정책 추적 같은 "행동"을 먼저 고르고 시각 유형을 나중에 고르는 시맨틱 패턴 7종과, reveal·step·loop 모드의 선택적 모션이 추가됐다. 다만 모션은 검토된 단일 컨트롤러만 허용하고 임의 스크립트·외부 리소스·onclick 같은 속성은 린터가 거부한다. 기본값은 여전히 스크립트 없는 정적 출력이다.

기존 도구와의 위치

팔복소프트 관점

• 한국 개발팀에 가장 와닿는 지점은 draw.io 재작도다. 국내 SI·솔루션 현장에서 draw.io로 그린 아키텍처 그림이 제안서와 설계서를 오가며 몇 년씩 살아남는 경우가 많다. 그림을 새로 그리는 것이 아니라 있는 파일을 넣고 "임원 보고용 16:9, 노드 7개 이하"로 뽑아내는 워크플로우는 그 자체로 시간을 아낀다.
• 한글 폰트는 검증이 필요하다. 기본 폰트 세트(Instrument Serif, Geist, Geist Mono)는 한글 글리프가 없다. 한글 라벨은 시스템 폴백 폰트로 렌더링되고, 4px 그리드로 맞춘 글자 폭 계산도 영문 기준이라 어긋날 수 있다. 브랜드 온보딩이 사이트의 body 폰트(국내라면 Pretendard, Noto Sans KR가 흔하다)를 읽어 오긴 하지만, README는 "공개 웹폰트를 직접 쓰고 렌더링 후 검증한다"고만 밝힐 뿐 CJK 지원을 명시하지 않는다. 도입 전 한글 라벨 예제 몇 개로 줄바꿈과 잘림을 직접 확인해야 한다.
• Notion·Confluence 위키 팀은 이점이 애매하다. 이 도구의 산출물은 HTML 파일이다. GitHub README나 정적 블로그처럼 HTML/SVG를 그대로 넣을 수 있는 곳에서는 강점이 크지만, Notion에 붙이려면 결국 PNG로 내보내야 하고, 그러면 Mermaid의 "텍스트로 diff 가능"이라는 장점을 잃는다. 문서 소비 채널이 어디인지가 도입 판단의 첫 기준이다.
• 비용은 토큰이다. 스킬은 요청당 SKILL.md와 유형 참고 문서 하나만 읽도록 설계돼 있어 컨텍스트를 아끼려는 노력이 보이지만, 그래도 다이어그램 하나를 뽑을 때마다 에이전트 세션이 돌아간다. Mermaid 한 줄 고치는 비용과는 차원이 다르다. 자주 바뀌는 그림보다 "한 번 만들어 오래 쓰는" 문서용 그림에 어울린다.
• 보안 관점에서는 오히려 안심되는 편이다. 에이전트가 HTML을 생성한다는 점이 걱정될 수 있지만, 린터가 외부 리소스·@import·인라인 이벤트 속성을 거부하고 import 과정도 텍스트 파싱만 한다. 사내 문서에 붙이기 전 self_check.py를 CI에 넣으면 최소한의 게이트가 된다.
• 아쉬운 점. 39종이라는 숫자에 비해 국내에서 자주 쓰는 "시스템 구성도 + 서버 스펙 표" 같은 표 결합형이나 네트워크 토폴로지 유형은 없다. 아이콘 55종에 AWS·Azure·Kubernetes는 있지만 NCP(네이버클라우드), KT클라우드 같은 국내 클라우드 로고는 당연히 없어서 직접 추가해야 한다.

정리

이 스킬의 본질은 "그림 생성기"가 아니라 "AI에게 강제하는 디자인 규칙집"이다. 그래서 가치는 그림 한 장의 품질보다 수십 장이 같은 톤을 유지한다는 일관성에서 나온다. draw.io 자산이 많고 산출물이 웹이나 슬라이드로 가는 팀이라면 당장 써 볼 만하고, 위키 중심에 한글 라벨이 대부분인 팀이라면 폰트 검증부터 하고 결정하면 된다. 어느 쪽이든 README 말미의 "이 그림이 잘 쓴 문단보다 더 알려 주는가"라는 질문은 도구와 무관하게 새겨둘 만하다.

• Claude Code
• Agent Skills
• 다이어그램
• draw.io
• Mermaid