llm-wiki/rules/diagram-standards.md

---
title: LLM Wiki Diagram Standards (컨퍼런스급 — Minimalist-first)
source_type: meta
status: stable
tags: [meta, diagram-standards]
last_reviewed: 2026-05-26
version: 2
---

# LLM Wiki Diagram Standards — 컨퍼런스급

본 표준은 **대기업 기술 컨퍼런스(Toss SLASH, Kakao if(dev), Naver DEVIEW) 발표 슬라이드 수준** 의 다이어그램 기준이다.

> **핵심 원칙: 적을수록 좋다 (Less is more).**
>
> 컨퍼런스 발표 슬라이드를 다시 생각해보면 — 좋은 다이어그램은 **단순**하다. 박스 5~8개, 화살표 5~7개, 핵심만. 정보를 다이어그램에 몰아넣으면 청중은 어디부터 봐야 할지 모르고 패닉한다.
>
> 본 표준은 **"포함해야 할 것"** 이 아니라 **"포함하지 말아야 할 것"** 중심이다.

---

# 0. 도구 분리 (변경 없음)

| 다이어그램 종류 | 도구 | 저장 위치 |
|---|---|---|
| **시스템 아키텍처 / 정적 구조** | **draw.io XML** (`.drawio`) | `raw/diagrams/<project-slug>/` |
| **시퀀스 (시간축)** | **Mermaid `sequenceDiagram`** | 본문 inline |
| **ER (데이터 모델, 선택)** | **Mermaid `erDiagram`** | 본문 inline |

위반 시 자동 BLOCKED.

---

# 1. The Two Tests — 5초·30초 룰

다이어그램 1장은 두 시간 기준을 통과해야 한다.

### 5초 룰

청중이 슬라이드를 본 지 **5초 안에** 다음을 이해해야 한다:
- **이게 무슨 시스템인가** (제목 + 시각적 게슈탈트)
- **어디부터 봐야 하나** (진입점)

5초 안에 위 두 가지를 답할 수 없으면 다이어그램이 너무 복잡한 것이다.

### 30초 룰

발표자가 다이어그램을 설명하는 30초 동안 청중이:
- **데이터 흐름 + 핵심 결정 1개** 를 이해해야 한다

30초가 부족하면 다이어그램에 정보가 너무 많은 것. 분할 또는 단순화.

### 실패 신호

- 청중이 다이어그램 자체를 읽느라 발표자 설명을 못 들음 → 정보 과잉
- 청중이 "어디를 봐야 하나요?" 질문 → 진입점 불명확
- 청중이 5초 안에 색·박스·화살표 의미를 추측해야 함 → 컨벤션 위반

---

# 2. The Question — 1 다이어그램 = 1 질문

모든 다이어그램은 **하나의 질문에만 답한다.**

좋은 질문 (구체적·단일 초점):
- "P3A 패턴에서 사용자 요청은 어떤 컴포넌트를 거치는가?"
- "Outbox 패턴에서 DB와 broker 발행이 어떻게 원자적으로 분리되는가?"

나쁜 질문:
- "전체 시스템 구조" — 범위 너무 큼. 다이어그램 분할 필요.

**여러 질문이 있다 → 다이어그램을 분할한다.** 1 mega 다이어그램에 모든 걸 담는 건 부정직 (kitchen sink anti-pattern).

---

# 3. Element Budget — 요소 수 상한 (HARD LIMITS)

| 요소 | 권장 | 상한 | 초과 시 |
|---|---|---|---|
| **Vertex (박스)** | 5~7개 | **10개** | 분할 또는 비핵심 제거 |
| **Edge (화살표)** | 4~6개 | **8개** | 시퀀스 다이어그램으로 분리 |
| **Callout (주석 박스)** | 0~1개 | **1개** | 본문 텍스트로 옮김 |
| **Boundary group** | 1~2개 | **3개** | 중첩 단계 축소 |
| **Legend 항목** | 3~4개 | **6개** | 표준 컨벤션 사용 (legend 생략) |
| **색상** | 2~3 가지 (회색/흑백 + 강조 1) | **4 가지** | 색 분류 축소 |

상한을 초과하면 다이어그램이 잘못된 단위에 있다. 분할 또는 추상화 레벨 올리기.

---

# 4. Component Label — 박스 안 텍스트 ≤ 2줄

