Communitygithub.com

D2 다이어그램 스킬

Claude Code 플러그인. D2 아키텍처 다이어그램(TALA/ELK)을 렌더링하고 자체 검증 루프로 수정합니다.

D2 다이어그램 스킬란 무엇인가요?

이 스킬은 Claude Code에서 D2 언어로 다이어그램을 작성하고 렌더링한 뒤, 결과물을 시각적으로 검토하고 수정하는 반복 작업을 자동화합니다. 개발자는 도구 체인 확인, 다이어그램 계획, D2 소스 작성, 렌더링, 시각적 감사 및 수정, 최종 전달까지 6단계로 구성된 워크플로우를 따를 수 있습니다. 특히 '렌더링 후 보기→수정' 루프는 보지 않고 만든 다이어그램이 완성되지 않았다는 원칙에 기반하며, TALA와 ELK 등 다양한 레이아웃 엔진을 지원합니다. 이 스킬은 실제 시스템의 서비스명, 테이블명 등 실제 데이터를 사용하도록 권장하며, 'Service A → Service B'와 같은 추상적인 이름 대신 실제 이름을 사용하여 신뢰도를 높입니다. GitHub README, 문서 사이트, 다크 모드 등 다양한 환경에 맞춘 SVG/PNG 출력을 지원합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add khollingworth/d2-diagram-skill

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

D2 다이어그램

D2 소스를 작성하고 SVG로 렌더링한 후, 렌더링 결과를 보고 발견한 문제를 수정하는 루프를 반복합니다. 보지 않은 다이어그램은 완성되지 않은 다이어그램입니다.

참조 파일 — 필요할 때 로드

파일읽는 시점
references/d2-language.md간단하지 않은 D2를 작성할 때 — 문법, 도형, 컨테이너, 클래스, 변수, 그리고 컴파일은 되지만 렌더링이 잘못되는 함정
references/layout-engines.md레이아웃 선택 또는 디버깅: TALA vs ELK vs dagre, 라이선싱, 시드(seed), 엔진별 동작 차이
references/diagram-patterns.md다이어그램 유형과 구조 선택 — 아키텍처, 시퀀스, ERD, 그리드, C4; 테마, 아이콘, 다크 모드, GitHub 임베딩

0단계 — 도구 체인 확인

첫 번째 렌더링 전에 세션당 한 번 실행합니다 (scripts/는 이 스킬 자체 디렉터리를 의미합니다 — Claude Code에서 ${CLAUDE_SKILL_DIR}이 이 디렉터리로 해석됩니다):

bash "${CLAUDE_SKILL_DIR}/scripts/setup.sh" --check-only
  • d2: ok → 계속 진행합니다.
  • d2: MISSING → 사용자에게 알린 후, 플래그 없이 scripts/setup.sh를 실행하여 Homebrew로 설치하거나, 설치 명령어를 출력해 안내합니다. 보지 않고 렌더링하지 마십시오 — 이 스킬의 다른 어떤 기능도 d2 없이 작동하지 않습니다.
  • tala: not installed 또는 unlicensed → 괜찮습니다. ELK가 자동으로 대체되며 좋은 레이아웃을 생성합니다. 다이어그램이 소프트웨어 아키텍처 다이어그램이고(TALA가 훨씬 더 나은 경우) 사용자가 출력 품질에 신경 쓰는 것 같다면 TALA에 대해 한 번만 언급하고, 절대 강요하지 마십시오.

1단계 — 작성 전 계획

먼저 세 가지를 결정합니다:

  1. 메시지. 독자가 5초 안에 무엇을 결론내길 바라는가? 다이어그램은 무언가를 주장합니다 — "요청이 여기로 분산된다", "이 서비스가 병목이다", "이 두 경로는 절대 만나지 않는다". 주장을 말할 수 없다면, 레이블이 붙은 상자 집합을 그리려는 것입니다.
  2. 유형. 아키텍처/토폴로지 → 기본 도형과 컨테이너. 시간에 따른 상호작용 → sequence_diagram. 데이터 모델 → sql_table. 엄격한 정렬(매트릭스, 대시보드, 범례 중심) → 그리드. 유형별 구조 가이드는 references/diagram-patterns.md를 참조하세요.
  3. 규모. 5–15개 노드는 잘 읽힙니다. 15–25개는 컨테이너로 그룹화해야 합니다. 약 25개를 넘으면 여러 다이어그램으로 나누거나 layers를 사용하세요. 벽화보다는 두 번째 다이어그램을 선호합니다.

