Diagram Design: AI 다이어그램 스킬이 작동하는 원리

클로드(Claude)나 코덱스(Codex)에게 다이어그램을 그려달라고 하면 거의 항상 똑같은 결과물이 돌아옵니다: 둥근 사각형 몇 개, 화살표 몇 개, 기본 강조색, 그리고 사이트의 나머지 부분과는 전혀 어울리지 않는 레이아웃. Diagram Design은 바로 이 문제를 고치기 위해 만들어진 오픈소스 AI 스킬입니다 — 그리고 그 해법은 더 나은 프롬프트와는 전혀 상관없는 트릭에 있습니다.

Diagram Design이 실제로 작동하는 방식은 이렇습니다: 모델에게 "보기 좋게 만들어줘"라고 요청하는 대신, 색상·노드·화살표·모서리 반경에 대한 고정된 숫자 상한선 — 엄격한 숫자 예산을 던져주고, 결과물을 내놓기 전에 반드시 통과해야 하는 체크리스트를 부여합니다. '감(vibe)' 대신 '예산(budget)'을 쓴다는 이 한 가지 결정이, 여기서 훔쳐 갈 만한 아이디어의 전부입니다.

Diagram Design이란 정확히 무엇인가

자체 GitHub "About" 란에 따르면 Diagram Design은 "Editorial diagram design for Claude Code, Codex, GitHub Copilot, Cursor, Factory Droid, and Pi,"(클로드 코드, 코덱스, 깃허브 코파일럿, 커서, Factory Droid, Pi를 위한 에디토리얼 다이어그램 디자인)이며, 이어서 "44 diagram types. Self-contained HTML + SVG. No shadows. No Mermaid slop."(다이어그램 44종. 자체 완결형 HTML + SVG. 그림자 없음. 머메이드(Mermaid)스러운 날림 없음.)이라고 적혀 있습니다. (README 자체는 다른 곳에서 다른 숫자를 제시하는데 — 이 불일치는 아래에서 다시 다룹니다.) README는 좀 더 평범한 말로 설명합니다: "An agent skill that draws diagrams as one self-contained HTML + SVG file, in your brand."(브랜드에 맞춰 다이어그램을 하나의 자체 완결형 HTML + SVG 파일로 그려주는 에이전트 스킬.)

다운로드해서 쓰는 독립형 앱이 아닙니다. 이미 쓰고 있는 AI 코딩 툴에 꽂아 넣는 스킬 파일입니다 — 클로드 코드, 커서, 코덱스, 깃허브 코파일럿, Gemini CLI, Cline, Windsurf 등이 대상이며, 명령어 한 줄로 설치합니다: npx skills add cathrynlavery/diagram-design. 설치하고 나면 다이어그램 편집기를 따로 여는 게 아니라, 이미 대화하던 에이전트에게 "내 앱의 아키텍처 다이어그램을 만들어줘" 같은 문장을 입력하면, 빌드 단계도 JavaScript 의존성도 없이 인라인 SVG가 포함된 .html 파일 하나를 바로 써줍니다.

무료로 제공되며 MIT 라이선스 아래 배포됩니다. 저작권 표기는 "Copyright (c) 2025 Cathryn Lavery."입니다. 만든 사람 Cathryn Lavery는 자신의 GitHub 소개란에 "Founder @bestselfco ($55M+ bootstrapped). Sold to PE in 2022. Bought it back 2024. Becoming AI Native & documenting as I go!"(bestselfco 창업자, 외부 투자 없이 $55M+ 규모로 성장, 2022년 PE에 매각, 2024년 되사들임, AI 네이티브가 되어가는 과정을 기록 중!)라고 적어두었습니다 — 본인 발표 기준 수치일 뿐 외부 감사를 거친 숫자는 아니지만, 이 저장소가 제작자에 대해 스스로 밝히는 유일한 맥락입니다.

출발점이 된 문제: 모델은 콘텐츠는 이해했지만 디자인은 몰랐다

README는 이 스킬이 왜 존재하는지를 작고 구체적인 불만 하나로 설명합니다. Lavery는 자신의 블로그에 다이어그램이 필요할 때마다 "I'd ask Claude and get back a generic rounded-box thing that looked nothing like the rest of the site."(클로드에게 물어보면 사이트의 나머지 부분과는 전혀 안 어울리는, 그저 평범한 둥근 박스 뭉치가 돌아왔다)라고 썼습니다. 이 불만 바로 다음 문장이 진짜 핵심입니다: "The model already understood the content."(모델은 이미 콘텐츠를 이해하고 있었다.) 모델이 이해력에서 실패한 게 아니었습니다 — 그녀가 보여주고 싶었던 아키텍처, 흐름, 단계를 모델은 이미 파악하고 있었습니다. 모델에게 없었던 건 안목(taste)이었습니다: 얼마나 보여주고 얼마나 덜어낼지, 단 하나의 강조색을 어디에 둘지에 대한 감각이요.

