4.1 KiB
4.1 KiB
name, description
| name | description |
|---|---|
| diagram-craft | Use when producing ANY technical diagram (software architecture, dependency graphs, flows, C4, sequence) — picks the abstraction level and audience FIRST, then renders with D2 (professional diagram-as-code) as primary engine and Excalidraw for explanatory sketches. Mermaid is a last-resort fallback only; it is not a professional-grade visual. |
Diagram Craft — 실무급 다이어그램 산출 표준
불변식
- Abstraction-first. 그리기 도구보다 추상화 계층·독자·전달 메시지를 먼저 정한다. 도구 선택은 마지막.
- One diagram, one message. 한 그림은 한 독자에게 한 메시지만. 넘치면 쪼갠다.
- 엔진 우선순위: D2 → Excalidraw → Mermaid(폴백). Mermaid로 보여주는 건 실무급 시각자료가 아니다 — 자제하라.
1단계 — 추상화 계층 정하기 (C4)
| 레벨 | 무엇 | 언제 |
|---|---|---|
| L1 System Context | 시스템 + 외부 관계(사용자·외부시스템) | 스코프 정렬, 비개발자 포함 |
| L2 Container | 배포 단위 + 기술 스택 | 가장 범용 — 기본값 |
| L3 Component | 컨테이너 내부 구조 | 정말 복잡할 때만 |
| L4 Code | 클래스/함수 | 손유지 금지 — 소스에서 자동생성(즉시 stale) |
독자를 먼저 적어라. "이 그림은 누가, 무엇을 알기 위해 보나?" 답이 없으면 그리지 마라.
2단계 — 엔진 선택
소프트웨어 아키텍처 · 의존성 · 중첩 컨테이너 · 시퀀스 → D2 (1급)
설명용 · 워크숍 발산 · 손그림 느낌 · 개념 스케치 → Excalidraw (보조)
정말 어쩔 수 없을 때(경량·플랫폼 네이티브가 유일 제약) → Mermaid (폴백)
왜 D2인가: 중첩 컨테이너(계층/경계 표현), 레이아웃 엔진 교체(dagre 기본 / elk 대형그래프 / tala 복잡), 테마, sketch 모드, SVG/PNG CLI(CI 친화) — Mermaid가 못 하는 것들.
3단계 — D2 관용구 (실물 산출)
direction: right # 방향 고정 (right/down)
vars: { d2-config: { layout-engine: elk } } # 큰 그래프는 elk
domain: 도메인 계층 { # 중첩 컨테이너로 계층/경계를 표현
entity: Entity
vo: Value Object
}
app: 애플리케이션 계층 {
usecase: UseCase
}
infra: 인프라 계층 {
repo: JPA Repository
}
app.usecase -> domain.entity: 사용 # 엣지에 라벨(의미)
infra.repo -> app.usecase: 구현(의존역전) { style.stroke-dash: 3 }
렌더:
- 렌더러 경유(권장): storyline exhibit에
{type: d2, code: "...", layout: elk}→render_consult.py가 d2 CLI로 실물 SVG. - 직접:
d2 --theme 0 --pad 16 [--layout elk] [--sketch] in.d2 out.svg(바이너리:~/.local/bin/d2).
D2 옵션: --theme 0(Neutral), --layout elk(대형), --sketch(손그림 느낌), 컨테이너는 name { ... }, 방향은 direction:.
4단계 — notation 규율
- 그림마다 스코프 한 줄 제목 + 범례 + 일관된 방향 + 예약색(색은 의미 전용, 장식 금지).
- shape/arrow에 의미를 고정하라(예: 실선=동기 호출, 점선=의존역전/비동기). 범례에 명시.
Anti-cheap-diagram self-check
- 독자와 한 메시지를 한 문장으로 쓸 수 있나?
- C4 레벨을 의식적으로 골랐나(기본 L2)?
- Mermaid로 도망치지 않았나? 아키텍처/의존성이면 D2여야 한다.
- 범례·방향·예약색이 있나?
- 요소가 넘치나? → 두 그림으로 쪼개라.
Excalidraw (보조 — 설명·발산)
.excalidraw JSON으로 산출(VS Code Excalidraw 확장·excalidraw.com에서 편집). 그리드 정렬(50–100px 배수)·roughness로 손그림 강도 조절. 확정·유지 대상은 D2로, 손그림은 발산·워크숍에만.
근거 (E3)
- D2 vs Mermaid(컨테이너·레이아웃엔진·테마): https://diagram-converter.orriguii.com/blog/d2-diagram-language-guide
- D2 공식: https://d2lang.com/
- C4 model: https://c4model.com/
- Excalidraw 아키텍처 다이어그램: https://plus.excalidraw.com/use-cases/software-architecture-diagram