j99way99 Mermaid 다이어그램
설치 없이 Obsidian, GitHub, Claude 앱에서 바로 렌더링되는 다이어그램을 만든다. 보기 좋은 그림보다 틀리지 않은 그림이 목표다.
절차
- 질문을 하나로 좁힌다. 다이어그램 하나는 질문 하나에 답한다. "무엇으로 구성되나"와 "요청이 어떻게 흐르나"는 다른 질문이므로 다른 다이어그램으로 그린다.
- 유형을 고른다. (아래 표)
- 사실을 모은다. 이미 대화에 있는 내용과 프로젝트
CLAUDE.md를 먼저 쓴다. 부족할 때만 해당 코드를 읽는다. 확인하지 않은 구성 요소나 화살표를 추측해서 그리지 않는다. - 작성한다. (아래 작성 규칙)
- 렌더링을 검증한다. (아래 검증)
- 저장 위치를 정해 저장한다. (아래 저장)
유형 선택
| 질문 | 유형 |
|---|---|
| 무엇으로 구성되고 무엇이 무엇을 부르나 | flowchart (구성도) |
| 요청 하나가 시간 순서로 어떻게 흐르나, 분기는 무엇인가 | sequenceDiagram |
| 상태가 어떻게 바뀌나 | stateDiagram-v2 |
| 테이블/엔티티 관계 | erDiagram |
| 작업 절차, 의사결정 | flowchart (TB) |
흐름 설명은 구성도보다 시퀀스가 낫다. 구성도에 번호 붙은 화살표를 늘어놓기보다
구성도 1장 + 핵심 흐름 시퀀스 1~2장으로 나눈다. 성공/실패처럼 갈리는 지점은 alt / else 로 보여준다.
작성 규칙
공통
- 노드는 12개 이하. 넘으면 다이어그램을 나눈다.
- 라벨은 짧게. 코드 식별자, 명령, 프로토콜, 경로 이름은 원문 그대로 쓴다.
- 부가 정보는
<br/>로 둘째 줄에 둔다:api["Server Actions<br/>업로드 발급 · 완료"] - 괄호, 따옴표, 콜론 같은 특수문자가 들어간 라벨은 큰따옴표로 감싼다.
- 색·스타일은 의미가 있을 때만 쓴다 (예: 보안 경계, 저장소). 꾸미기용
classDef를 늘리지 않는다.
flowchart
- 방향은 주요 경로가 한 줄로 읽히게 고른다. 요청 경로는
LR, 절차는TB. - 배포 경계·권역·신뢰 경계는
subgraph로 묶는다. - 경계를 넘지 않는 흐름을 경계 안으로 그리지 않는다. 예: 브라우저가 스토리지로 직접 올리는 흐름은 서버 subgraph 바깥 노드끼리 잇는다. 그림만 보고 경로를 오해하게 만들지 않는다.
- 저장소는
[("...")](원통), 외부 사용자는 기본 사각형. - 선 종류로 의미를 구분한다:
-->동기 호출,-.->부수/비동기,==>강조할 핵심 경로. end를 노드 id 로 쓰지 않는다 (flowchart 가 깨진다).endNode처럼 바꾼다.
sequenceDiagram
participant X as 표시이름으로 짧은 id 를 쓴다.- 여러 단계가 이어지면
autonumber. - 응답은
-->>, 요청은->>. - 분기는
alt 조건/else 조건/end, 반복은loop. - 메시지 안에
;를 쓰지 않는다 (문장 끝으로 해석되어 깨진다).·나,로 바꾼다.
검증
Mermaid 는 문법이 틀리면 에러 없이 조용히 깨진다. 저장 전에 한 번은 렌더링을 확인한다.
python3 <이 skill 디렉터리>/scripts/render_check.py <파일.md 또는 .mmd> [--screenshot out.png]
- 파일 안의 모든
```mermaid블록을 headless Chrome 으로 렌더링하고 블록별 결과를 JSON 으로 준다. - exit 0 = 전부 성공 · 1 = 실패한 블록 있음 (몇 번째 블록, 몇째 줄인지 표시) · 2 = Chrome 없음
- Mermaid 를 jsdelivr 에서 받으므로 네트워크가 필요하다. 쓸 수 없으면 검증하지 못했다고 말한다.
--screenshot은 구성도의 레이아웃을 눈으로 봐야 할 때만 쓴다. 스크린샷을 읽는 비용이 크다.
실패하면 오류가 가리킨 줄만 고치고 다시 돌린다. 문법 검증을 통과해도 경계와 화살표 방향이 사실과 맞는지는 따로 확인한다. 렌더러는 의미를 검사하지 않는다.
검증하지 않은 다이어그램을 "렌더링된다"고 말하지 않는다.
저장
| 용도 | 위치 |
|---|---|
| 대화 중 설명 | 채팅에 코드 블록으로. 파일을 만들지 않는다 |
| 개인 노트 | 사용자가 지정한 노트 (Obsidian 등) |
| 저장소 문서 | 프로젝트의 문서 위치 (docs/, README.md 등). 프로젝트 CLAUDE.md 규칙을 따른다 |
- 저장소 루트에 임의로 파일을 만들지 않는다.
- 노트나 문서에는 다이어그램 위에 무엇에 답하는 그림인지 한 줄, 그리고 근거가 된 파일이나 노트 링크를 남긴다.
하지 말 것
- 코드에 없는 구성 요소를 "보통 이렇게 생겼으니까" 추가하기
- 한 장에 구성·흐름·상태를 모두 욱여넣기
- 레이아웃이 마음에 들지 않는다고 사실을 빼거나 화살표 방향을 바꾸기
— 대신 방향(
LR/TB), subgraph 묶음, 노드 순서를 바꾼다 - 렌더링 확인 없이 "완성"이라고 보고하기
프로젝트 고유의 문서 위치·다이어그램 규약이 있으면 그 프로젝트의 CLAUDE.md 가 우선한다.