75 lines
4.2 KiB
Markdown
75 lines
4.2 KiB
Markdown
# diagram-standards (plugin split)
|
|
|
|
Root SSOT: [`rules/diagram-standards.md`](../../../../../rules/diagram-standards.md) (379줄, v2 minimalist)
|
|
|
|
본 폴더는 root rule 을 Antigravity 컨텍스트에서 lazy-load 하기 좋게 5개 sub-file 로 분할한 사본이다. 의미는 root 와 동일. 충돌 시 root 가 진실.
|
|
|
|
## 핵심 원칙
|
|
|
|
> **적을수록 좋다 (Less is more).**
|
|
>
|
|
> 컨퍼런스 발표 슬라이드 (Toss SLASH, Kakao if(dev), Naver DEVIEW) 수준 — 박스 5~8개, 화살표 5~7개, 핵심만. 정보를 다이어그램에 몰아넣으면 청중은 어디부터 봐야 할지 모르고 패닉한다.
|
|
>
|
|
> 본 표준은 **"포함해야 할 것"** 이 아니라 **"포함하지 말아야 할 것"** 중심이다.
|
|
|
|
## 도구 분리 (필독)
|
|
|
|
| 다이어그램 종류 | 도구 | 저장 위치 |
|
|
|---|---|---|
|
|
| **시스템 아키텍처 / 정적 구조** | **draw.io XML** (`.drawio`) | `raw/diagrams/<project-slug>/` |
|
|
| **시퀀스 (시간축)** | **Mermaid `sequenceDiagram`** | 본문 inline |
|
|
| **ER (데이터 모델, 선택)** | **Mermaid `erDiagram`** | 본문 inline |
|
|
|
|
위반 시 자동 `BLOCKED`. Mermaid `graph TD/LR` 로 아키텍처 작성 → draw.io 로 이관 필요.
|
|
|
|
## Sub-file index
|
|
|
|
| Sub-file | 다루는 root section | 필독 시점 |
|
|
|---|---|---|
|
|
| [`principles.md`](principles.md) | §1 The Two Tests (5초·30초 룰) + §2 The Question (1 다이어그램 = 1 질문) | 다이어그램 설계 시작 직전 |
|
|
| [`elements.md`](elements.md) | §3 Element Budget (vertex/edge/callout 상한) + §4 Component Label + §5 Edge Label + §6 Visual Hierarchy (색 / stroke / 화살표) | 박스·화살표·색 결정 시 |
|
|
| [`structure.md`](structure.md) | §7 Boundary + §8 Callout + §9 Legend + §10 Header/Footer + §11 Source 인용 | 구조 요소 (boundary, callout, legend) 추가 시 |
|
|
| [`mermaid.md`](mermaid.md) | §12 Mermaid Sequence + §13 Mermaid ER | Mermaid 시퀀스 / ER 다이어그램 작성 시 |
|
|
| [`anti-patterns.md`](anti-patterns.md) | §15 Anti-patterns + §16 컨퍼런스급 사례 | 작성 후 self-review 시 |
|
|
|
|
## §14 Self-check — 컨퍼런스급 (재작성, 8항만)
|
|
|
|
다이어그램 작성 후 모두 ✓ 여야 발표 가능 수준.
|
|
|
|
- [ ] **5초 룰** — 5초 안에 "무슨 시스템인가" + "진입점" 이해 가능?
|
|
- [ ] **30초 룰** — 30초 발표로 흐름 + 핵심 결정 1개 전달 가능?
|
|
- [ ] **요소 수 상한** — Vertex ≤ 10, Edge ≤ 8, Callout ≤ 1, Legend ≤ 6?
|
|
- [ ] **단일 질문** — 다이어그램이 답하는 질문이 1개로 명확?
|
|
- [ ] **박스 라벨 ≤ 2줄, 화살표 라벨 ≤ 5단어?**
|
|
- [ ] **80% 회색/흑백 + 강조색 ≤ 2** ? (color salad 없음)
|
|
- [ ] **Boundary 정보 있을 때만** (장식용 boundary 없음)?
|
|
- [ ] **본문/캡션** 이 다이어그램을 보강 (다이어그램에 안 들어간 정보 본문에 있음)?
|
|
|
|
8/8 ✓ → 컨퍼런스 발표 가능. 1개라도 미달 → 다이어그램이 너무 많은 일을 하려는 것 → 분할 또는 단순화.
|
|
|
|
## §17 Quick Reference (작성 직전 빠른 체크)
|
|
|
|
```
|
|
□ 1 다이어그램 = 1 질문 (헤더에 명시)
|
|
□ 박스 ≤ 10, 화살표 ≤ 8, callout ≤ 1, legend ≤ 6
|
|
□ 박스 라벨 ≤ 2줄
|
|
□ 화살표 라벨 ≤ 5단어
|
|
□ 80% 회색/흑백, 강조색 ≤ 2개
|
|
□ Boundary 는 정보 있을 때만
|
|
□ 표준 컨벤션이면 legend 생략 (점선=외부, cylinder=DB)
|
|
□ 다이어그램 외부 본문에 출처 wikilink + 디테일
|
|
□ 5초 룰 + 30초 룰 통과
|
|
□ 박스 / 화살표 / 색 / 라벨 모두 컨벤션 일관
|
|
```
|
|
|
|
## Antigravity-specific 메모
|
|
|
|
| 항목 | 컨텍스트 |
|
|
|---|---|
|
|
| 도구 분리 (Mermaid `graph TD` 로 아키텍처 작성 → BLOCKED) | hook 미커버 — `.drawio` write 시 도구 검증 없음. agent self-check 단독. |
|
|
| Element budget (Vertex ≤ 10 등) | hook 미커버. `wiki-diagram-reviewer` agent 가 dispatch 시 채점 (≥95/100 PASS). |
|
|
| 컨퍼런스급 self-check 8항 | hook 미커버. 모든 다이어그램 작성 후 agent 자체 검증 + 사용자 리뷰. |
|
|
| Source 인용 wikilink (§11) | hook 미커버. 다이어그램 안에 wikilink 욱여넣기 금지는 self-check 단독. |
|
|
|
|
자세한 채점은 `wiki-diagram-reviewer` agent dispatch — `.agents/plugins/wiki-superpowers/agents/wiki-diagram-reviewer.md` 참조.
|