---

name: mermaid-diagram description: Mermaid CLI를 사용하여 다이어그램을 생성합니다. 플로우차트, 시퀀스 다이어그램, ER 다이어그램 등 복잡한 논리 흐름에 적합합니다.

Mermaid CLI 다이어그램 스킬

Mermaid 문법을 사용하여 다이어그램을 생성하고 SVG/PNG로 변환합니다.

언제 이 방식을 사용하는가?

장점

• 텍스트 기반 문법으로 빠른 작성
• 자동 레이아웃 (노드 배치 자동화)
• 복잡한 분기/조건 표현 용이
• 시퀀스 다이어그램 특화
• Git 버전 관리 용이
• 20개 이상의 다이어그램 유형 지원

단점

• 세밀한 레이아웃 조정 어려움
• 커스텀 스타일 제한적
• Mermaid CLI 설치 필요
• 한글 폰트 렌더링 이슈 가능

사전 요구사항

Copy# Mermaid CLI 설치
npm install -g @mermaid-js/mermaid-cli

# 확인
mmdc --version

파일 구조

Copycs/{category}/
├── {document}.md                    # 마크다운 문서
└── images/
    ├── {diagram-name}.mmd           # Mermaid 소스 (선택)
    └── {diagram-name}.svg           # 생성된 SVG

---

지원 다이어그램 전체 목록

기본 다이어그램

고급 다이어그램

---

Diagram Syntax 레퍼런스

1. Flowchart (플로우차트)

가장 많이 사용되는 다이어그램. 프로세스 흐름, 의사결정, 시스템 구조 표현.

Copyflowchart TD
    A[시작] --> B{조건}
    B -->|Yes| C[처리 1]
    B -->|No| D[처리 2]
    C --> E[종료]
    D --> E

방향 옵션:

노드 형태:

연결선:

Subgraph (그룹핑):

Copygraph TB
    subgraph Frontend
        A[React] --> B[Redux]
    end
    subgraph Backend
        C[Spring] --> D[JPA]
    end
    B --> C

---

2. Sequence Diagram (시퀀스 다이어그램)

API 호출, 시스템 간 통신 흐름 표현에 적합.

CopysequenceDiagram
    participant C as Client
    participant S as Server
    participant D as Database

    C->>S: HTTP Request
    activate S
    S->>D: Query
    activate D
    D-->>S: Result
    deactivate D
    S-->>C: HTTP Response
    deactivate S

화살표 유형:

고급 기능:

CopysequenceDiagram
    autonumber
    participant A as Client
    participant B as Server

    A->>B: 요청

    alt 성공
        B-->>A: 200 OK
    else 실패
        B-->>A: 500 Error
    end

    loop 재시도 (3회)
        A->>B: 재요청
    end

    opt 선택적 처리
        B->>B: 로깅
    end

    par 병렬 처리
        B->>C: 요청1
    and
        B->>D: 요청2
    end

    Note over A,B: 통신 완료

---

3. Class Diagram (클래스 다이어그램)

CopyclassDiagram
    class User {
        -Long id
        -String name
        #String email
        +getName() String
        +setName(name) void
    }

    class Order {
        -Long id
        -List~Item~ items
        +addItem(item) void
        +getTotal()$ BigDecimal
    }

    User "1" --> "*" Order : places

접근 제어자:

관계 표현:

---

4. State Diagram (상태 다이어그램)

CopystateDiagram-v2
    [*] --> Pending
    Pending --> Processing : submit
    Processing --> Completed : success
    Processing --> Failed : error
    Failed --> Processing : retry
    Completed --> [*]

복합 상태:

CopystateDiagram-v2
    [*] --> Active

    state Active {
        [*] --> Running
        Running --> Paused : pause
        Paused --> Running : resume
    }

    Active --> Stopped : stop
    Stopped --> [*]

---

5. ER Diagram (개체 관계 다이어그램)

CopyerDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : contains
    PRODUCT ||--o{ ORDER_ITEM : "ordered in"

    USER {
        long id PK
        string name
        string email UK
        datetime created_at
    }

    ORDER {
        long id PK
        long user_id FK
        string status
        datetime created_at
    }

관계 표기:

속성 키:

---

6. Gantt Chart (간트 차트)

Copygantt
    title 프로젝트 일정
    dateFormat YYYY-MM-DD
    excludes weekends

    section 기획
    요구사항 분석    :done,    des1, 2024-01-01, 7d
    설계 문서 작성   :active,  des2, after des1, 5d

    section 개발
    백엔드 개발     :         dev1, after des2, 14d
    프론트엔드 개발  :         dev2, after des2, 14d

    section 테스트
    통합 테스트     :         test1, after dev1, 7d
    배포           :milestone, deploy, after test1, 0d

태스크 상태:

---

7. GitGraph (Git 그래프)

CopygitGraph
    commit id: "Initial"
    branch develop
    checkout develop
    commit id: "Feature A"
    commit id: "Feature B"
    checkout main
    merge develop id: "Merge develop"
    commit id: "Hotfix"
    branch release
    checkout release
    commit id: "Release prep"
    checkout main
    merge release id: "v1.0.0" tag: "v1.0.0"

---

8. Mindmap (마인드맵)

Copymindmap
  root((시스템 설계))
    확장성
      수평 확장
        로드밸런싱
        샤딩
      수직 확장
    가용성
      이중화
      장애 조치
    성능
      캐싱
      CDN

---

9. Timeline (타임라인)

Copytimeline
    title 기술 발전 역사
    section 2000년대
        2004 : Gmail 출시
        2006 : AWS 출시
    section 2010년대
        2013 : Docker 출시
        2014 : Kubernetes 출시
    section 2020년대
        2022 : ChatGPT 출시

---

10. Quadrant Chart (사분면 차트)

기술 평가, 우선순위 매트릭스, 의사결정에 활용.

CopyquadrantChart
    title 기술 평가 매트릭스
    x-axis 구현 난이도 낮음 --> 구현 난이도 높음
    y-axis 비즈니스 가치 낮음 --> 비즈니스 가치 높음
    quadrant-1 즉시 구현
    quadrant-2 전략적 투자
    quadrant-3 빠른 개선
    quadrant-4 재검토 필요
    캐싱: [0.3, 0.8]
    마이크로서비스: [0.8, 0.9]
    로깅 개선: [0.2, 0.4]
    레거시 리팩토링: [0.9, 0.3]

사분면 위치:

• quadrant-1: 우상단 (높은 가치, 높은 난이도)
• quadrant-2: 좌상단 (높은 가치, 낮은 난이도)
• quadrant-3: 좌하단 (낮은 가치, 낮은 난이도)
• quadrant-4: 우하단 (낮은 가치, 높은 난이도)

---

11. Pie Chart (파이 차트)

데이터 비율, 분포 시각화.

Copypie showData
    title 프로그래밍 언어 사용률
    "Java" : 35
    "Python" : 25
    "JavaScript" : 20
    "Go" : 12
    "Others" : 8

옵션:

• showData: 퍼센트 값 표시
• title: 차트 제목

---

12. User Journey (사용자 여정)

UX 흐름, 사용자 경험 만족도 시각화.

Copyjourney
    title 사용자 구매 여정
    section 탐색
      홈페이지 방문: 5: 사용자
      상품 검색: 4: 사용자
      상품 상세 보기: 4: 사용자
    section 구매
      장바구니 담기: 5: 사용자
      결제 진행: 3: 사용자
      결제 완료: 5: 사용자
    section 배송
      배송 추적: 4: 사용자
      상품 수령: 5: 사용자

문법:

• section: 단계 그룹
• 작업명: 만족도(1-5): 액터

---

13. XY Chart (좌표 차트)

수치 데이터, 트래픽, 성능 지표 시각화.

Copyxychart-beta
    title "월별 트래픽"
    x-axis [Jan, Feb, Mar, Apr, May, Jun]
    y-axis "요청 수 (천)" 0 --> 100
    bar [30, 45, 60, 55, 70, 85]
    line [30, 45, 60, 55, 70, 85]

차트 유형:

• bar: 막대 그래프
• line: 선 그래프
• 둘 다 함께 사용 가능

---

14. Kanban (칸반 보드)

작업 상태 관리, 스프린트 보드.

Copykanban
    Todo
        task1[기능 설계]
        task2[API 정의]
    In Progress
        task3[백엔드 개발]
    Review
        task4[코드 리뷰 대기]
    Done
        task5[DB 설계 완료]

문법:

• 열 이름을 먼저 작성
• 하위에 taskId[작업명] 형식으로 태스크 추가

---

15. Block Diagram (블록 다이어그램)

시스템 구성 요소, 아키텍처 블록 표현.

Copyblock-beta
    columns 3
    Frontend:3
    block:backend:2
        API["API Server"]
        Worker["Background Worker"]
    end
    DB[("Database")]:1

문법:

• columns N: 열 개수 지정
• 요소:N: N칸 차지
• block:id:N ... end: 블록 그룹

---

16. Architecture Diagram (아키텍처 다이어그램)

클라우드/시스템 아키텍처, 인프라 구성.

Copyarchitecture-beta
    group api(cloud)[API Layer]

    service client(internet)[Client] in api
    service gateway(server)[API Gateway] in api
    service auth(server)[Auth Service] in api
    service app(server)[App Service] in api

    client:R --> L:gateway
    gateway:R --> L:auth
    gateway:B --> T:app

아이콘 유형:

• cloud, server, database, disk, internet

---

17. Sankey Diagram (생키 다이어그램)

흐름/에너지 분석, 데이터 흐름 시각화.

Copysankey-beta

%% source,target,value
Electricity,Residential,30
Electricity,Commercial,25
Electricity,Industrial,45
Natural Gas,Residential,20
Natural Gas,Commercial,15
Natural Gas,Industrial,35

문법:

• source,target,value 형식
• CSV 스타일로 흐름 정의

---

18. Requirement Diagram (요구사항 다이어그램)

요구사항 추적, 의존성 관리.

CopyrequirementDiagram
    requirement user_auth {
        id: REQ-001
        text: 사용자 인증 기능
        risk: high
        verifymethod: test
    }

    functionalRequirement login {
        id: REQ-001-1
        text: 로그인 기능 구현
        risk: medium
        verifymethod: test
    }

    element auth_module {
        type: module
        docRef: auth.md
    }

    user_auth - contains -> login
    auth_module - satisfies -> login

관계:

• contains: 포함
• derives: 파생
• satisfies: 충족
• verifies: 검증
• refines: 구체화
• traces: 추적

---

19. C4 Diagram (C4 아키텍처)

시스템 아키텍처를 4단계 레벨로 표현.

CopyC4Context
    title System Context Diagram

    Person(user, "User", "시스템 사용자")
    System(system, "My System", "핵심 시스템")
    System_Ext(email, "Email System", "이메일 발송")

    Rel(user, system, "Uses")
    Rel(system, email, "Sends email")

C4 레벨:

• C4Context: 시스템 컨텍스트 (Level 1)
• C4Container: 컨테이너 (Level 2)
• C4Component: 컴포넌트 (Level 3)
• C4Dynamic: 동적 다이어그램

요소:

• Person(id, label, description): 사용자
• System(id, label, description): 내부 시스템
• System_Ext(id, label, description): 외부 시스템
• Container(id, label, tech, description): 컨테이너
• Rel(from, to, label): 관계

---

20. Packet Diagram (패킷 다이어그램)

네트워크 패킷 구조 표현.

Copypacket-beta
    0-15: "Source Port"
    16-31: "Destination Port"
    32-63: "Sequence Number"
    64-95: "Acknowledgment Number"
    96-99: "Data Offset"
    100-105: "Reserved"
    106-111: "Flags"
    112-127: "Window Size"

문법:

• 시작비트-끝비트: "필드명"

---

용도별 다이어그램 선택 가이드

---

CLI 사용법

기본 변환

Copy# MMD 파일에서 SVG 생성
mmdc -i diagram.mmd -o diagram.svg

# PNG로 생성
mmdc -i diagram.mmd -o diagram.png

# 배경 투명
mmdc -i diagram.mmd -o diagram.svg -b transparent

# 테마 지정
mmdc -i diagram.mmd -o diagram.svg -t dark

# 크기 지정
mmdc -i diagram.mmd -o diagram.png -w 1920 -H 1080

설정 파일 사용

mermaid-config.json:

Copy{
  "theme": "base",
  "themeVariables": {
    "primaryColor": "#3498DB",
    "primaryTextColor": "#ffffff",
    "primaryBorderColor": "#2980B9",
    "lineColor": "#7F8C8D",
    "secondaryColor": "#2ECC71",
    "tertiaryColor": "#ECF0F1",
    "fontSize": "14px"
  }
}

Copymmdc -i diagram.mmd -o diagram.svg -c mermaid-config.json

테마 옵션

---

스타일링

노드 스타일

Copygraph LR
    A[기본] --> B[스타일 적용]

    style A fill:#fff,stroke:#333,stroke-width:2px
    style B fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff

클래스 정의

Copygraph LR
    A[Success]:::success --> B[Error]:::error

    classDef success fill:#c8e6c9,stroke:#2e7d32
    classDef error fill:#ffcdd2,stroke:#c62828

테마 초기화

Copy%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#ff6b6b'}}}%%
graph LR
    A --> B

---

작성 절차

1. Mermaid 코드 작성: .mmd 파일 또는 마크다운 코드 블록
2. SVG 변환: mmdc 명령으로 변환
3. 파일 저장: cs/{category}/images/{diagram-name}.svg
4. 마크다운에서 참조: ![설명](./images/{diagram-name}.svg)
5. git add 실행

주의사항

1. 파일명: kebab-case 사용
2. 위치: cs/{category}/images/ 폴더에 저장
3. 한글: 일부 폰트에서 깨질 수 있음 - 테스트 필요
4. 복잡한 레이아웃: 자동 배치가 마음에 안 들면 SVG 직접 생성 고려
5. Mermaid CLI 미설치 시: SVG 직접 생성 방식 사용

참고 자료

• Mermaid 공식 문서
• Mermaid Live Editor
• Mermaid CS 문서