이것이 바로 Diagram Design이 메우려는 틈이며, README는 이 틈이 좁다는 것도 분명히 밝힙니다: "Diagram Design is for the diagram you are going to publish,"(Diagram Design은 당신이 발행할 다이어그램을 위한 것이다) — 모든 화이트보드 스케치를 위한 것은 아닙니다.

메커니즘: '보기 좋게'를 숫자 예산으로 바꾸다

실제 규칙은 에이전트가 무엇을 그리기 전에 먼저 읽는 긴 지시 파일 skills/diagram-design/SKILL.md에 담겨 있습니다. 모호한 스타일 가이드 대신, 이 파일은 엄격한 숫자를 정해둡니다:

• 제안이 아니라 복잡도 예산: SKILL.md에 따르면 모든 다이어그램은 노드(node) 9개, 화살표 12개, 코랄색 강조 요소 2개, 콜아웃 2개로 상한이 정해져 있습니다.
• 자유 배치가 아니라 그리드: "Structural geometry sits on a 4px grid,"(구조적인 기하 형태는 4px 그리드 위에 놓인다)라고 명시돼 있어, 눈대중으로 위치를 잡는 요소가 하나도 없습니다.
• 단 하나의 형태만 허용되는 커넥터: "Orthogonal only."(직각 연결만 허용.) 오직 직각 꼭지 연결선만 쓸 수 있으며 — 파일은 "Diagonals fail."(대각선은 실패다.)라고 딱 잘라 말합니다.
• 의미를 담은 색은 하나뿐: SKILL.md에 따르면 강조색은 "goes on 1–2 elements max,"(최대 1~2개 요소에만 들어간다) 다이어그램에서 실제로 중요한 한두 가지만을 위해 아껴둡니다.
• 그림자 전면 금지: "Shadows are out. Borders are in."(그림자는 아웃, 테두리가 인.) 모서리 반경은 최대 6~10px이거나 아예 없습니다.
• 덜어내는 쪽으로 기우는 철학: README가 스스로 요약한 철학은 "Every node earns its place."(모든 노드는 자기 자리를 '증명'해야 한다.)입니다.

이 중 어느 것도 "깔끔하게 유지하려고 노력하라" 같은 식으로 포장된 스타일 조언이 아닙니다. 모델이 스스로 검증할 수 있는 통과/실패 기준의 집합이며 — 이게 바로 다른 곳에도 옮겨 쓸 수 있는 아이디어입니다. LLM에게 "안목을 가져라"라고 말하면 결과가 일관되지 않습니다. 안목은 지시가 아니라, 매번 다르게 내려지는 판단이기 때문입니다. 숫자는 판단이 아닙니다.

"테이스트 게이트": 모델이 결과를 내놓기 전에 통과해야 하는 체크리스트

이 스킬은 규칙을 한 번 던져주고 알아서 지켜지길 바라는 식이 아닙니다 — 에이전트가 스스로 자기 결과물을 검사하게 만듭니다. SKILL.md는 "Run before producing any diagram"(다이어그램을 만들기 전에 실행하라)라는 제목이 붙은 출력 전 체크리스트를 정의하고, 새 다이어그램을 만들 때 밟아야 하는 5단계 제작 순서도 함께 정합니다: 템플릿을 복사하고, 선택한 다이어그램 유형에 맞는 타입 레퍼런스를 불러오고, 자리표시자(placeholder)를 채우고, 요청받은 모션이 있으면 처리하고, 그런 다음에야 이 파일이 "테이스트 게이트(taste gate)"라고 부르는 단계를 실행합니다. 이보다도 앞서, 이 파일의 '0번 섹션'은 에이전트가 프로젝트의 브랜드 스타일 가이드가 실제로 커스터마이징되었는지부터 확인하도록 요구합니다 — 기본값이 그대로 남아 있다면, 에이전트는 그냥 평범해 보이는 결과물을 조용히 내놓는 대신 멈춰서 사용자에게 어떻게 커스터마이징할지 물어보라는 지시를 받습니다.

또한 에이전트가 자기 과정을 설명하게 만듭니다: 렌더링하기 전에 에이전트는 "state the plan in one short message"(짧은 메시지 하나로 계획을 밝혀야 한다) — 어떤 시각적 유형을 골랐는지, 왜 골랐는지를요 — 그래서 숫자 규칙이 블랙박스 안에 숨겨지지 않습니다. 결과물을 보기 전에 결정 과정을 먼저 보게 되는 것입니다.

다이어그램 유형도 다양하게 다루고, 경쟁 툴의 파일도 가져온다

