숏컷 코드

```mermaid
flowchart TD
  A[요청] --> B{검증}
  B -->|통과| C[저장]
  B -->|실패| D[오류]
```

문법

mermaid 언어 코드 블록으로 다이어그램을 선언한다

Mermaid 다이어그램은 일반적으로 fenced code block의 언어를 mermaid로 지정해 작성합니다. GitHub처럼 Mermaid 렌더링을 지원하는 환경에서는 코드 블록이 SVG 다이어그램으로 변환되고, 지원하지 않는 렌더러에서는 코드 블록 그대로 표시됩니다. 따라서 문서가 어느 환경에서 읽히는지에 따라 결과가 달라질 수 있습니다.

```mermaid
sequenceDiagram
  participant User
  participant API
  User->>API: 요청
  API-->>User: 응답
```

Markdown 문법 입장에서는 이것도 코드 블록입니다. 실제 다이어그램 해석은 Markdown parser가 아니라 Mermaid renderer가 담당합니다.

다이어그램 타입마다 문법이 다르다

Mermaid는 flowchart, sequenceDiagram, classDiagram, stateDiagram, erDiagram, gantt 등 여러 다이어그램 타입을 제공합니다. 타입 이름이 첫 줄에 오고, 그 뒤 문법은 타입마다 다릅니다. flowchart의 화살표 문법을 sequence diagram에 그대로 쓸 수 없고, class diagram의 관계 표기도 별도 문법을 따릅니다.

작은 흐름은 flowchart가 가장 범용적입니다. 호출 순서가 핵심이면 sequence diagram, 데이터 관계가 핵심이면 ER diagram, 상태 전이가 핵심이면 state diagram이 더 읽기 쉽습니다.

문서 보조 수단으로 쓰고 원본 정보는 텍스트로도 남긴다

Mermaid는 구조를 빠르게 이해시키는 데 좋지만, 다이어그램만으로 중요한 요구사항을 전달하면 검색성과 접근성이 떨어집니다. 핵심 단계, 예외, 용어는 본문에도 짧게 남겨야 합니다. 특히 GitHub 외부로 문서를 복사하거나 PDF로 변환하는 환경에서는 Mermaid가 렌더링되지 않을 수 있습니다.

복잡한 아키텍처 전체를 한 그림에 넣기보다, 독자가 한 번에 판단해야 하는 경계만 다이어그램으로 분리하는 편이 낫습니다. 노드가 15개를 넘어가면 텍스트 표나 여러 개의 작은 다이어그램으로 나누는 것을 검토합니다.

선택 기준

주의할 점

문법 오류가 있으면 전체 다이어그램이 렌더링되지 않습니다. 변경 후에는 실제 렌더링 화면에서 확인하고, 노드 라벨에 특수 문자가 많으면 따옴표나 단순한 라벨로 줄여서 parser 충돌을 피합니다.