hgzero/claude/mermaid-guide.md

Mermaid문법검사가이드

개요

Mermaid 다이어그램의 문법 오류를 사전에 검출하여 렌더링 실패를 방지하기 위한 가이드입니다. Docker 기반 Mermaid CLI를 활용하여 로컬에서 빠르게 문법을 검증할 수 있습니다.

Mermaid CLI 서버 설치 및 검사

Docker로 Mermaid CLI 컨테이너 실행

# Mermaid CLI 컨테이너가 실행 중인지 확인
docker ps | grep mermaid-cli

# ⚠️ 중요: 첫 실행 시 이미지 다운로드를 먼저 진행 (큰 이미지로 인한 타임아웃 방지)
docker pull minlag/mermaid-cli:latest

# Mermaid CLI 컨테이너가 없으면 설치 및 실행 (root 권한으로 실행, 포트 48080 사용)
docker run -d --rm --name mermaid-cli -u root -p 48080:8080 --entrypoint sh minlag/mermaid-cli:latest -c "while true;do sleep 3600; done"

# 컨테이너 상태 확인
docker logs mermaid-cli

💡 Docker 이미지 다운로드 관련 주의사항

첫 실행 시 발생할 수 있는 문제:

• minlag/mermaid-cli:latest 이미지가 큰 용량(약 700MB+)이므로 다운로드에 시간이 오래 걸림
• docker run 명령 실행 시 이미지가 없으면 자동 다운로드하지만 타임아웃 발생 가능
• 해결방법: docker pull 명령으로 이미지를 먼저 다운로드한 후 컨테이너 실행

권장 실행 순서:

1. docker pull minlag/mermaid-cli:latest (이미지 다운로드)
2. docker run 명령으로 컨테이너 실행
3. 필수 설정 진행

⚠️ 중요: 최초 컨테이너 생성 후 필수 설정

Mermaid CLI는 Puppeteer를 사용하여 다이어그램을 렌더링하므로 Chromium 브라우저가 필요합니다. 컨테이너를 처음 생성한 후 다음 명령을 실행하여 필요한 패키지를 설치해야 합니다:

# Chromium 및 필요한 종속성 설치
docker exec mermaid-cli sh -c "apk add --no-cache chromium chromium-chromedriver nss freetype harfbuzz ca-certificates ttf-freefont"

# Puppeteer가 사용할 설정 파일 생성
docker exec mermaid-cli sh -c "echo '{\"executablePath\": \"/usr/bin/chromium-browser\", \"args\": [\"--no-sandbox\", \"--disable-setuid-sandbox\", \"--disable-dev-shm-usage\"]}' > /tmp/puppeteer-config.json"

이 설정은 컨테이너가 실행되는 동안 유지되므로 한 번만 실행하면 됩니다.

문법검사 후 Container를 중지하지 않고 계속 사용함

문법 검사 방법

현재 OS에 맞게 수행.

Linux/macOS 버전

스크립트 파일(tools/check-mermaid.sh)을 이용하여 수행

1. tools/check-mermaid.sh 파일 존재 여부 확인
2. 스크립트 파일이 없으면 "Mermaid문법검사기(Linux/Mac)"를 tools/check-mermaid.sh 파일로 다운로드하여 스크립트 파일을 만듦
3. 스크립트 파일이 있으면 그 스크립트 파일을 이용하여 검사

# 1. 스크립트 실행 권한 부여 (최초 1회)
chmod +x tools/check-mermaid.sh

# 2. 문법 검사 실행
./tools/check-mermaid.sh {검사할 파일}

# 예시
./tools/check-mermaid.sh design/backend/physical/physical-architecture.mmd

Windows PowerShell 버전

스크립트 파일(tools/check-mermaid.ps1)을 이용하여 수행

1. tools/check-mermaid.ps1 파일 존재 여부 확인
2. 스크립트 파일이 없으면 "Mermaid문법검사기(Window)"를 tools/check-mermaid.ps1 파일로 다운로드하여 스크립트 파일을 만듦
3. 스크립트 파일이 있으면 그 스크립트 파일을 이용하여 검사

# 문법 검사 실행
.\tools\check-mermaid.ps1 {검사할 파일}

# 예시
.\tools\check-mermaid.ps1 design\backend\physical\physical-architecture.mmd

수동 검사 방법 (스크립트 없이)

# 1. 고유 파일명 생성 (충돌 방지)
TEMP_FILE="/tmp/mermaid_$(date +%s)_$$.mmd"

# 2. 파일 복사
docker cp {검사할 파일} mermaid-cli:${TEMP_FILE}

# 3. 문법 검사 (Puppeteer 설정 파일 사용)
docker exec mermaid-cli sh -c "cd /home/mermaidcli && node_modules/.bin/mmdc -i ${TEMP_FILE} -o /tmp/output.svg -p /tmp/puppeteer-config.json -q"

# 4. 임시 파일 삭제
docker exec mermaid-cli rm -f ${TEMP_FILE} /tmp/output.svg

