[심층분석] Figma 없이 60초, '디자이너도 만족할' 다이어그램 — Claude Code 스킬 diagram-design 뜯어보기

들어가며: 우리 모두의 '다이어그램 스트레스'

기술 문서나 블로그 글을 쓰다 보면 꼭 한 번은 마주치는 순간이 있어요. '아, 여기 아키텍처 다이어그램 하나 있으면 딱인데...' 하는 순간이요. 그런데 막상 그리려고 하면 선택지가 다 애매하거든요. Figma를 열자니 박스 정렬하고 색 고르다가 30분이 훌쩍 가고, Mermaid로 뽑자니 결과물이 어딘가 밋밋한 회색 둥근 박스 뭉치라서 글 분위기와 따로 놀고요. 그래서 결국 '그냥 다이어그램 빼자'가 되는 경우, 다들 한 번쯤 있으시죠?

오늘 소개할 diagram-design은 바로 이 문제를 정면으로 겨냥한 오픈소스 프로젝트예요. 만든 사람인 Cathryn Lavery는 littlemight.com이라는 블로그를 운영하는데, 글 쓸 때마다 Claude에게 다이어그램을 부탁하면 '어디서 본 듯한 둥근 박스'만 돌아와서 결국 직접 만들었다고 해요. 저장소 설명에 붙은 'No Mermaid-slop'이라는 문구가 인상적인데요, slop은 요즘 AI가 대충 찍어낸 성의 없는 결과물을 부르는 말이에요. 그러니까 'Mermaid스러운 밋밋한 다이어그램은 이제 그만'이라는 선언인 셈이죠.

앱이 아니라 '스킬'이에요

먼저 개념부터 짚고 갈게요. 이 프로젝트는 앱도, 라이브러리도 아니고 Claude Code 스킬(skill)이에요. 스킬이 뭐냐면, 쉽게 말해 Claude Code에게 건네주는 '전문 분야 매뉴얼'이에요. '다이어그램을 그릴 땐 이런 레이아웃 규칙, 이런 색 배치, 이런 여백을 따라라' 하는 상세한 지침과 예시를 문서로 정리해두면, Claude가 다이어그램 작업을 할 때마다 그 매뉴얼을 펼쳐 보고 일하는 거죠. 신입 디자이너에게 회사 디자인 가이드북을 쥐여주는 것과 비슷하다고 보면 돼요. 같은 AI라도 좋은 매뉴얼이 있으면 결과물의 수준이 완전히 달라진다는 게 이 프로젝트의 출발점이에요.

결과물은 '자급자족형' HTML + SVG

이 스킬이 만들어내는 결과물은 self-contained HTML + SVG 파일이에요. 자급자족형이라는 게 뭐냐면, 파일 하나만 있으면 끝이라는 뜻이에요. 빌드 도구도, 자바스크립트도, 외부 이미지도 필요 없고 브라우저에 드래그해서 열면 바로 보여요. SVG가 처음이신 분을 위해 설명하면, 픽셀을 저장하는 게 아니라 '여기서 저기로 선을 그어라' 같은 명령어로 이루어진 벡터 그림 형식이에요. 그래서 아무리 확대해도 안 깨지고, 본질이 텍스트 파일이라 색상 코드 하나만 바꿔도 수정이 되고, git으로 변경 이력 관리까지 돼요.

지원하는 다이어그램은 29종이나 돼요. 아키텍처, 플로차트, 시퀀스, 상태 머신, ER 다이어그램 같은 개발 문서 단골손님부터 스윔레인, 2×2 매트릭스, 피라미드/퍼널, 레이더 차트, 간트 차트처럼 기획·컨설팅 쪽에서 쓰는 것까지 폭이 꽤 넓어요. 각 다이어그램은 미니멀 라이트, 미니멀 다크, 풀 에디토리얼 세 가지 변형으로 제공되고요. 2.0 버전에서 새로 추가된 Loop 타입이 재미있는데, 플라이휠(선순환 구조)을 그리면서 가운데에 공유 메모리 허브를 두고 각 단계가 점선으로 허브에 기록을 남기는 형태예요. 요즘 AI 에이전트 아키텍처를 설명할 때 딱 맞는 모양이죠.

그리고 가장 눈길을 끄는 기능, 60초 브랜드 매칭이에요. 여러분 블로그나 회사 웹사이트 주소를 주면 스킬이 그 사이트를 읽고 색상과 폰트를 뽑아서 모든 다이어그램에 자동으로 입혀줘요. 색상 피커 붙잡고 고민하는 시간이 통째로 사라지는 거예요.

설계 철학: '뺄수록 좋아진다'

사실 이 프로젝트에서 제일 흥미로운 건 기능보다 철학이에요. README에 이런 문장이 있거든요. '가장 수준 높은 편집은 대개 삭제다. 모든 노드는 자기 자리를 증명해야 한다.' 강조색은 독자가 가장 먼저 봐야 할 한두 곳에만 아껴 쓰고, 목표 밀도는 10점 만점에 4점. 그림자 효과는 아예 금지고요.

