PlantUML을 오래 썼다. 근데 솔직히 말하면 쓰다 보면 환장하는 구간이 있다.

박스 위치를 내가 원하는 대로 못 박는다. 한 번 조정하면 다른 박스가 엉뚱하게 움직이고, 화면 절반이 빈 공간으로 남는 패턴도 흔하다. AI한테 소스를 시켜도 마찬가지라, 프롬프트 몇 번 돌려야 원하는 그림이 겨우 나온다.

그러다 X 타임라인에서 fireworks-tech-graph를 만났는데, 예시 이미지 하나 보고 "와우" 했다. AI가 SVG 요소를 하나씩 직접 써서 이 완성도를 뽑는다는 게 기대 밖이었고, 비슷한 시기에 architecture-diagram-generator도 타임라인에서 스쳤다.

이게 끝일 리 없다 싶어 AI한테 "다이어그램 스킬 중에 요즘 잘 나가는 거 또 뭐 있냐"고 직접 물어봤더니, 추천으로 건진 게 excalidraw-diagram-skill. Mermaid는 코드형의 대표격이니 기준으로 끼워 넣었고, 이 글은 그렇게 모인 4개에 같은 아키텍처를 네 번 그리게 한 결과다.

네 가지 AI 다이어그램 스킬 비교 요약

살펴본 네 개

  • Mermaid (WH-2099/mermaid-skill). 텍스트 코드(.mmd)를 뱉고 외부 런타임이 SVG로 렌더. Git에 올리면 diff로 변경 추적이 된다. 22종 타입 전부 지원. 대표격으로 편입.
  • fireworks-tech-graph (yizhiyanhua-ai). SVG를 직접 그려 PNG까지 뽑아준다. 15종 타입(Architecture, Sequence, ER, UML 계열에 Agent Architecture·Memory Architecture 같은 AI 전용까지)과 7가지 배경 프리셋(Flat Icon, Dark Terminal, Blueprint, Notion, Glassmorphism, Claude, OpenAI) 제공. X에서 우연히 발견 ("와우" 지점).
  • architecture-diagram-generator (Cocoon-AI). 자체 완결 HTML 파일을 뱉어 브라우저로 바로 열린다. 2.5k⭐, 다크 테마 단일 파일이 시그니처. X에서 우연히 발견.
  • excalidraw-diagram-skill (coleam00). Excalidraw JSON + Playwright로 "AI가 자기 렌더를 보고 고치는" 피드백 루프가 박혀 있다. AI 추천으로 건짐.

테스트 과제

네 스킬에 똑같이 던진 건 가상의 e-commerce 스택이다. 흔한 MSA 구성이라 비교 기준으로 무난하다.

  • 웹 + 모바일 클라이언트 · CDN · API Gateway
  • 마이크로서비스 4개: Auth, Order, Payment, Inventory
  • 데이터 레이어: PostgreSQL, Redis, 이벤트 버스, 오브젝트 스토리지
  • 외부 의존: Stripe

조건 하나. 동기 요청 흐름, 데이터 접근, 비동기 이벤트가 한 그림에 다 보여야 한다.

① Mermaid

렌더링 방식: Claude는 텍스트만 쓴다. flowchart LR로 시작해 노드와 화살표를 .mmd 소스로 쓰면 외부 런타임(Mermaid.js 또는 mmdc CLI)이 SVG로 뽑는다. WH-2099/mermaid-skill은 22종 타입을 정확히 쓰게 안내하는 시스템 프롬프트 묶음이다.

컴포넌트 다이어그램

Mermaid로 그린 e-commerce 스택

강점은 Git. architecture.mmd를 리포에 두면 PR에서 diff가 그대로 읽힌다.

약점은 레이아웃 통제가 거의 안 된다는 것. 자동 레이아웃 엔진(dagre)에 맡기다 보니 박스 하나 옆으로 미는 것도 힌트만 줄 수 있고, 복잡해질수록 박스가 쏠리고 화살표가 꼬인다. PlantUML에서 겪던 문제랑 결이 같다.

시퀀스 다이어그램

같은 스킬에 시퀀스도 시켰다. sequenceDiagram 블록에 participant 8개, 메시지 18개, alt payment ok/failed 분기. .mmd 소스 60줄로 끝.

Mermaid sequenceDiagram으로 그린 주문 결제 시퀀스

중첩형 다이어그램

Mermaid로 그린 Order Service 내부

같은 Order Service를 subgraph로 열어봤는데, 계층 박스 안에 클래스 박스를 중첩해 넣는 코드 구조 자체는 간결하다.

결과물은 기대보다 덜 질서정연한데, dagre 자동 레이아웃이 Domain을 바닥으로 내려보내고, 레이어를 가로지르는 화살표가 여기저기서 꼬인다. 중첩이 2단을 넘어서면 레이아웃 엔진이 붙잡고 있던 게 풀려버리는 순간이 온다.