실제 시스템의 기술 다이어그램에서는 실제 이름(실제 서비스명, 실제 테이블명, 사용자 코드베이스 또는 설명의 실제 이벤트명)을 사용하세요. 가능하면 코드를 grep하세요. Service A -> Service B는 독자의 신뢰를 낭비합니다.

2단계 — D2 작성

간단한 다이어그램이 아니라면 references/d2-language.md를 먼저 읽으십시오. 깨진 출력의 90%를 방지하는 규칙:

  • 레이블이 아닌 키를 연결하세요. api: API Gateway 다음에 api -> db를 작성하고, 절대 API Gateway -> db라고 작성하지 마십시오. 후자는 조용히 중복 도형을 생성합니다.
  • # 또는 ;가 포함된 레이블은 따옴표로 감싸세요 — 따옴표 없는 #은 레이블 중간에 주석을 시작하고, 따옴표 없는 ;는 줄을 두 도형으로 나누며, 둘 다 오류 없이 컴파일됩니다. 구두점이 있는 레이블은 인용하는 것이 안전한 습관입니다.
  • classes:를 통해 스타일을 적용하고, 노드별 스타일은 피하세요 — 한 번 정의하고 class:로 적용합니다. 개별 노드에 style.fill을 피하십시오. 하드코딩된 채우기는 테마와 충돌하고 다크 모드 렌더링을 깨뜨립니다.
  • 대부분의 아키텍처 흐름에는 direction: right를 설정하세요 (왼쪽에서 오른쪽으로 자연스럽게 읽힙니다). 모든 엔진이 최상위 방향을 존중하며, TALA는 추가로 컨테이너별 direction을 지원합니다.
  • 소스는 {이름}.d2로 출력 파일이 속한 위치(기본값: 프로젝트의 ./diagrams/)에 저장하세요.

3단계 — 렌더링

항상 번들 스크립트를 통해 렌더링하세요. 레이아웃 엔진을 선택하고, 워터마크 출력을 방지하며, 먼저 유효성을 검사합니다:

bash "${CLAUDE_SKILL_DIR}/scripts/render.sh" --png input.d2 output.svg
  • --png는 output.png도 함께 작성합니다. 4단계에서 필요합니다 (Read 도구는 SVG가 아닌 래스터 이미지를 봅니다).
  • 스크립트는 engine:(실제로 렌더링한 엔진)과 fallback:(TALA를 사용하지 않은 이유)을 출력합니다. 사용자가 엔진에 대해 물었거나 명시적으로 TALA를 원한 경우에만 한 줄 메모를 전달하세요.
  • 유용한 플래그: --theme N, --dark-theme 200(SVG가 독자의 색상 구성표에 반응), --sketch, --pad N, --seed N(TALA 재시도), --engine tala|elk|dagre(강제), --allow-watermark(TALA 평가).
  • 실패 시 스크립트는 파일:줄:열 형식의 d2 컴파일 오류를 출력합니다. 해당 위치의 소스를 수정하고 다시 실행하세요. 오류가 명확하지 않으면 references/d2-language.md의 함정 섹션을 확인하세요.

사용자가 명시적으로 동의하지 않는 한 워터마크가 있는 TALA 출력을 전달 용도로 렌더링하지 마십시오. 스크립트는 ELK로 자동 대체하여 이를 강제합니다.

4단계 — 확인하고 수정하기 (필수)

.d2 소스는 렌더링이 실제로 어떻게 배치되었는지에 대해 아무것도 알려주지 않습니다 — 레이아웃은 엔진의 결정이지 여러분의 결정이 아닙니다. Read 도구로 PNG를 열고 두 번 검사하세요:

