feat: 공식 문서 근거자료, 브랜치 기능 문서 작성

2026-07-29 18:05:17 +09:00
parent cfd84875bf
commit 58515ab0f3
251 changed files with 31470 additions and 109 deletions
@@ -0,0 +1,51 @@
+# Diagram Principles — The Two Tests + The Question
+
+Root SSOT: [`rules/diagram-standards.md`](../../../../../rules/diagram-standards.md) §1~§2
+parent: [`README.md`](README.md)
+
+## §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).
+
+다이어그램이 답하는 질문은 다이어그램 **헤더에 한 줄로 명시**한다:
+
+```
+<Title>
+<답하는 질문 1줄>  ← 이게 5초 룰의 핵심
+```