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단계 — 작성 전 계획
먼저 세 가지를 결정합니다:
- 메시지. 독자가 5초 안에 무엇을 결론내길 바라는가? 다이어그램은 무언가를 주장합니다 — "요청이 여기로 분산된다", "이 서비스가 병목이다", "이 두 경로는 절대 만나지 않는다". 주장을 말할 수 없다면, 레이블이 붙은 상자 집합을 그리려는 것입니다.
- 유형. 아키텍처/토폴로지 → 기본 도형과 컨테이너. 시간에 따른 상호작용 →
sequence_diagram. 데이터 모델 →sql_table. 엄격한 정렬(매트릭스, 대시보드, 범례 중심) → 그리드. 유형별 구조 가이드는references/diagram-patterns.md를 참조하세요. - 규모. 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 found | scripts/setup.sh 실행 (안내 설치) |
D2_LAYOUT "tala" is not bundled | TALA가 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에서 다른 아이콘 선택; 아이콘은 일찍 테스트 |