```
┌─────────────────────────┐
│  <Name>                 │  ← 1줄: 시스템 이름 (Bold)
│  <Context 1줄>          │  ← 1줄: 역할 OR 기술. 둘 중 핵심만.
└─────────────────────────┘
```

예시:

| Bad (v2 스타일) | Good |
|---|---|
| `Spring Boot Resource Server`<br/>`Role: JWT 검증 + 비즈니스 API`<br/>`Stack: Spring Boot 3.4 / Java 21`<br/>`+ Spring Security 6.x`<br/>`Endpoint: localhost:8080`<br/>`Capacity: 1 instance`<br/>`Owner: 본인` (7줄) | `**Spring Boot RS**`<br/>`Spring Boot 3.4 · :8080` (2줄) |

**다이어그램에 안 들어가는 정보는 본문에**:
- 컴포넌트 상세 (역할, 책임, owner, capacity) → project-note 의 §"컴포넌트 책임 분담" 표
- 의존성 매트릭스 → 별도 §"외부 의존성" 표
- 운영 SLO → 별도 §"비기능 요구사항"

---

# 5. Edge Label — 화살표 라벨 ≤ 5단어

```
<step?> <verb/protocol> <object>
```

예시:

| Bad (v2 스타일) | Good |
|---|---|
| `① HTTPS GET / (HTML/JS)`<br/>`   payload: ~50KB (initial SPA bundle)`<br/>`   p99: ~80ms (cold) / ~10ms (cache)` (3줄) | `① GET /` (1줄) |
| `⑥ proxy_pass http://localhost:8080`<br/>`   Authorization header forward`<br/>`   (timeout: 30s, keepalive: 60s)` | `proxy_pass :8080` |

**스케일 어노테이션 (QPS, latency, payload size) 는 다이어그램의 질문이 *그것* 일 때만**:
- 일반 아키텍처 다이어그램: 화살표는 prototype + endpoint 만
- 성능 다이어그램: QPS / latency 가 핵심 → 그 때만 라벨에

번호 (①②③) 는 **순서가 중요할 때만**. 정적 토폴로지 다이어그램은 번호 불필요.

---

# 6. Visual Hierarchy Through Restraint — 색은 강조용

### 색 사용 비율

- **80% 회색/흑백** — 본문 박스의 기본 fill / stroke
- **15% 강조색 1개** — 다이어그램의 critical path 또는 primary system
- **5% 위험 / 경고색 (빨강)** — error path, SPoF, 보안 위협 — 있을 때만

### 표준 팔레트 (Minimal)

| 용도 | Fill | Stroke | 비고 |
|---|---|---|---|
| 일반 컴포넌트 (기본) | `#FFFFFF` | `#57606A` (회색) | 80% 의 박스가 여기 |
| **Critical path / 주인공** | `#FFFFFF` 또는 옅은 강조색 | **굵은 강조색** (`#1F6FEB` 파랑 또는 `#FB923C` 주황) | 다이어그램에서 가장 중요한 1~2개 박스만 |
| Data store (DB) | `#FFFFFF` | `#57606A` + cylinder shape | 모양으로 구분 |
| **External (점선)** | `#F6F8FA` | `#D0D7DE` (회색 점선) | 외부 시스템·3rd party |
| **Warning / Error path** | `#FEF2F2` (옅은 빨강) | `#DC2626` (빨강) | 있을 때만, 1~2 요소 한정 |

**금지**: 모든 박스에 색 칠하기. 색이 의미를 잃음 (color salad).

### Stroke 굵기

- 일반: 1~1.5px
- Critical path / Primary: 2~3px (강조용)
- Boundary: 1.5~2px

### 화살표 종류

| 종류 | 의미 |
|---|---|
| 실선 + 화살촉 | 동기 호출 (HTTP, RPC, JDBC) |
| 점선 + 화살촉 | 비동기 / fire-and-forget (Kafka publish, async event) |
| 굵은 실선 (2~3px, 강조색) | Critical path / hot path |
| 빨간 점선 | Error path |

화살표 종류는 **다이어그램 내 일관성** 이 핵심. 4종류 이상 섞지 말 것.

---

# 7. Boundary — 정보 있을 때만 사용

Boundary 는 **시각 장식이 아님.** 다음 중 하나일 때만 사용:

