2. 우리의 시각화 컨벤션
이 시리즈를 통해 배운 것들을 우리 프로젝트에 적용하는 규칙입니다.
1. 기본 도구
| 용도 | 도구 | 이유 |
|---|---|---|
| 문서 속 다이어그램 | Mermaid | Git diff, GitHub 자동 렌더링, AI 생성 |
| 아이디어 스케치 | Excalidraw | 빠르게, 대충, 부담 없이 |
| 공식 아키텍처 | draw.io | 필요할 때만. 정밀 배치 |
| 마인드맵 | Markmap | 마크다운 기반, Git 관리 |
2. 다이어그램 규칙
방향
- 위 → 아래 (기본)
- 왼 → 오 (타임라인일 때만)
노드 이름
- 동사로 시작 ("결제 요청", "본인 인증 수행")
- 추상적 이름 금지 ("Step 1", "Process A")
색상
- 기호 종류 구분에만 사용 (양 표현 금지)
- 프로젝트 색상 팔레트 따르기
- 기호 종류 6개 이내
분기
- 마름모 안에 질문 ("결제 성공?")
- 화살표에 조건 텍스트 ("Yes", "No", "미참여")
메타
- 제목 필수
- 날짜 필수
- 생략한 부분은 표시
3. 파일 관리
docs/diagrams/ ← 다이어그램 파일 모음
├── *.md ← Mermaid (문서에 포함)
├── *.excalidraw ← Excalidraw
└── *.drawio ← draw.io (필요할 때만)
4. 언제 다이어그램을 만드는가
- 새로운 플로우를 팀에 공유할 때
- PR에서 변경 사항의 전후를 보여줄 때
- 복잡한 로직을 설명할 때
- "말로 설명하다가 3분이 넘으면" → 다이어그램
5. 언제 안 만드는가
- 순서가 3단계 이하일 때 (글로 충분)
- 이미 있는 다이어그램과 동일할 때 (링크로 참조)
- "예쁘게 만들어야 해서" → 목적 없이 만들지 않기
이 시리즈는 여기까지. 새로운 시각화 도구를 테스트하거나 기준을 업데이트하면 이 문서를 갱신합니다.