이 스킬은 플로차트에만 머물지 않습니다. README의 "What it makes"(만들 수 있는 것) 표에는 시각 유형 45종이 나열돼 있습니다 — 아키텍처 다이어그램, 시퀀스·상태 다이어그램, ER/데이터 모델 다이어그램, 타임라인, 쿼드런트 차트, 생키(Sankey) 다이어그램, 간트(Gantt) 차트, 워들리 맵(Wardley map), UML 클래스 다이어그램까지 포함되며, 각각 세 가지 정적 변형(미니멀 라이트, 미니멀 다크, 풀 에디토리얼)으로 렌더링됩니다. 같은 README에 따르면, 기존 draw.io·Mermaid·Excalidraw 파일을 불러와 자신의 스타일로 다시 그려 SVG나 PNG로 내보내는 것도 가능합니다.

솔직하게 짚어둘 부분: 프로젝트 자신의 숫자들이 서로 안 맞습니다. About 소개글은 다이어그램 44종이라고 하고, CHANGELOG의 아직 릴리스되지 않은 섹션은 같은 44로 맞춰지는 갤러리 번호 수정 내역을 설명하는 반면, README의 다른 부분은 여전히 45라고 말합니다. 두 숫자 모두 같은 프로젝트에서 나온 것이고, 그저 업데이트가 진행되는 중간에 걸린 것일 뿐입니다 — 다듬어진 단발성 릴리스가 아니라 실제로 계속 살아 움직이는 저장소라는 사실을 작고 거의 웃길 만큼 확실하게 보여주는 증거입니다.

일주일짜리 트렌딩 반짝임이 아니라, 지금도 활발히 관리되고 있다

Diagram Design은 예전에 한 번 떴던 순간에 안주하고 있는 죽은 저장소가 아닙니다. 이 글을 쓰는 시점 기준 스타 52.6k개, 포크 3.3k개를 보유하고 있고, "SVG export scopes CDATA markers into carried stylesheet selectors"처럼 구체적인 제목을 단 열린 이슈 17개, 그리고 열린 풀 리퀘스트 29개, 닫힌 풀 리퀘스트 258개가 있습니다. 공개된 커밋 히스토리를 보면 2026년 10월 10일과 12일 단 이틀 사이에만 커밋 35개가 올라왔는데, 그중 15개는 자동화된 "chore(release)" 플러그인 매니페스트 버전 업 커밋이고 나머지는 사람이 직접 작성한 수정·기능·머지입니다 — 드물게 큰 덩어리로 릴리스하는 대신 끊임없이 배포하는 릴리스 파이프라인이라는 신호입니다. 아직 태그가 붙은 GitHub 릴리스는 없습니다; 릴리스 탭은 비어 있고, 그래서 믿을 수 있는 버전 번호는 릴리스 페이지가 아니라 플러그인 매니페스트와 CHANGELOG에 적힌 숫자입니다.

이 스킬이 풀지 못하는 문제

프로젝트는 README에서 자신의 한계를 솔직하게 밝힙니다: 결과물의 품질은 여전히 어떤 모델이 이 스킬을 실행하느냐에 달려 있고, 같은 프롬프트라도 실행할 때마다 다른 레이아웃이 나올 수 있습니다 — 규칙은 결과를 제약할 뿐, 결정론적으로 만들어주지는 않습니다. 또한 결과물은 Mermaid의 .mmd 파일처럼 편집 가능한 소스 포맷이 아니기 때문에, 스프린트마다 바뀌고 버전 관리에 올라가는 다이어그램이라면 README 스스로도 Mermaid가 여전히 더 나은 도구라고 인정합니다. 이 스킬은 앞으로 계속 고쳐 쓸 다이어그램이 아니라, 한 번 발행하고 끝날 다이어그램을 위한 것입니다.

이게 일반화되면 어떤 이야기가 될까요

여기서 얻을 수 있는 교훈은 "4px 그리드를 써라"가 아닙니다. 언어 모델에게 디자인된 것처럼 보여야 하는 무언가를 만들어달라고 요청하는 모든 상황에 적용되는 패턴입니다: 모호한 미학적 지시("깔끔하게 해줘", "모던하게 해줘")는 모델이 스스로 검증할 구체적인 기준이 없기 때문에 일관되지 않은 결과를 낳습니다. 요소 개수의 상한, 고정된 그리드, 단 하나의 강조색, 출력 전에 실행하는 통과/실패 체크리스트 같은 숫자 예산은 모델에게 실제로 검증할 수 있는 무언가를 줍니다 — 범위를 좁게 잡은 깃허브 트렌딩 클로드 코드 스킬이 넓고 모호한 임무 대신 명시적이고 검증 가능한 규칙으로 단 하나의 일을 해냄으로써 신뢰를 얻은 것과 같은 방식입니다. AI 에이전트가 시각적이거나 구조적인 결과물을 만들어내야 하는 무언가를 만들고 있는데 결과물이 자꾸 평범하게 나온다면, 여기서 보여준 해법은 더 나은 프롬프트가 아니라 더 작고 더 날카로운 규칙집입니다 — Loop Habit Tracker의 점수 산출 공식이 모호한 "꾸준히 하자"라는 목표를 실제로 계산 가능한 숫자로 바꿔치기할 때 쓰는 것과 똑같은 수법입니다.