- **Trust Boundary**: 인증·인가 영역 분리 (파란 실선, 옅은 파란 배경)
- **Network Boundary**: VPC / 서브넷 / public-private (회색 점선)
- **External**: 외부 시스템 영역 (회색 점선)

### 금지

- 모든 컴포넌트가 1개 boundary 안에 있음 → boundary 가 정보 0. 제거.
- 3 단계 이상 중첩 boundary → 시각 복잡도 폭증
- "팀 소유권" 같은 다이어그램 핵심이 아닌 분류 → 다이어그램 외부 본문 표로

---

# 8. Callout — 1개만, 진짜 비자명한 것에만

Callout 박스는 **다이어그램의 시각 요소로 표현 불가능한 핵심 1가지** 에만 사용.

### 좋은 callout

- 비자명한 함정 (e.g., "KC_HOSTNAME 미설정 시 JWT iss mismatch")
- 핵심 결정의 이유 (e.g., "왜 BFF 대신 SPA-direct? — 학습 환경 단순성")
- 보안 위협 영역 (e.g., "JWKS unknown kid → DoS 벡터")

### 나쁜 callout (제거 대상)

- 단순 부가 정보 (capacity, version 등) → 박스 라벨로
- 컴포넌트 설명 → 본문 텍스트로
- "참고로..." 식 비핵심 메모 → 본문으로

**1개 이상의 callout → 다이어그램이 너무 많은 것을 말하려는 것. 분할.**

---

# 9. Legend — 표준 컨벤션이면 생략

Legend 는 **다이어그램 내 비표준 색·기호** 가 있을 때만.

### 표준 컨벤션 (Legend 불필요)

- 점선 = 외부 / 비동기
- Cylinder = DB
- Solid arrow = 동기 호출
- Dashed arrow = 비동기 / 점선 응답

### Legend 가 필요한 경우

- 다이어그램 내 색이 **§6 표준 팔레트 외** 인 경우
- 특수 기호 사용 (예: ⚡ for circuit breaker)

### Legend 작성 표준

- ≤ 6 항목 (가능하면 ≤ 4)
- 다이어그램 우하단 또는 본문 캡션
- 표준 컨벤션 (점선=외부, cylinder=DB) 은 legend 에 안 적음

---

# 10. Header / Footer — 미니멀

### Header (다이어그램 상단)

```
<Title>
<답하는 질문 1줄>  ← 옵션
```

`Project / branch / status` 같은 메타 정보는 **다이어그램에 안 들어감**. project-note frontmatter 와 §3 본문에 이미 있음.

### Footer (다이어그램 하단)

```
v2 · 2026-05-26
```

작성자 / source wikilink / standard reference 같은 메타는 **다이어그램 외부**. project-note 의 frontmatter `diagrams:` 필드와 본문에서 참조.

---

# 11. Source 인용 — 본문에서, 다이어그램 안 X

핵심 사실의 출처 wikilink (`[[raw/official-docs/...]]`) 는 **다이어그램 옆 본문 또는 callout** 에 둔다. 화살표 라벨이나 박스 안에 wikilink 를 욱여넣지 말 것.

```markdown
![[architecture-p3a-...drawio]]

> **출처**:
> - KC_HOSTNAME 함정: [[raw/branch-notes/feature-keycloak-iss-claim-hostname-mismatch]]
> - redirect_uri 함정: [[raw/branch-notes/feature-keycloak-docker-compose-stack]]
> - OIDC PKCE: [[raw/official-docs/oauth2-pkce-rfc-7636]]
```

본문이 다이어그램을 보강한다. 다이어그램이 본문 역할까지 떠안지 말 것.

---

# 12. Mermaid Sequence — Minimal

- **메시지 ≤ 8개** (초과 시 분할)
- **`autonumber` 활성화**
- **에러 경로 1개** (alt/else)
- **트랜잭션 경계 1개** (Note over, 있을 때만)
- **지연·QPS 어노테이션 금지** (시퀀스의 질문이 *성능* 일 때만)

```mermaid
sequenceDiagram
    autonumber
    actor User
    participant FE
    participant API
    participant DB

    User->>FE: 로그인
    FE->>API: POST /login
    API->>DB: SELECT user
    DB-->>API: row
    alt 자격 증명 유효
        API-->>FE: 200 + token
    else 자격 증명 무효
        API-->>FE: 401
    end
```