이게 왜 중요하냐면, LLM에게 다이어그램을 시키면 보통 정반대로 하거든요. 아는 걸 전부 욱여넣어서 노드 20개짜리 스파게티를 만들어요. 좋은 다이어그램은 '무엇을 그릴까'보다 '무엇을 뺄까'의 문제라는 걸 스킬 규칙으로 강제한 거예요. 발표 잘하는 선배들이 '슬라이드 한 장엔 메시지 하나'라고 조언하는 것과 같은 원리죠.

Mermaid, Figma와 뭐가 다른가요

• Mermaid: 텍스트로 그리는 다이어그램의 사실상 표준이에요. 간단한 문법만 쓰면 자동으로 그려줘서 git 관리와 문서 임베드에 최고죠. 대신 '어떻게 그려질지'를 렌더러가 정해버려서 디자인 커스텀에 한계가 뚜렷해요. 비유하자면 구내식당이에요. 빠르고 균일하지만 맛은 늘 비슷해요.
• Figma·Excalidraw: 자유도는 최고지만 내 손으로 다 그려야 해요. 직접 장 봐서 요리하는 셈이라 시간이 들고, 문서마다 스타일 일관성을 유지하기도 어렵죠.
• diagram-design: 내 취향을 이미 아는 단골 셰프에게 주문하는 느낌이에요. 의도만 말하면 브랜드가 입혀진 완성품이 나와요.

물론 트레이드오프도 분명해요. 첫째, Claude Code에 종속돼요. Mermaid는 GitHub이든 노션이든 어디서나 렌더링되지만 이건 생성 단계에서 Claude Code(또는 함께 제공되는 Codex 플러그인)가 필요해요. 둘째, 재현성 문제요. Mermaid는 같은 소스면 항상 같은 그림이 나오지만, LLM이 생성하는 방식이라 같은 요청도 매번 조금씩 다를 수 있어요. 다만 결과물이 편집 가능한 SVG 텍스트라서, 한 번 뽑은 뒤엔 코드처럼 버전 관리하며 손으로 다듬으면 돼요. 셋째, README 안에서 자동 갱신되는 Mermaid 블록 같은 워크플로를 대체하진 못해요. 그러니 '자주 바뀌는 문서 속 다이어그램은 Mermaid, 블로그·발표·포트폴리오처럼 보이는 게 중요한 다이어그램은 이 스킬'로 나눠 쓰는 게 현실적이에요.

한국 개발자에게: 이렇게 써보세요

• 기술 블로그: 아키텍처 설명 글을 쓸 때 본인 블로그 URL을 넘겨서, 블로그의 색과 폰트가 입혀진 다이어그램을 받는 거예요. 글 전체의 완성도가 갑자기 '있어 보이게' 올라가요.
• 사내 문서와 발표: 분기 회고용 간트 차트, 조직도, 컨설팅식 2×2 매트릭스까지 지원하니 개발팀 바깥 문서에도 쓸 수 있어요.
• 이력서·포트폴리오: 프로젝트 구조를 잘 정돈된 다이어그램 한 장으로 보여주면 전달력이 확 달라지거든요.

학습 로드맵을 제안하자면 이래요. 1단계, Claude Code 공식 문서에서 Agent Skills 개념을 훑어보기. 2단계, 스킬을 설치하고 익숙한 주제로 플로차트 하나 생성해보기. 3단계, 본인 블로그 URL로 브랜드 매핑을 시도해보기. 4단계, 생성된 SVG를 열어 색과 간격을 직접 고쳐보기. 여기까지 가면 '뽑고 다듬는' 자기만의 파이프라인이 생겨요. 덤으로 스킬 파일 자체를 읽어보는 것도 강력 추천해요. 디자인 원칙을 어떻게 문서화하면 AI가 그 수준으로 일하는지 보여주는 훌륭한 교재거든요.

마무리: '디자인도 생성하는 코드'의 시대

이 프로젝트가 진짜로 보여주는 건 다이어그램 도구 하나가 아니에요. '전문가의 감각을 매뉴얼로 정리하면 LLM이 그 수준으로 일한다'는 스킬 생태계의 가능성이죠. 디자인 가이드를 스킬로 만들면 디자이너가 생기고, 코드 리뷰 기준을 스킬로 만들면 리뷰어가 생기는 식으로요. 다이어그램은 그 첫 번째 성공 사례일 뿐이고, 앞으로 각 분야의 '장인 매뉴얼'이 스킬 형태로 쏟아질 가능성이 커요.

여러분은 지금 다이어그램을 어떻게 만들고 계세요? Mermaid로 버티는 파인가요, Figma 장인이신가요, 아니면 '그냥 글로 때우는' 파인가요? 이 스킬을 써보신다면 첫 결과물이 어땠는지, 특히 한글 문서에서의 완성도는 어떤지 댓글로 경험을 나눠주세요.