여러 코딩 에이전트에서 쓰는 편집형 다이어그램 스킬 — 42가지 시각 유형과 자체 검증 도구

AI 요약

Diagram Design은 코딩 에이전트가 일반적인 둥근 상자 대신 일관된 편집 디자인의 다이어그램을 만들도록 돕는 스킬입니다. Claude Code, Codex, GitHub Copilot, Factory Droid, Pi와 Agent Skills 호환 도구에서 같은 스킬 파일을 사용합니다. 결과물은 빌드 과정이나 외부 이미지 없이 브라우저에서 여는 HTML·SVG이며, 기본 출력은 정적입니다. 그림자와 장식용 상자를 줄이고, 다이어그램마다 강조색을 한두 곳에만 쓰도록 설계합니다.

42가지 시각 유형과 의미 패턴

아키텍처, 흐름도, 시퀀스, 상태 머신, ER 모델, 타임라인, 스윔레인, 사분면, 레이더 차트, 루프, 계층 구조부터 Sankey, fishbone, Wardley map, Kanban, 사용자 여정, 배포도, 의존성 그래프, UML 클래스, 스토리 맵, 데이터베이스 스키마까지 지원합니다. 각 유형에는 밝은 테마, 어두운 테마, 편집형 테마의 정적 예제가 있습니다. 2.5.10에서 Sankey 등 열 가지 레이아웃 문법을 추가했습니다.

행동과 배치는 별도로 다룹니다. 큐와 병목, 정책 추적, 신뢰 경계 같은 동작은 아홉 가지 의미 패턴으로 표현한 뒤 적합한 시각 유형에 연결합니다. 패턴을 추가해도 시각 유형 수를 늘리지 않습니다. 에이전트는 요청에 필요한 참조 문서만 불러오도록 구성해, 일상적인 흐름도 요청에는 해당 유형의 지침을 중심으로 작업합니다.

브랜드 설정과 접근성

사용자는 웹사이트 주소를 지정해 브랜드 설정을 시작합니다. 스킬은 사이트에서 배경색, 본문 색, 강조색, 글꼴 등을 읽고 의미 역할에 맞춰 제안합니다. 값을 파일에 쓰기 전에 작은 글자 크기 기준으로 잉크와 배경의 WCAG AA 대비를 확인하며, 기준에 미달하면 조정값을 설명합니다. 확인된 URL, 색상 역할, 글꼴 정보와 대체 여부도 기록합니다. 프로젝트마다 브랜드가 다르면 이름 붙인 프로필을 저장하고 .diagram-design 표식으로 적용할 프로필을 지정합니다.

SVG에는 role="img", 제목과 설명을 연결하는 접근성 이름, 고유 ID를 넣습니다. 여러 SVG를 한 페이지에 삽입해도 ID가 겹치지 않도록 다이어그램과 변형별 접두사를 붙입니다. 애니메이션은 선택 기능입니다. 정적 첫 화면을 완성 상태로 제공하고, reduced-motion 설정에서는 전체 정적 화면을 보여주며 재생 기능을 숨기거나 비활성화합니다. 애니메이션에 쓰는 스크립트는 검토된 컨트롤러로 제한하고 원격 자산과 임의의 실행 속성을 거부합니다.

기존 다이어그램 가져오기와 내보내기

draw.io, Mermaid, Excalidraw 파일을 읽어 같은 내용을 목적지에 맞는 디자인으로 다시 그립니다. 가져올 때 형식은 HTML·SVG·PNG, 크기는 문서·슬라이드·인쇄물 등에 맞춰 고릅니다. 상세도는 faithful(최대 24개 노드), balanced(최대 12개), simplified(최대 7개)로 나뉩니다. 정보가 합쳐지거나 생략되면 결과에 충실도 기록을 남겨 무엇이 바뀌었는지 확인하게 합니다. 원본의 좌표와 색상은 가져오지 않고 구성 요소, 관계, 그룹, 방향을 유지합니다. SVG는 독립 실행형 파일로 내보내며 PNG는 기본 2배 크기로 렌더링합니다.

출력 검증

저장소에는 생성 결과와 예제를 검사하는 도구가 포함됩니다. 렌더링 검사는 헤드리스 Chromium으로 실제 화면을 그려 SVG 잘림, 페이지 넘침, 빠진 로컬 자산과 JavaScript 오류를 찾습니다. 기하 검사에서는 글자와 노드 겹침, 대각선 연결선, 경계선에 붙은 연결선, 화살표 간격 등을 확인합니다. Sankey와 워터폴 차트는 수치 보존과 막대 위치를 따로 검사합니다. 접근성 이름, 애니메이션 컨트롤러, 외부 자산 제한도 CI에서 검증합니다. Linux, Windows, macOS 환경에서 GitHub Actions 검사를 자동 실행합니다.

설치 방법은 에이전트별로 다릅니다. Claude Code, Codex, Copilot, Factory Droid는 각자의 플러그인 마켓플레이스를 사용하고 Pi는 Git 저장소를 설치합니다. 그 밖의 호환 도구에는 npx skills add cathrynlavery/diagram-design 명령을 제공합니다. 마켓플레이스 설치와 독립형 Agent Skill 설치는 업데이트 경로가 다르므로, 저장소는 각 방식의 갱신 명령과 마이그레이션 절차도 안내합니다.

원문: GitHub / 번역·요약: Trawling