AI가 만든 다이어그램을 읽히게 하는 법: Diagram Design 스킬 살펴보기

AI에게 아키텍처나 사용자 여정을 그려 달라고 하면, 내용은 대체로 맞는데 읽는 순서가 없는 그림이 자주 나옵니다. 같은 모양의 상자와 화살표가 늘어서고, 중요한 흐름과 보조 정보가 같은 무게로 보이는 문제입니다.

Diagram Design ↗은 이 빈틈을 겨냥한 Agent Skill입니다. Claude Code와 Codex 같은 에이전트에게 다이어그램의 내용뿐 아니라 정보 위계, 여백, 색상, 연결선, 접근성 규칙까지 함께 주어 HTML과 SVG 결과물을 만들게 합니다.

먼저 결론부터 말하면, 이 프로젝트의 가치는 다이어그램 유형을 많이 제공하는 데만 있지 않습니다. 생성 결과를 “예쁜 그림”으로 보지 않고, 독자가 무엇을 먼저 읽고 어디서 의미를 연결해야 하는지까지 설계 대상으로 만든 데 있습니다.

이 글에서 다루는 내용은 다음과 같습니다.

• AI 다이어그램이 “맞지만 읽기 어려워지는” 이유
• Diagram Design이 스킬에 넣은 시각적 제약
• 제품 UI의 디자인 시스템과 문서용 다이어그램 규칙의 차이
• 팀 문서에 적용할 수 있는 가벼운 품질 게이트

문제는 SVG 생성이 아니라 편집 결정입니다

Mermaid, draw.io, Excalidraw, SVG는 이미 다이어그램을 표현하는 좋은 도구입니다. 하지만 도구가 있다고 해서 어떤 정보를 생략하고, 무엇을 강조하며, 독자가 어느 방향으로 읽게 할지는 자동으로 결정되지 않습니다.

Diagram Design의 README ↗는 이 문제를 “generic rounded boxes”의 반복으로 설명합니다. 프로젝트는 아키텍처, 흐름, 시퀀스, ER 모델, 타임라인, 사용자 여정, 배포와 같은 39개 유형을 제시하지만, 더 중요한 기준은 유형을 고른 뒤의 편집 규칙입니다.

flowchart TD
    A[문서의 핵심 질문] --> B[표현 유형 선택]
    B --> C[정보 위계 결정]
    C --> D[레이아웃·색상·연결선 규칙 적용]
    D --> E[HTML + SVG 생성]
    E --> F[접근성·독해성 사람 검토]

이 흐름에서 AI는 마지막 그림만 만드는 존재가 아닙니다. 요구사항을 가장 적절한 시각 형식으로 옮기고, 정해진 제약 안에서 초안을 만드는 역할을 맡습니다. 사람은 여전히 “이 그림이 독자의 질문에 답하는가”를 검토해야 합니다.

스킬은 다이어그램에 무엇을 강제할까

공식 skill 문서 ↗는 내용의 의미와 레이아웃을 분리합니다. 예를 들어 큐, 신뢰 경계, 정책 추적 같은 의미 패턴은 기존 시각 유형에 얹을 수 있고, 매번 새로운 도형 체계를 만들 필요가 없습니다.

1. 강조는 적게, 위계는 분명하게

README는 강조색을 독자가 먼저 봐야 할 1~2개 요소에만 쓰고, 나머지는 기본 색과 보조 색으로 처리하는 원칙을 제시합니다. 모든 상자를 같은 크기·같은 색으로 만들면 AI가 정보를 빠뜨리지 않았더라도 독자는 중요도를 판별할 수 없습니다.

이는 Atlassian DESIGN.md가 제품 UI에 디자인 의도를 전달하려 한 이유와 닿아 있습니다. 다만 DESIGN.md가 제품 전반의 토큰·컴포넌트 문맥을 다룬다면, Diagram Design은 한 장의 설명 그림에서 어떤 메시지를 가장 먼저 보일지에 집중합니다.

2. 연결선도 문장처럼 읽혀야 합니다

스킬은 대각선 연결, 라벨과 선의 충돌, 지나친 교차를 피하고, 연결선이 노드 뒤에 놓이도록 하는 규칙을 명시합니다. 화살표는 장식이 아니라 관계를 읽는 문법이기 때문입니다.

3. 정적 결과물을 기본으로 둡니다

