donghyeon.kang/llm-wiki

Fork 0

Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

14 KiB

Raw Blame History

title, source_type, status, tags, last_reviewed, version

title

source_type

status

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` `Role: JWT 검증 + 비즈니스 API` `Stack: Spring Boot 3.4 / Java 21` `+ Spring Security 6.x` `Endpoint: localhost:8080` `Capacity: 1 instance` `Owner: 본인` (7줄)	`Spring Boot RS` `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)` `payload: ~50KB (initial SPA bundle)` `p99: ~80ms (cold) / ~10ms (cache)` (3줄)	`① GET /` (1줄)
`⑥ proxy_pass http://localhost:8080` `Authorization header forward` `(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 를 욱여넣지 말 것.

![[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 어노테이션 금지 (시퀀스의 질문이 성능 일 때만)

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초 룰 통과
□ 박스 / 화살표 / 색 / 라벨 모두 컨벤션 일관

14 KiB Raw Blame History