84 lines
4.1 KiB
Markdown
84 lines
4.1 KiB
Markdown
---
|
||
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
|