② fireworks-tech-graph

렌더링 방식이 좀 특이한데, Claude가 SVG를 직접 쓰지 않고 SVG를 만드는 Python 스크립트를 먼저 쓴다. SKILL.md가 이걸 "MANDATORY"로 못 박아 놨다.

python3 << 'EOF'
lines = []
lines.append('<svg xmlns="..." viewBox="0 0 960 600">')
lines.append('  <defs>')
# ... 한 요소씩 독립된 줄로 누적
lines.append('</svg>')
with open('out.svg', 'w') as f:
    f.write('\n'.join(lines))
EOF

이유도 같이 적혀 있다. "각 줄이 독립적이라 문자 잘림·오타·구문 오류를 줄일 수 있다." 긴 SVG를 한 번에 쓰다가 토큰이 잘려서 태그가 깨지는 사고를 차단하는 방어적 패턴인데, 생성이 끝나면 rsvg-convert로 1920px PNG까지 뽑아준다.

컴포넌트 다이어그램

fireworks-tech-graph로 생성한 e-commerce SVG 다이어그램

SKILL.md에 도메인 지식이 녹아 있다. RAG 파이프라인, Multi-Agent, Tool Call Flow 같은 AI 워크플로우를 그리라고 시키면 패턴별 고정 레이아웃이 튀어나오고, "LLM = 둥근 직사각형에 강조색", "Long-term memory = 원통", "Decision = 다이아몬드" 같은 shape vocabulary가 7단계 절차 안에 박혀 있다.

약점 하나. 토큰을 많이 먹는다. Python 래퍼, lines.append 호출, 그 안의 SVG 문자열까지 다 출력하니까 직접 생성 대비 거의 두 배가 들고, 안전하게 가려고 택한 패턴의 대가인 셈이다.

시퀀스 다이어그램

시퀀스도 같은 Python 래퍼 방식으로 그렸다. lifeline, activation box, alt frame, 번호 배지, 범례까지 SKILL.md의 Sequence Diagram 레이아웃 규칙이 모두 강제하는 요소다.

fireworks-tech-graph로 생성한 주문 결제 시퀀스

약점 둘. 화살표 구성이 엉망인데, SKILL.md엔 "jump-over arcs"라고 화살표가 교차할 때 위로 넘어가는 아치를 그려서 겹치지 않게 한다는 규칙이 박혀 있다. 근데 솔직히 나는 실제 출력에서 이게 적용된 걸 한 번도 본 적이 없다. 아키텍처든 시퀀스든 교차 구간은 그냥 선이 겹치는, 스펙이랑 실제 출력이 따로 노는 전형이다.

중첩형 다이어그램

fireworks로 그린 Order Service 내부

네 계층을 가로 병렬 박스로 배치하고 점선으로 구역을 나눠 중첩을 표현했고, 모든 의존이 Domain으로 수렴하는 방향이 한눈에 보인다.

다만 깊이는 2단에서 멈춘다. 계층 안 클래스 박스까지는 들어가는데, 그 안쪽(예: 클래스 내부 분해)으로 더 파고들려고 하면 SVG 수작업 양이 가파르게 늘어난다.

③ architecture-diagram-generator

렌더링 방식: Claude가 HTML 파일 하나를 직접 뱉는다. 브라우저로 열면 그게 결과물. 중간 런타임이 없다(Mermaid의 런타임, fireworks의 rsvg-convert, excalidraw의 Playwright와 대조).

안쪽에 들어가는 구성은 이렇게 고정돼 있다.

  • 인라인 SVG로 다이어그램을 그림
  • 임베디드 CSS로 스타일 (외부 CSS 파일 없음)
  • JetBrains Mono 웹폰트 (Google Fonts에서 로딩)
  • 배경은 #020617 Slate-950에 40px 격자 패턴
  • 색 팔레트는 역할별 하드코딩: backend = emerald, database = violet, pipeline = amber, security = rose, external = slate

컴포넌트 다이어그램

architecture-diagram-generator로 생성한 e-commerce HTML 다이어그램

강점은 한 장짜리 HTML이라 docs/architecture.html로 올리면 브라우저에서 그냥 열린다는 것. 이미지, 런타임, 플러그인 따로 필요 없고, 폰트·팔레트도 정해져 있어서 미적 고민이 없다.

약점은 수정이 구조화돼 있지 않다는 점이다. "Payment 서비스를 분리해줘" 같은 요청을 주면 Claude가 HTML을 통째로 다시 생성하니까 diff가 난잡해진다. 다크 테마도 고정인데, 팔레트가 SKILL.md에 하드코딩돼 있어서 라이트 테마로 바꾸는 것도 쉽지 않다.

시퀀스 다이어그램

이 스킬은 시퀀스 다이어그램을 지원하지 않는다. "한 장" 전용이라, lifeline 타입 자체가 아예 없다.