주의: Puppeteer 설정 파일(/tmp/puppeteer-config.json)이 있어야 합니다. 없다면 위의 "최초 컨테이너 생성 후 필수 설정"을 먼저 실행하세요.

검사 결과 해석

출력	의미	대응 방법
"Success: Mermaid syntax is valid!"	문법 오류 없음 ✅	정상, 렌더링 가능
"Parse error on line X"	X번째 줄 구문 오류 ❌	해당 라인 문법 확인
"Expecting 'XXX'"	예상 토큰 오류 ❌	누락된 문법 요소 추가
"Syntax error"	일반 문법 오류 ❌	전체 구조 재검토

Mermaid 다이어그램 타입별 주의사항

1. Graph/Flowchart

graph TB
    %% 올바른 사용법 ✅
    A[Node A] --> B[Node B]
    C[Node C] -.-> D[Node D]
    E[Node E] ==> F[Node F]
    
    %% 주의사항
    %% - 노드 ID에 공백 불가 (대신 [Label] 사용)
    %% - subgraph와 end 개수 일치 필요
    %% - 따옴표 안에서 특수문자 주의

2. Sequence Diagram

sequenceDiagram
    %% 올바른 사용법 ✅
    participant A as Service A
    participant B as Service B
    
    A->>B: Request
    B-->>A: Response
    A->>+B: Call with activation
    B-->>-A: Return with deactivation
    
    %% 주의사항
    %% - participant 선언 권장
    %% - 활성화(+)/비활성화(-) 쌍 맞추기
    %% - Note 블록 종료 확인

3. Class Diagram

classDiagram
    %% 올바른 사용법 ✅
    class Animal {
        +String name
        +int age
        +makeSound() void
    }
    
    class Dog {
        +String breed
        +bark() void
    }
    
    Animal <|-- Dog : inherits
    
    %% 주의사항
    %% - 메서드 괄호 필수
    %% - 관계 표현 정확히
    %% - 접근 제한자 기호 확인

4. State Diagram

stateDiagram-v2
    %% 올바른 사용법 ✅
    [*] --> Idle
    Idle --> Processing : start
    Processing --> Completed : finish
    Processing --> Error : error
    Error --> Idle : reset
    Completed --> [*]
    
    %% 주의사항
    %% - [*]는 시작/종료 상태
    %% - 상태 이름에 공백 불가
    %% - 전이 레이블 콜론(:) 사용

일반적인 오류와 해결 방법

1. 괄호 불균형

%% 잘못된 예 ❌
graph TB
    A[Node (with parenthesis)]  %% 괄호 안에 괄호
    
%% 올바른 예 ✅
graph TB
    A[Node with parenthesis]

2. 특수 문자 이스케이프

%% 잘못된 예 ❌
graph TB
    A[Security & Management]  %% & 문자 직접 사용
    
%% 올바른 예 ✅
graph TB
    A[Security & Management]  %% HTML 엔티티 사용

3. subgraph/end 불일치

%% 잘못된 예 ❌
graph TB
    subgraph One
        A --> B
        subgraph Two
            C --> D
    end  %% Two만 닫힘, One은 안 닫힘
    
%% 올바른 예 ✅
graph TB
    subgraph One
        A --> B
        subgraph Two
            C --> D
        end
    end  %% 모든 subgraph 닫기

4. 노드 참조 오류

%% 잘못된 예 ❌
graph TB
    A --> UnknownNode  %% 정의되지 않은 노드
    
%% 올바른 예 ✅
graph TB
    A[Node A] --> B[Node B]  %% 모든 노드 정의

컨테이너 관리

컨테이너 중지 및 삭제

# 컨테이너 중지
docker stop mermaid-cli

# 컨테이너 삭제
docker rm mermaid-cli

# 한 번에 중지 및 삭제
docker stop mermaid-cli && docker rm mermaid-cli

컨테이너 재시작

# 컨테이너 재시작
docker restart mermaid-cli

성능 최적화 팁

1. 컨테이너 유지: 검사 후 컨테이너를 중지하지 않고 유지하여 다음 검사 시 빠르게 실행
2. 배치 검사: 여러 파일을 연속으로 검사할 때 컨테이너 재시작 없이 진행
3. 로컬 파일 사용: 네트워크 경로보다 로컬 파일 경로 사용 권장

문제 해결

Docker 관련 오류

# Docker 데몬 실행 확인
docker ps

# Docker Desktop 시작 (Windows/Mac)
# Docker 서비스 시작 (Linux)
sudo systemctl start docker

권한 오류

# Linux/Mac에서 스크립트 실행 권한
chmod +x tools/check-mermaid.sh

# Docker 권한 (Linux)
sudo usermod -aG docker $USER

컨테이너 이미지 오류

# 이미지 재다운로드
docker pull minlag/mermaid-cli:latest

# 기존 컨테이너 삭제 후 재생성
docker stop mermaid-cli && docker rm mermaid-cli