Communitygithub.com

spillwavesolutions/design-doc-mermaid

텍스트나 소스 코드에서 Mermaid 다이어그램(순서도, 시퀀스, 클래스, ER, 상태, C4, 아키텍처)을 생성합니다. GitHub 위키에 기본으로 사용되며, 다이어그램 생성, Mermaid 생성, 아키텍처 문서화, 코드를 다이어그램으로 변환할 때 사용됩니다. PlantUML은 남은 유형에만 사용합니다. Confluence는 펜스 코드 블록뿐만 아니라 PNG/SVG도 필요합니다.

design-doc-mermaid란 무엇인가요?

이 스킬은 개발자가 텍스트 설명이나 소스 코드를 기반으로 다양한 유형의 Mermaid 다이어그램을 생성하고 문서화할 수 있도록 지원하는 종합적인 시스템입니다. 순서도, 시퀀스 다이어그램, 클래스 다이어그램, ER 다이어그램, 상태 다이어그램, C4 다이어그램, 아키텍처 다이어그램 등 다양한 다이어그램 유형을 지원하며, 각 유형별 전용 가이드와 템플릿을 제공합니다. GitHub 위키, WikiTicket, Confluence 등 여러 플랫폼과 호환되며, Confluence에는 펜스 코드 블록과 함께 PNG 또는 SVG 이미지를 업로드해야 합니다. 이 스킬은 코드베이스 분석, 다이어그램 유효성 검사, 오류 복구, 유니코드 기호 사용, 그리고 Python 스크립트를 통한 일괄 변환 기능을 포함한 강력한 워크플로우를 제공하여 문서화 과정에서 발생할 수 있는 문제를 사전에 방지합니다.

지원 대상✓Claude Code~Codex CLI~Cursor✓Gemini CLI
npx skills add spillwavesolutions/design-doc-mermaid
원본 보기→모든 스킬 둘러보기

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

미리보기

스킬 README에서

설명
API 시퀀스

문서

Mermaid Architect - 계층적 다이어그램 및 문서화 스킬

전문화된 가이드와 코드-다이어그램 변환 기능을 갖춘 Mermaid 다이어그램 및 문서화 시스템입니다.

목차

의사 결정 트리

이 스킬의 작동 방식:

  1. 사용자가 요청 → 스킬이 의도 분석
  2. 스킬이 다이어그램/문서 유형 결정 → 적절한 가이드 로드
  3. AI가 전문화된 가이드 읽기 → 템플릿을 사용하여 다이어그램/문서 생성
  4. 결과 제공 → 유효성 검사 및 내보내기 옵션 포함

사용자 의도 분석:

flowchart TD
    Start([사용자 요청]) --> Analyze{의도 분석}

    Analyze -->|"워크플로우, 프로세스, 비즈니스 로직"| Activity[액티비티 다이어그램 가이드 로드<br/>references/guides/diagrams/activity-diagrams.md]
    Analyze -->|"인프라, 배포, 클라우드"| Deploy[배포 다이어그램 가이드 로드<br/>references/guides/diagrams/deployment-diagrams.md]
    Analyze -->|"시스템 아키텍처, 컴포넌트"| Arch[아키텍처 가이드 로드<br/>references/guides/diagrams/architecture-diagrams.md]
    Analyze -->|"API 흐름, 상호작용"| Sequence[시퀀스 다이어그램 가이드 로드<br/>references/guides/diagrams/sequence-diagrams.md]
    Analyze -->|"클래스, ER, 상태, 위키, 워크스루"| WikiGuide[WikiTicket GitHub 가이드 로드<br/>references/guides/wiki-ticket-and-github.md]
    Analyze -->|"코드에서 다이어그램"| CodeToDiag[코드-다이어그램 가이드 로드<br/>references/guides/code-to-diagram/ + examples/]
    Analyze -->|"설계 문서, 전체 문서"| DesignDoc[설계 문서 템플릿 로드<br/>assets/*-design-template.md]
    Analyze -->|"유니코드 기호, 아이콘"| Unicode[유니코드 기호 가이드 로드<br/>references/guides/unicode-symbols/guide.md]
    Analyze -->|"추출, 검증, 변환"| Scripts[Python 스크립트 사용<br/>scripts/extract_mermaid.py<br/>scripts/mermaid_to_image.py]

    Activity --> 생성[다이어그램 생성]
    Deploy --> 생성
    Arch --> 생성
    Sequence --> 생성
    WikiGuide --> 생성
    CodeToDiag --> 생성
    DesignDoc --> 생성
    Unicode --> 생성
    Scripts --> 실행[스크립트 실행]

    생성 --> 검증{검증?}
    검증 -->|예| 검증실행[mmdc 검증 실행]
    검증 -->|아니오| 출력
    검증실행 --> 출력[결과 출력]
    실행 --> 출력

    classDef decision fill:#FFD700,stroke:#333,stroke-width:2px,color:black
    classDef guide fill:#90EE90,stroke:#333,stroke-width:2px,color:darkgreen
    classDef action fill:#87CEEB,stroke:#333,stroke-width:2px,color:darkblue

    class Analyze,검증 decision
    class Activity,Deploy,Arch,Sequence,WikiGuide,CodeToDiag,DesignDoc,Unicode,Scripts guide
    class 생성,실행,검증실행,출력 action

사용 가능한 가이드 및 리소스

다이어그램 유형 가이드 (references/guides/diagrams/)

가이드전체 경로사용자가 원할 때 로드예시
액티비티 다이어그램references/guides/diagrams/activity-diagrams.md워크플로우, 프로세스, 비즈니스 로직, 사용자 흐름, 의사 결정 트리"결제 흐름 보여줘", "ETL 파이프라인 문서화", "승인 워크플로우 생성"
배포 다이어그램references/guides/diagrams/deployment-diagrams.md인프라, 클라우드 아키텍처, K8s, 서버리스, 네트워크 토폴로지"AWS 아키텍처 보여줘", "GCP 배포 문서화", "K8s 다이어그램 생성"
아키텍처 다이어그램references/guides/diagrams/architecture-diagrams.md시스템 아키텍처, 컴포넌트 설계, 고수준 구조"시스템 컴포넌트 보여줘", "마이크로서비스 문서화", "아키텍처 개요"
시퀀스 다이어그램references/guides/diagrams/sequence-diagrams.mdAPI 상호작용, 서비스 통신, 요청/응답 흐름"API 호출 시퀀스 보여줘", "인증 흐름 문서화", "서비스 상호작용"
WikiTicket / GitHub / Confluencereferences/guides/wiki-ticket-and-github.md설계 문서, 워크스루, 요구사항, 위키 게시, Confluence 이미지"아키텍처 문서", "코드 워크스루", "위키", "Confluence"

WikiTicket 및 GitHub 위키의 기본값은 이 스킬이며, classDiagram, erDiagram, stateDiagram-v2를 포함합니다. 이러한 유형을 PlantUML로 보내지 마십시오. GitHub에서 C4 / architecture-beta / block-beta를 렌더링하지 못하면 flowchart TD로 대체하십시오.

코드-다이어그램 가이드 및 예제

리소스전체 경로제공 내용
마스터 가이드references/guides/code-to-diagram/README.md모든 코드베이스를 분석하고 다이어그램을 추출하는 완전한 워크플로우
Spring Bootexamples/spring-boot/README.mdController→Service→Repository 아키텍처, 배포 구성, 메서드의 시퀀스, 비즈니스 로직의 액티비티
FastAPIexamples/fastapi/README.mdPython 비동기 패턴, Pydantic 모델, 의존성 주입, 클라우드 배포
Reactexamples/react/README.md컴포넌트 계층 구조, 상태 관리, 데이터 흐름, 빌드 파이프라인
Python ETLexamples/python-etl/README.md데이터 파이프라인, 변환 단계, 오류 처리, 스케줄링
Node/Expressexamples/node-webapp/README.md미들웨어 체인, 라우트 핸들러, 비동기 패턴, 배포
Java 웹 앱examples/java-webapp/README.md전통적인 MVC, 서블릿 컨테이너, WAR 배포

설계 문서 템플릿

템플릿전체 경로용도로드 시점
아키텍처 설계assets/architecture-design-template.md시스템 전체 아키텍처"아키텍처 문서 생성", "시스템 설계 문서화"
API 설계assets/api-design-template.mdAPI 명세"API 설계 문서", "REST API 문서화"
기능 설계assets/feature-design-template.md기능 계획"기능 설계", "새 기능 계획"
데이터베이스 설계assets/database-design-template.md데이터베이스 스키마"데이터베이스 설계", "스키마 문서화"
시스템 설계assets/system-design-template.md전체 시스템"시스템 설계 문서", "전체 시스템 문서화"

유니코드 기호 가이드

전체 경로: references/guides/unicode-symbols/guide.md

사용자가 언급할 때 로드: "유니코드 기호", "다이어그램의 이모지", "의미 있는 아이콘", "기호 추가"

빠른 참조:

  • 📦 인프라: ☁️ 🌐 🔌 📡 🗄️
  • ⚙️ 컴퓨트: ⚙️ ⚡ 🔄 ♻️ 🚀 💨
  • 💾 데이터: 💾 📦 📊 📈 🗃️ 🧊
  • 📨 메시징: 📨 📬 📤 📥 🐰 📢
  • 🔐 보안: 🔐 🔑 🛡️ 🚪 👤 🎫
  • 📝 모니터링: 📝 📊 🚨 ⚠️ ✅ ❌

Python 스크립트 (scripts/)

스크립트용도로드 시점
extract_mermaid.pyMarkdown에서 다이어그램 추출, 구문 검증, 이미지로 대체"다이어그램 추출", "mermaid 검증", "모든 다이어그램 찾기"
mermaid_to_image.py.mmd를 PNG/SVG로 변환, 일괄 변환, 사용자 정의 테마"이미지로 변환", "다이어그램 렌더링", "PNG 생성"
resilient_diagram.py전체 워크플로우: .mmd 저장, 이미지 생성, 검증, 오류 복구"다이어그램 생성", "검증과 함께 다이어그램 생성", "탄력적 다이어그램"

GitHub 위키, WikiTicket, Confluence

WikiTicket 설계 문서, 코드 워크스루, 요구사항, GitHub 위키 또는 Confluence를 위해 references/guides/wiki-ticket-and-github.md를 로드하십시오.

대상제공 사항
GitHub 위키 / GFM펜스 mermaid 블록. GitHub는 class, ER, state, sequence, flowchart, C4를 렌더링합니다.
Confluence / Notion / Word / PDF또한 PNG 또는 SVG를 렌더링하고(scripts/resilient_diagram.py 또는 mmdc) 이미지를 업로드하십시오. Confluence가 Mermaid를 렌더링할 것이라고 믿지 마십시오.

PlantUML은 Salt 와이어프레임, 유스 케이스, 타이밍, ArchiMate, nwdiag 및 WBS에 대해 옵트인 방식입니다. 이러한 유형은 항상 PNG 또는 SVG로 제공됩니다.

사용 패턴

일반적인 요청 패턴 및 가이드 선택. 전체 매핑은 언제 무엇을 사용할지를 참조하십시오.

패턴요청 예시로드할 가이드
단일 다이어그램"로그인 흐름에 대한 액티비티 다이어그램 생성"다이어그램 유형 가이드 + 유니코드 기호
코드에서 다이어그램"application.yml에서 배포 다이어그램 생성"프레임워크 예제 + 배포 가이드
설계 문서"API 설계 문서 생성"assets/의 템플릿 + 관련 다이어그램 가이드
추출/검증"design.md에서 다이어그램 추출"scripts/extract_mermaid.py 사용
일괄 변환"모든 .mmd를 PNG로 변환"scripts/mermaid_to_image.py 사용

탄력적 워크플로우

중요: 모든 다이어그램 생성에 권장되는 접근 방식입니다. 검증, 오류 복구 및 일관된 파일 구성을 보장합니다.

전체 가이드: references/guides/resilient-workflow.md

워크플로우 개요

flowchart LR
    A[1. 유형 식별] --> B[2. .mmd + 이미지 저장]
    B --> C{3. 유효?}
    C -->|예| D[4. Markdown에 추가]
    C -->|아니오| E[5. 오류 복구]
    E --> F{수정 발견?}
    F -->|예| A
    F -->|아니오| G[외부 검색]
    G --> A

    classDef step fill:#90EE90,stroke:#333,color:darkgreen
    classDef decision fill:#FFD700,stroke:#333,color:black
    class A,B,D,E,G step
    class C,F decision

핵심 원칙

유효성 검사를 통과할 때까지 절대 다이어그램을 마크다운에 추가하지 마십시오. 이를 통해 문서에서 깨진 다이어그램을 방지할 수 있습니다.

스크립트 사용 (권장)

# 전체 오류 복구와 함께 생성
python scripts/resilient_diagram.py \
    --code "flowchart TD; A-->B" \
    --markdown-file design_doc \
    --diagram-num 1 \
    --title "process_flow" \
    --format png \
    --json

출력: ./diagrams/ 디렉토리에 .mmd 및 .png 파일 모두.

파일 명명 규칙

./diagrams/<markdown_file>_<num>_<type>_<title>.mmd
./diagrams/<markdown_file>_<num>_<type>_<title>.png

예시: ./diagrams/api_design_01_sequence_auth_flow.png

오류 복구 우선순위

검증이 실패하면 워크플로우가 자동으로 다음을 수행합니다:

  1. 문제 해결 가이드 확인 - references/guides/troubleshooting.md (28개의 문서화된 오류)
  2. perplexity로 검색 - 구문 질문을 위한 perplexity_ask MCP
  3. brave로 검색 - 최근 솔루션을 위한 brave_web_search MCP
  4. gemini에 질문 - 대안적인 관점을 위한 gemini 스킬
  5. 일반 검색 - 대체 수단으로 WebSearch 도구

수동 대체 단계

스크립트를 사용할 수 없는 경우:

  1. 첫 번째 줄에서 다이어그램 유형 식별 (flowchart, sequence 등)
  2. 참조 가이드 로드 from references/guides/diagrams/
  3. 저장 ./diagrams/<markdown_file>_<num>_<type>_<title>.mmd
  4. 검증: mmdc -i file.mmd -o file.png -b transparent
  5. 오류 발생 시: 일치하는 오류를 위해 references/guides/troubleshooting.md 검색
  6. 찾을 수 없는 경우: 위의 우선순위 순서대로 검색 도구 사용
  7. 참조 추가: ![설명](./diagrams/filename.png)

패턴 6: 탄력적 다이어그램 생성

사용자: "시퀀스 다이어그램을 생성하고 설계 문서에 추가해줘"

스킬 동작:

  1. 의도 식별: 다이어그램 생성 + 마크다운 통합
  2. 워크플로우 가이드 로드: references/guides/resilient-workflow.md
  3. 다이어그램 유형 식별: 시퀀스
  4. 다이어그램 가이드 로드: references/guides/diagrams/sequence-diagrams.md
  5. 템플릿을 사용하여 Mermaid 코드 생성
  6. 탄력적 워크플로우 실행: 
    python scripts/resilient_diagram.py \
    --code "[생성된 코드]" \
    --markdown-file design_doc \
    --diagram-num 1 \
    --title "api_sequence" \
    --json
  7. 검증 실패 시 → 문제 해결 수정 적용 → 재시도
  8. 성공 시 → 마크다운에 ![API 시퀀스](./diagrams/design_doc_01_sequence_api_sequence.png) 추가

유니코드 의미 기호

항상 유니코드 기호를 사용하여 다이어그램 명확성을 높이십시오. 일반적인 패턴:

인프라 및 배포

graph TB
    Client[👤 사용자] --> LB[🌐 로드 밸런서]
    LB --> App1[⚙️ 앱 서버 1]
    LB --> App2[⚙️ 앱 서버 2]
    App1 --> DB[(💾 데이터베이스)]
    App1 --> Cache[(⚡ Redis)]

상태가 있는 액티비티 흐름

flowchart TD
    Start([🚀 시작]) --> Process[⚙️ 데이터 처리]
    Process --> Check{✓ 유효?}
    Check -->|예| Save[💾 저장]
    Check -->|아니오| Error[❌ 오류]
    Save --> Complete([✅ 완료])

마이크로서비스 아키텍처

graph TB
    API[🌐 API 게이트웨이] --> Auth[🔐 인증 서비스]
    API --> Orders[📋 주문 서비스]
    Orders --> Queue[📬 메시지 큐]
    Queue --> Worker[⚙️ 백그라운드 워커]
    Worker --> Storage[📦 객체 스토리지]

전체 기호 참조를 위해 로드: references/guides/unicode-symbols/guide.md

Python 유틸리티

Mermaid 다이어그램 추출

# 모든 다이어그램 나열
python scripts/extract_mermaid.py document.md --list-only

# 별도 파일로 추출
python scripts/extract_mermaid.py document.md --output-dir diagrams/

# 모든 다이어그램 검증
python scripts/extract_mermaid.py document.md --validate

# 이미지 참조로 대체 (Confluence 업로드용)
python scripts/extract_mermaid.py document.md --replace-with-images \
  --image-format png --output-markdown output.md

이미지로 변환

# 단일 변환
python scripts/mermaid_to_image.py diagram.mmd output.png

# 사용자 정의 설정과 함께
python scripts/mermaid_to_image.py diagram.mmd output.svg \
  --theme dark --background white --width 1200

# 디렉토리 일괄 변환
python scripts/mermaid_to_image.py diagrams/ output/ --format png --recursive

# stdin에서
echo "graph TD; A-->B" | python scripts/mermaid_to_

…

[번역을 위해 잘림]

의사 결정 트리 예시

의도 분석을 위한 실제 시나리오:

사용자 요청의도로드할 가이드생성할 다이어그램 유형
"사용자 등록 프로세스 문서화"비즈니스 로직액티비티 다이어그램 가이드액티비티 다이어그램
"AWS Lambda 아키텍처 보여줘"인프라배포 다이어그램 가이드배포 다이어그램
"주문 API 설계"API 흐름시퀀스 다이어그램 가이드시퀀스 다이어그램
"마이크로서비스 개요 생성"시스템 아키텍처아키텍처 다이어그램 가이드C4/아키텍처 다이어그램
"코드를 다이어그램으로 변환"코드 분석코드-다이어그램 가이드 + 예제프레임워크별 다이어그램
"설계 문서 생성"전체 문서설계 문서 템플릿 + 가이드문서 + 포함된 다이어그램

고대비 스타일링

접근성을 위해 항상 고대비 색상을 사용하십시오:

flowchart TD
    Start([시작]) --> Process{처리}
    Process -->|성공| Success[✅ 완료]
    Process -->|실패| Failure[❌ 실패]

    classDef default fill:#ffffff,stroke:#000000,color:#000000
    classDef highlight fill:#ffff00,stroke:#000000,color:#000000
    class Success,Failure highlight

모범 사례:

  • 흰색 또는 매우 밝은 배경에 검정색 텍스트 사용
  • 상태 강조를 위해 굵은 테두리 사용
  • 색상 코드와 함께 유니코드 기호 사용
  • 배경이 있는 경우 텍스트 그림자 사용 안 함

파일 구성

모든 다이어그램 및 문서에 대해 일관된 파일 구조 유지:

./
├── assets/
│   ├── architecture-design-template.md
│   ├── api-design-template.md
│   ├── feature-design-template.md
│   ├── database-design-template.md
│   └── system-design-template.md
├── references/
│   ├── guides/
│   │   ├── diagrams/
│   │   │   ├── activity-diagrams.md
│   │   │   ├── deployment-diagrams.md
│   │   │   ├── architecture-diagrams.md
│   │   │   ├── sequence-diagrams.md
│   │   │   └── ...
│   │   ├── wiki-ticket-and-github.md
│   │   ├── resilient-workflow.md
│   │   ├── troubleshooting.md
│   │   ├── code-to-diagram/
│   │   │   └── README.md
│   │   └── unicode-symbols/
│   │       └── guide.md
│   └── examples/
│       ├── spring-boot/README.md
│       ├── fastapi/README.md
│       ├── react/README.md
│       ├── python-etl/README.md
│       ├── node-webapp/README.md
│       └── java-webapp/README.md
├── scripts/
│   ├── extract_mermaid.py
│   ├── mermaid_to_image.py
│   └── resilient_diagram.py
└── diagrams/
    └── # 생성된 다이어그램

워크플로우 요약

  1. 요청 분석 → 의사 결정 트리 사용
  2. 가이드 로드 → 의도와 일치하는 가이드
  3. 생성 → 템플릿 및 유니코드 기호 사용
  4. 검증 → 스크립트로 유효성 검사 실행
  5. 문서화 → 마크다운 또는 이미지로 출력
  6. 게시 → GitHub 위키, Confluence 등

언제 무엇을 사용할지

작업사용할 도구
단일 다이어그램 생성수동 워크플로우 + 가이드 로드
다중 다이어그램 배치scripts/resilient_diagram.py
기존 문서에서 추출scripts/extract_mermaid.py
모든 .mmd를 PNG/SVG로 변환scripts/mermaid_to_image.py
설계 문서 생성assets/의 템플릿 + 다이어그램 가이드
코드베이스 분석코드-다이어그램 가이드 + 예제
위키/Confluence 게시wiki-ticket-and-github.md 가이드

모범 사례

  1. 다이어그램 생성 전에 항상 가이드 로드 - 각 다이어그램 유형에 대한 특정 템플릿 및 모범 사례 포함
  2. 유니코드 기호 사용 - 다이어그램을 더 직관적으로 만듦
  3. 생성된 모든 다이어그램 검증 - scripts/resilient_diagram.py 사용
  4. 일관된 명명 규칙 유지 - {문서}_{번호}_{유형}_{제목}
  5. 검증 통과한 후에만 문서에 추가
  6. 설계 문서에 적절한 템플릿 사용
  7. 가능한 경우 코드-다이어그램 예제 활용
  8. 문서화를 위해 대상 플랫폼 고려 (GitHub 위키 대 Confluence)

학습 경로

초보자부터 고급 사용자까지:

  1. 기본 다이어그램 생성 - 간단한 순서도 또는 시퀀스 다이어그램으로 시작
  2. 다이어그램 유형 이해 - 각 유형의 가이드 읽기
  3. 템플릿 마스터 - 설계 문서 템플릿 사용 방법 학습
  4. 코드에서 다이어그램 - 코드베이스에서 다이어그램을 추출하는 방법 학습
  5. 고급 워크플로우 - 탄력적 워크플로우 및 스크립트 사용
  6. 통합 - GitHub 위키, Confluence 등과 통합
  7. 사용자 정의 - 사용자 정의 테마, 유니코드 기호 및 고급 스크립트 옵션

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

spillwavesolutions/design-doc-mermaid

Create Mermaid diagrams (activity, deployment, sequence, architecture) from text descriptions or source code. Use when asked to "create a diagram", "generate mermaid", "document architecture", "code to diagram", "create design doc", or "convert code to diagram". Supports hierarchical on-demand guide loading, Unicode semantic symbols, and Python utilities for diagram extraction and image conversion.

관련 스킬

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community