프로젝트는 결과물을 self-contained HTML과 SVG로 만들고, 기본 출력은 별도의 build step이나 JavaScript 없이 브라우저에서 열 수 있다고 설명합니다. 순서를 설명할 때만 선택적으로 motion을 더하는 방향입니다.

이 선택은 Claude Code에서 HTML을 검토 화면으로 쓰는 방법과도 잘 맞습니다. HTML은 단순 문서보다 풍부한 표현을 제공하지만, 문서에서 필요한 것은 항상 인터랙션이 아니라 빠르게 공유하고 검토할 수 있는 결과물인 경우가 많습니다.

접근성은 내보내기 옵션이 아니라 생성 규칙입니다

다이어그램은 특히 색상과 위치에 의미를 숨기기 쉽습니다. 공식 문서는 색·배경 대비, SVG의 이름과 설명, motion 감소 선호를 고려하도록 안내합니다. 즉, 결과물의 마지막 점검 항목이 아니라 생성 단계에 접근성 제약을 넣는 접근입니다.

이 관점은 DTCG와 DESIGN.md에서 다룬 디자인 토큰의 역할과도 구분됩니다. 토큰은 색·간격·타이포그래피를 일관되게 쓰도록 돕지만, 다이어그램이 담아야 할 정보 위계까지 대신 정해 주지는 않습니다. 스킬은 그 사이에 “표현을 선택하고 검토하는 절차”를 추가합니다.

우리 팀 문서에 적용하는 최소 규칙

프로젝트 전체를 바로 설치하지 않아도 접근법은 가져올 수 있습니다. 먼저 팀이 반복해서 만드는 다이어그램 하나를 고르고, 아래 네 가지를 짧은 스킬이나 문서 규칙으로 고정해 보세요.

1. 독자의 질문을 한 문장으로 적습니다. 아키텍처를 모두 보여 주는 대신, 예를 들어 “요청은 어디서 인증되고 실패는 어디로 가는가”처럼 질문을 좁힙니다.
2. 유형을 먼저 고릅니다. 시간의 흐름이면 sequence나 timeline, 소유 관계면 tree나 org chart, 상태 변화면 state diagram처럼 표현의 문법을 맞춥니다.
3. 강조와 금지를 정합니다. 핵심 경로 1개, 강조색 1개, 노드당 최대 라벨 길이, 피해야 할 연결선 교차처럼 검토 가능한 규칙을 둡니다.
4. 본문에도 결론을 씁니다. 다이어그램만 보고 이해해야 하는 정보를 만들지 말고, 그림 아래에 핵심 해석과 텍스트 대안을 남깁니다.

이 방식은 Figma MCP와 AI 에이전트 디자인처럼 캔버스와 실제 컴포넌트에 접근하는 도구를 대체하지 않습니다. 대신 PR 설명, RFC, 장애 회고, 제품 문서처럼 한 번 읽고 판단해야 하는 시각 자료의 초안 품질을 일정하게 만들기 위한 가드레일입니다.

설치보다 먼저 정해야 할 것

Diagram Design의 공식 README ↗는 Claude Code와 Codex용 marketplace 설치 경로를 제공하고, 저장소의 공용 스킬 디렉터리를 여러 Agent Skills 호스트에서 사용하도록 안내합니다. 하지만 팀에 도입할 때 가장 먼저 할 일은 설치가 아니라 “어떤 문서를 어떤 독자에게 설명할 것인가”를 정하는 일입니다.

다이어그램 규칙은 디자인 리뷰를 없애지 않습니다. 대신 매번 같은 종류의 실수—동일한 상자, 과한 강조색, 읽기 어려운 연결선, 색에만 의존한 의미 전달—를 초안 단계에서 줄여 줍니다.

AI로 문서를 더 빨리 만드는 시대에는 그림을 만들 수 있는지가 경쟁력이 아닙니다. 그림이 독자의 판단을 더 빠르게 만드는가가 기준이 됩니다. Diagram Design은 그 기준을 프롬프트 감각이 아니라 재사용 가능한 규칙으로 옮긴 사례입니다.

참고 자료

• Diagram Design GitHub 저장소 ↗ — 프로젝트 개요와 라이선스
• Diagram Design README ↗ — 지원 유형, 출력 형식, 설치·브랜드 적용 안내
• Diagram Design SKILL.md ↗ — 디자인·연결선·접근성 규칙
• 공식 갤러리 ↗ — 다이어그램 유형과 테마 예시
• GeekNews 소개 ↗ — 한국어 요약