diagram-explainer

Diagram Explainer

기술 개념을 설명할 때 텍스트만 쓰면 추상적이다. ASCII 다이어그램으로 "지금 어떤 상태인지", "무슨 일이 일어나는지", "고치면 어떻게 되는지"를 보여줘라.

설명 구조

1단계 — 현재 상황 다이어그램 지금 어떻게 생겼는지를 박스와 화살표로 그린다.

2단계 — 무슨 일이 생기는지 이벤트/액션 → 결과를 화살표로 연결해서 흐름을 보여준다.

3단계 — 해결책 다이어그램 (해당할 때) 고치면 구조가 어떻게 달라지는지 비교해서 보여준다.

4단계 — 한 줄 요약 다이어그램 아래에 핵심만 1-2줄로 정리.

---

다이어그램 규칙

박스 그리기

  [컴포넌트 이름]
  ┌─────────────────────┐
  │ 속성1: 값            │  ← 오른쪽에 설명 레이블 붙임
  │ 속성2: 값            │
  └─────────────────────┘

흐름/이벤트 표현

  이벤트 발생 → 결과 설명
  다음 단계 → 또 다른 결과

관계 표현

  [A] ──────────▶ [B]        연결/의존
  [A] ─────────── [B]        양방향 참조
  [A]      ↑                 원인-결과
           │ 
  이벤트 발생

전/후 비교

  [수정 전]                    [수정 후]
  ┌──────────┐                ┌──────────┐  ┌──────────┐
  │          │                │          │  │ 새 요소   │
  └──────────┘                └──────────┘  └──────────┘

---

자주 쓰는 패턴

자세한 패턴은 references/diagram-patterns.md 참고.

---

실제 예시 — Docker 볼륨 없을 때

나쁜 예 (다이어그램 없이)

Redis는 인메모리 저장소라서 컨테이너가 꺼지면 데이터가 없어집니다.

좋은 예 (이 스킬 적용)

지금 상황:

  [Redis 컨테이너]
  ┌─────────────────────┐
  │ tags:trending       │  ← 메모리에만 존재
  │   #갓생  score: 42  │
  │   #공부  score: 38  │
  └─────────────────────┘

  docker-compose down 하는 순간 → 박스 통째로 날아감
  docker-compose up 하면 → 새 박스, 데이터 없음


볼륨 추가 후:

  [Redis 컨테이너]          [redis_data 볼륨]
  ┌─────────────────────┐   ┌──────────────────┐
  │ tags:trending       │──▶│ dump.rdb (파일)  │
  │   #갓생  score: 42  │   │ appendonly.aof   │
  └─────────────────────┘   └──────────────────┘

  docker-compose down → 컨테이너는 삭제되지만 볼륨 파일은 디스크에 남음
  docker-compose up → 새 컨테이너가 볼륨 파일 읽어서 데이터 복구

한 줄 요약: 볼륨은 컨테이너 바깥에 만들어두는 외부 저장소. 박스가 사라져도 내용물은 남는다.

---

언제 다이어그램이 필요한가

다이어그램을 그려야 할 때:

• 컴포넌트가 2개 이상 관계를 맺는 구조 설명
• "왜 X가 일어나는가" — 원인-결과 흐름
• "A와 B의 차이" — 비교
• "수정 전/후" — 변화
• "데이터가 어디서 어디로 가는가" — 흐름

다이어그램 없이 텍스트만 써도 되는 경우:

• 단순 정의 ("JWT는 JSON Web Token의 약자다")
• 코드 스니펫 설명
• 사용자가 이미 구조를 알고 세부 사항만 묻는 경우