1차 검사 — 주장을 전달하는가?

  • 눈이 이야기가 시작되는 곳으로 들어가서 끝나는 곳으로 나오는가?
  • 흐름 방향이 일관적인가(뒤로 돌아가거나 의도치 않게 아래에서 위로 읽히지 않는가)?
  • 컨테이너 그룹화가 계획한 논리적 그룹화와 일치하는가?
  • 가장 중요한 요소가 시각적으로 눈에 띄는가, 아니면 묻혀 있는가?

2차 검사 — 레이아웃 결함(자동 레이아웃 엔진은 모두 다음을 생성합니다):

  • 가장자리 레이블이 해당 가장자리에서 멀리 떨어져 있거나, 어떤 가장자리를 설명하는지 모호한 경우
  • 평행 실행에서 가장자리가 겹치거나, 노드나 컨테이너를 가로지르거나, 터무니없이 우회하는 경우
  • 텍스트가 잘리거나 도형/아이콘과 충돌하는 경우
  • 한 영역은 비좁고 다른 영역은 비어 있는 경우; 컨테이너가 내용물보다 훨씬 큰 경우
  • 노드가 너무 작아 레이블이 지배적이거나, 노드 크기가 극도로 일관되지 않은 경우
  • 사용자에게 보여줄 때 변명을 해야 할 것 같은 모든 것

D2의 레버로 수정하고 픽셀을 밀어 넣지 마십시오(자동 레이아웃은 입력을 변경하는 것이지 좌표를 변경하는 것이 아닙니다): direction 변경; 컨테이너로 그룹화/재그룹화; 가장자리 레이블 단축(긴 레이블은 ELK에서 가장 많이 떠돕니다); 병렬 가장자리를 하나의 레이블이 있는 가장자리로 병합; near로 범례/제목을 흐름 밖으로 이동; 과부하된 다이어그램을 layers로 분할; --pad 조정; TALA에서는 --seed N으로 재시도(2-3개 시드 시도 — 레이아웃이 크게 다릅니다); 최후의 수단으로 이 다이어그램 모양에 맞는 엔진으로 전환(references/layout-engines.md 참조).

재렌더링, 재확인, 반복. 2~4회 렌더링 주기를 예상하세요 — 첫 번째 렌더링이 두 검사를 모두 통과하는 경우는 드뭅니다. 완료 기준: 두 검사 모두 깨끗하고, 이미지에 사과나 설명이 필요한 부분이 없습니다.

5단계 — 전달

  • 최종 .svg(및 .d2 소스) 경로를 확인하세요 — 항상 사용자에게 둘 다 제공하십시오. .d2가 편집 가능한 아티팩트입니다.
  • 다이어그램이 GitHub README나 문서 사이트에 포함될 경우, 다크 모드 대응 변형을 제공하세요: --dark-theme 200으로 재렌더링(독자의 색상 구성표를 따르는 단일 SVG). PNG/<picture> 임베딩 패턴은 references/diagram-patterns.md에 있습니다.
  • 사용자가 직접 다이어그램을 반복 수정할 경우, 브라우저에서 실시간 미리보기를 위해 d2 --watch input.d2를 언급하세요.

문제 해결

증상원인 / 해결책
d2: command not foundscripts/setup.sh 실행 (안내 설치)
D2_LAYOUT "tala" is not bundledTALA가 PATH에 없음 — 스크립트가 자동으로 ELK로 대체; 사용자가 원할 때만 TALA 설치
출력에 UNLICENSED 텍스트 표시라이선스 없는 TALA — 렌더 스크립트가 자동으로 ELK로 재렌더링; 라이선스 키는 TSTRUCT_TOKEN 또는 ~/.config/tstruct/auth.json에 입력
PNG 내보내기 실패, SVG는 정상첫 PNG 렌더링에서 헤드리스 브라우저를 다운로드; 한 번 재시도. 차단된 경우(오프라인/CI), SVG를 전달하고 사용 가능한 SVG 래스터라이저로 변환하여 검사
--layout tala에서 컴파일 오류, ELK는 정상 렌더링d2/TALA 버전 불일치 — 스크립트가 자동 대체; 두 도구 업데이트 권장
출력에서 아이콘 누락아이콘 URL이 403/404 반환 — 아이콘을 제거하거나 icons.terrastruct.com에서 다른 아이콘 선택; 아이콘은 일찍 테스트

관련 스킬