---
name: diagram-craft
description: 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 — 실무급 다이어그램 산출 표준

## 불변식

1. **Abstraction-first.** 그리기 도구보다 *추상화 계층·독자·전달 메시지*를 먼저 정한다. 도구 선택은 마지막.
2. **One diagram, one message.** 한 그림은 한 독자에게 한 메시지만. 넘치면 쪼갠다.
3. **엔진 우선순위: 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 관용구 (실물 산출)

```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