중첩형 다이어그램

architecture-diagram-generator로 그린 Order Service 내부

의미론적 팔레트(API 시안, Application 그린, Domain 바이올렛, Infra 앰버)로 계층을 색으로 구분했다. HTML 카드·푸터까지 한 세트라 운영 콘솔 같은 분위기가 난다.

중첩 깊이는 2단. 레이어와 그 안의 컴포넌트까지가 이 스킬의 자연스러운 한계선인데, 더 들어가면 팔레트가 포화되고 그리드가 빽빽해진다.

④ excalidraw-diagram-skill

렌더링 방식: 순환형 루프다.

  1. Claude가 Excalidraw JSON 생성
  2. Playwright가 헤드리스 브라우저에서 JSON을 렌더해 PNG 추출
  3. Claude가 그 PNG를 눈으로 보고 JSON을 수정
  4. 1~3을 2~4회 반복

다른 셋은 텍스트·HTML·SVG를 한 번 뱉으면 거기서 끝인 반면, 이건 시각 검사가 루프 안에 들어가 있다. SKILL.md가 흥미로운 원칙을 여럿 요구하는데 대표적인 둘.

Isomorphism Test: "If you removed all text, would the structure alone communicate the concept?"
(번역: 모든 텍스트를 지워도 구조만으로 개념이 전달되는가?)
Evidence Artifacts: 기술 다이어그램엔 실제 JSON 페이로드, 실제 API 메서드 이름, 스펙에서 딴 이벤트 시퀀스 같은 구체적 증거를 포함하라. 박스에 "DB"라고만 쓰지 말고 "postgres · orders + inventory"라고 쓰라는 얘기.

컴포넌트 다이어그램

excalidraw-diagram-skill로 생성한 e-commerce 다이어그램 (Playwright 렌더)

위 두 원칙이 결과물에 그대로 드러난다. 박스 라벨이 postgres · orders처럼 구체적이고, 박스의 색·굵기·배치가 레이블 없이도 "이건 핵심이다"를 말한다.

시퀀스 다이어그램

시퀀스도 같은 스킬에 시켰는데, Excalidraw JSON으로 뽑고 Playwright 렌더·재수정 루프를 2회 돌렸다. 번호 배지가 라벨과 겹쳐서 배지를 왼쪽 거터로 빼고 alt 분기 박스를 늘린 게 2번째 패스에서 고친 부분이고, 스킬이 시키니까 실제로 고치게 된다.

excalidraw-diagram-skill로 생성한 주문 결제 시퀀스

중첩형 다이어그램

excalidraw로 그린 Order Service 내부

이 스킬만 SKILL.md가 Multi-Zoom Architecture를 원칙으로 못 박는다. Level 1 요약 흐름 → Level 2 섹션 경계 → Level 3 섹션 안의 세부까지 세 층으로 같이 그린다는 규칙이다.

같은 과제를 그리면 bounded context → 5개 계층 → 각 계층의 구체 클래스 + invariant 같은 조건이 한 장에 3단으로 들어간다. 넷 중 중첩 깊이를 가장 멀리 끌고 갈 수 있었던 이유.

출력이 .excalidraw JSON이라, README에 그대로 꽂으려면 PNG나 공유 링크로 한 번 바꾸는 단계가 필요하다. Playwright를 띄우는 오버헤드 얘기도 있는데, 적어도 내 환경에선 특별히 무겁다고 느끼진 못했다.

그래서 뭘 쓸까

fireworks와 excalidraw는 첫인상이 좋았다. 둘 다 Mermaid보다 그림이 꼼꼼했고, excalidraw는 Multi-Zoom이라는 원칙까지 내세우길래, 이 정도면 믿을 만해 보였다.

근데 같이 놓고 보면 선 겹치는 문제가 꽤 심각한데, 그냥 교차가 아니라 라벨·화살표·박스 경계가 서로 먹고 들어가는 수준이다. fireworks는 특히 아쉬웠는데, SKILL.md에 "jump-over arcs"라고 규칙까지 박아뒀으면서 실제 출력에선 한 번도 적용된 걸 못 봤다. 스펙이랑 결과가 따로 노는 거, 좀 실망.

그럼에도 내 선택은 fireworks. 이걸 실무 아키텍처 문서에 쓰려는 게 아니라 간단한 개념 도식을 그릴 용도라서, SVG가 파일로 바로 떨어지는 것도 편하고, SKILL.md에 박힌 shape vocabulary(LLM은 둥근 박스, memory는 원통) 같은 것도 내가 주로 다루는 주제하고 잘 맞는다. 선 겹침은 거슬리긴 해도 단순 도식에선 큰 문제가 아니고, 화살표를 손볼 생각도 없다. 그럴 만큼 복잡한 그림이면 애초에 이 스킬들 범위가 아니니까.