이게 끝. `Note over` 도 비자명한 동작 1개에만.

---

# 13. Mermaid ER — Minimal

- **엔터티 ≤ 8개** (over-engineering 안 함)
- **PK / FK 표시 필수**
- **컬럼 ≤ 4개 per 엔터티** (모든 컬럼 X)
- **카디널리티 정확** (`||--o{` 1:N, `}o--o{` M:N)
- **관계 라벨 동사**

전체 스키마는 별도 ERD 도구 (DBeaver, dbdiagram.io) 로. project-note 의 ER 은 **핵심 엔터티 + 관계** 만.

---

# 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개라도 미달 → 다이어그램이 너무 많은 일을 하려는 것 → 분할 또는 단순화.

---

# 15. Anti-patterns — 절대 금지

| 안티패턴 | 증상 | 고치는 법 |
|---|---|---|
| **Kitchen sink** | 모든 정보를 다이어그램에 몰아넣음 (vertex 15+, edge 12+, callout 3+) | 분할 또는 본문으로 정보 이동 |
| **Color salad** | 모든 박스에 색 칠함. 색이 의미를 잃음 | 80% 회색/흑백, 강조 1~2개만 |
| **Legend bloat** | 사용된 모든 요소를 legend 에 → legend 가 다이어그램만큼 큼 | 표준 컨벤션은 legend 생략 |
| **Component bloat** | 박스마다 5+줄 텍스트 → 청중이 박스 하나 읽는 데 5초+ | 박스 2줄, 나머지는 본문 |
| **Edge label bloat** | 화살표마다 3줄 라벨 (QPS / latency / payload / step) | 1줄 5단어 이내 |
| **Callout salad** | 3+ callout 박스 → 어느 게 중요한지 모름 | 1개 (가장 중요한 함정만), 나머지 본문으로 |
| **Boundary nesting** | 3+ 중첩 boundary | 1~2 단계로 평면화 |
| **Numbered everywhere** | 모든 화살표에 번호 (필요 없는데도) | 순서가 중요할 때만 번호 |
| **Required-by-rule additions** | "표준이 시킨다고" 모든 칸 채움 → 필요 없는 정보 포함 | 표준의 목적은 *정보 전달*, 칸 채우기 X |
| **Scale annotation everywhere** | 모든 화살표에 QPS·latency | 다이어그램의 질문이 *성능* 일 때만 |
| **Mermaid `graph TD` 로 아키텍처** | 도구 선택 위반 | draw.io 사용 |
| **draw.io 로 시퀀스** | 도구 선택 위반 | Mermaid `sequenceDiagram` |
| **다이어그램이 본문 역할까지** | 다이어그램 안에 wikilink, 설명, 출처 다 들어감 | 다이어그램 = 시각 요약. 디테일·출처 = 본문 |

---

# 16. 컨퍼런스급 사례 (참고)

좋은 다이어그램의 공통점 (Toss SLASH / Kakao if(dev) / Naver DEVIEW 슬라이드 분석):

- 박스 5~8개 (10 초과 드묾)
- 박스 안 텍스트 1~2줄 (대부분 1줄)
- 화살표 라벨 1~5단어
- 색 2~3가지 (대부분 무채색 + 강조 1)
- Legend 종종 없음 (관례면 충분)
- **본문 / 발표자 설명이 다이어그램을 보강**

다이어그램은 발표자의 보조 도구 — 발표자의 입을 대체하지 않는다.

---

# 17. Quick Reference (작성 직전 빠른 체크)

```
□ 1 다이어그램 = 1 질문 (헤더에 명시)
□ 박스 ≤ 10, 화살표 ≤ 8, callout ≤ 1, legend ≤ 6
□ 박스 라벨 ≤ 2줄
□ 화살표 라벨 ≤ 5단어
□ 80% 회색/흑백, 강조색 ≤ 2개
□ Boundary 는 정보 있을 때만
□ 표준 컨벤션이면 legend 생략 (점선=외부, cylinder=DB)
□ 다이어그램 외부 본문에 출처 wikilink + 디테일
□ 5초 룰 + 30초 룰 통과
□ 박스 / 화살표 / 색 / 라벨 모두 컨벤션 일관
```