NanoSkill
스킬 제출

머메이드 아키텍트: 다이어그램 및 문서화 스킬

제작SpillwaveSolutions66GitHub 스타GitHub

지능형 오케스트레이션, 코드-다이어그램 변환, Python 유틸리티를 사용하여 포괄적인 머메이드 다이어그램과 설계 문서를 생성하세요. 몇 초 만에 상세한 기술 문서 작성을 시작하세요.

다이어그램머메이드보안 검사 통과
결과 미리보기

전체 데모

이 에이전트 스킬로 생성된 음식 배달 플랫폼 시스템에 대한 머메이드 다이어그램을 확인하세요.

시작하기

첫 작업 실행

  1. mermaid-architect-step-1
    01

    1단계：설치

    에이전트에 스킬을 추가하세요.

  2. mermaid-architect-step-2
    02

    2단계：프로세스 설명

    시각화하려는 워크플로, 시스템 또는 시퀀스를 입력하세요.

  3. mermaid-architect-step-3
    03

    3단계：결과 검토

    프로세스 설명을 기반으로 생성된 머메이드 다이어그램을 받으세요.

설치 명령

$ npx skills add https://github.com/spillwavesolutions/design-doc-mermaid

소개

머메이드 아키텍트 스킬은 개발자, 아키텍트, 기술 문서 작성자가 포괄적인 머메이드 다이어그램과 설계 문서를 효율적으로 생성하고 관리할 수 있도록 지원합니다. 지능형 오케스트레이션과 온디맨드 가이드 로딩을 활용하여 이 스킬은 복잡한 시스템, 워크플로, 코드 구조의 시각화를 간소화합니다. 정확하고 시각적으로 매력적인 다이어그램을 생성하여 명확한 커뮤니케이션과 최신 문서화를 보장합니다.

이 강력한 Claude Code 스킬은 코드-다이어그램 생성과 같은 고급 기능을 제공하여 Spring Boot 또는 FastAPI 애플리케이션에서 직접 아키텍처 인사이트를 추출할 수 있습니다. 또한 머메이드 다이어그램을 추출, 검증, 이미지 형식으로 변환하는 풍부한 Python 유틸리티 세트를 포함하여 기존 문서 워크플로 및 Confluence와 같은 도구와 쉽게 통합할 수 있습니다. 계층적 시스템은 효율적인 토큰 사용과 빠른 응답 시간을 보장하여 원활한 경험을 제공합니다.

API 문서화, 시스템 아키텍처 시각화, 비즈니스 프로세스 설명 등 무엇이 필요하든 머메이드 아키텍트는 작업을 완료하는 데 필요한 도구와 템플릿을 제공합니다. 다양한 다이어그램 유형, 유니코드 시맨틱 기호, 고대비 스타일링을 지원하여 다이어그램이 정보를 잘 전달하고 접근성이 뛰어납니다. 또한 이 스킬은 사용자가 상세한 기술 문서를 빠르게 능숙하게 작성할 수 있도록 체계적인 학습 경로와 예제를 제공합니다.

핵심 기능

강력한 이유

  • 지능형 다이어그램 생성

    워크플로우, 인프라, 시스템 구성 요소, API 흐름을 위한 활동, 배포, 아키텍처, 시퀀스 다이어그램 등 다양한 머메이드 다이어그램을 생성합니다.

  • 코드-다이어그램 변환

    기존 코드베이스(예: 스프링 부트, FastAPI)나 구성 파일에서 다이어그램을 자동으로 생성하여 아키텍처, 배포, 시퀀스 흐름을 시각화합니다.

  • 포괄적인 설계 문서 생성

    아키텍처, API, 기능, 데이터베이스, 시스템 설계를 위한 사전 정의된 템플릿을 사용하여 머메이드 다이어그램이 포함된 완전한 설계 문서를 생성합니다.

  • 유니코드 의미 기호 및 고대비 스타일링

    100개 이상의 의미 있는 유니코드 기호와 가독성 향상을 위한 고대비 색상 구성표로 다이어그램의 명확성과 접근성을 높입니다.

  • 다이어그램 관리를 위한 파이썬 유틸리티

    파이썬 스크립트를 사용하여 머메이드 다이어그램을 추출, 검증하고 PNG/SVG 이미지로 변환하며, 배치 처리 및 컨플루언스와 같은 도구와의 통합을 지원합니다.

사용 사례

언제 사용하면 좋은가

  • 소프트웨어 아키텍처 시각화

    개발자와 아키텍트는 코드나 구성 파일에서 아키텍처 및 배포 다이어그램을 생성하여 시스템 구성 요소와 인프라를 이해할 수 있습니다.

  • API 흐름 및 워크플로우 문서화

    기술 문서 작성자와 엔지니어는 상세한 시퀀스 및 활동 다이어그램을 만들어 API 상호 작용, 비즈니스 프로세스, 사용자 여정을 설명할 수 있습니다.

  • 설계 문서 생성 자동화

    팀은 다양한 목적(API, 시스템, 기능)에 맞는 구조화된 설계 문서를 머메이드 다이어그램이 자동으로 포함된 상태로 빠르게 생성하여 시간을 절약하고 일관성을 보장할 수 있습니다.

  • 최신 기술 문서 유지

    코드나 구성에서 직접 다이어그램을 생성하여 문서를 최신 상태로 유지하고, 공유 및 협업을 위해 이미지 형식으로 쉽게 변환할 수 있습니다.

SKILL.md

Mermaid Architect - 종합 다이어그램 및 문서화 스킬

버전 2.0 - 지능형 오케스트레이션을 갖춘 계층적 아키텍처

온디맨드 가이드 로딩, 코드-투-다이어그램 생성, 파이썬 유틸리티를 사용하여 Mermaid 다이어그램과 디자인 문서를 생성하는 강력한 Claude Code 스킬입니다.

설치

Skilz Marketplace를 통한 원클릭 설치

Skilz Marketplace에서 이 스킬을 즉시 설치하세요:

skilz install SpillwaveSolutions_design-doc-mermaid/design-doc-mermaid

수동 설치

Claude Code 스킬 디렉토리에 직접 클론합니다:

# 스킬 디렉토리로 이동
cd ~/.claude/skills

# 저장소 클론
git clone https://github.com/SpillwaveSolutions/design-doc-mermaid.git

설치 확인

설치 후 스킬이 사용 가능한지 확인하세요:

# 설치된 스킬 목록 확인
ls ~/.claude/skills/design-doc-mermaid

# 또는 Claude Code에게 물어보기
# "내 설치된 스킬 목록 보여줘"

이 스킬의 기능

지능형 다이어그램 생성:

  • 활동 다이어그램 (워크플로우, 프로세스, 비즈니스 로직)
  • 배포 다이어그램 (클라우드 인프라, K8s, 서버리스)
  • 아키텍처 다이어그램 (시스템 구성 요소, 마이크로서비스)
  • 시퀀스 다이어그램 (API 흐름, 서비스 상호작용)
  • 임베디드 다이어그램이 포함된 완전한 디자인 문서

코드-투-다이어그램 변환:

  • Spring Boot 애플리케이션에서 아키텍처 추출
  • 구성 파일에서 배포 다이어그램 생성
  • 메서드 호출에서 시퀀스 다이어그램 생성
  • ETL 파이프라인 및 데이터 흐름 문서화

다이어그램 관리:

  • 마크다운 파일에서 Mermaid 다이어그램 추출
  • mermaid-cli로 다이어그램 구문 검증
  • 다이어그램을 PNG/SVG 이미지로 변환
  • 전체 디렉토리 일괄 처리

빠른 시작

활동 다이어그램 생성

사용자: "이메일 인증이 있는 사용자 등록을 위한 활동 다이어그램 생성"

스킬이 다음을 수행합니다:

  1. references/guides/diagrams/activity-diagrams.md 로드
  2. 등록 패턴 템플릿 사용
  3. 유니코드 기호 추가 (🔐 보안, 📧 이메일, ✅ 성공)
  4. 고대비 스타일 적용
  5. 완전한 Mermaid 다이어그램 출력

코드에서 생성

사용자: "여기 내 Spring Boot application.yml이 있어 - 배포 다이어그램 생성해줘"

스킬이 다음을 수행합니다:

  1. 구성 분석 (데이터소스, 캐시, 보안)
  2. references/guides/diagrams/deployment-diagrams.md 로드
  3. examples/spring-boot/README.md 로드
  4. 구성을 클라우드 리소스에 매핑
  5. 리소스 사양과 함께 배포 다이어그램 생성

디자인 문서 생성

사용자: "연락처 API를 위한 API 디자인 문서 생성"

스킬이 다음을 수행합니다:

  1. assets/api-design-template.md 로드
  2. 관련 다이어그램 가이드 로드 (시퀀스, ER, 아키텍처)
  3. 임베디드 다이어그램이 포함된 완전한 문서 생성
  4. docs/design/api-contacts-v1-2025-01-13.md에 저장

구조

계층적 조직

mermaid-architect/
├── SKILL.md                          # 결정 트리가 있는 메인 오케스트레이터
├── README.md                         # 이 파일
├── CLAUDE.md                         # Claude Code 지침
│
├── references/                       # 참조 자료
│   ├── mermaid-diagram-guide.md     # 레거시 일반 가이드
│   └── guides/                       # 전문화된 가이드 (온디맨드 로딩)
│       ├── diagrams/
│       │   ├── activity-diagrams.md      # ✅ 완료
│       │   ├── deployment-diagrams.md    # ✅ 완료
│       │   ├── architecture-diagrams.md  # ✅ 완료
│       │   └── sequence-diagrams.md      # ✅ 완료
│       ├── code-to-diagram/
│       │   └── README.md                 # ✅ 완료 (마스터 가이드)
│       ├── unicode-symbols/
│       │   └── guide.md                  # ✅ 완료 (100개 이상 기호)
│       └── troubleshooting.md        # ✅ 완료 (28가지 일반 오류)
│
├── scripts/                          # 파이썬 유틸리티
│   ├── extract_mermaid.py           # ✅ 다이어그램 추출 및 검증
│   └── mermaid_to_image.py          # ✅ PNG/SVG로 변환
│
├── examples/                         # 언어별 패턴
│   ├── spring-boot/                 # ✅ 완료
│   ├── fastapi/                     # ✅ 완료
│   ├── react/                       # ✅ 완료
│   ├── python-etl/                  # ✅ 완료
│   ├── node-webapp/                 # ✅ 완료
│   └── java-webapp/                 # ✅ 완료
│
└── assets/                           # 디자인 문서 템플릿
    ├── architecture-design-template.md
    ├── api-design-template.md
    ├── feature-design-template.md
    ├── database-design-template.md
    └── system-design-template.md

주요 기능

1. 유니코드 의미 기호

모든 다이어그램은 의미 있는 유니코드 기호를 사용합니다:

graph TB
    User[👤 클라이언트] --> Gateway[🌐 API 게이트웨이]
    Gateway --> Auth[🔐 인증 서비스]
    Gateway --> API[⚙️ API 서비스]
    API --> DB[(💾 데이터베이스)]
    API --> Cache[(⚡ Redis)]
    API --> Queue[📬 메시지 큐]
    Queue --> Worker[⚙️ 백그라운드 워커]

기호 카테고리:

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

2. 고대비 스타일링

모든 다이어그램은 접근성이 좋은 고대비 색상을 사용합니다 - 자세한 내용은 SKILL.md를 참조하세요.

3. 파이썬 유틸리티

다이어그램 추출
# 파일의 모든 다이어그램 목록
python scripts/extract_mermaid.py document.md --list-only

# 별도의 .mmd 파일로 추출
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_image.py - output.png

요구 사항

다이어그램 생성용

  • Claude Code 스킬 시스템 (자동)
  • 가이드 및 템플릿 (이 스킬에 포함)

검증 및 이미지 변환용

# mermaid-cli 글로벌 설치
npm install -g @mermaid-js/mermaid-cli

# 설치 확인
mmdc --version

파이썬 스크립트용

  • Python 3.7+
  • 추가 패키지 필요 없음 (표준 라이브러리만 사용)

학습 경로

Mermaid 다이어그램이 처음이신가요?

  1. 활동 다이어그램으로 시작 - references/guides/diagrams/activity-diagrams.md 읽기
  2. 유니코드 기호 배우기 - references/guides/unicode-symbols/guide.md 읽기
  3. 예제 시도 - examples/spring-boot/의 패턴 사용
  4. 작업 검증 - python scripts/extract_mermaid.py --validate 실행

기존 코드 문서화가 필요하신가요?

  1. 프레임워크 식별 - Spring Boot, FastAPI, React 등
  2. 예제 가이드 로드 - examples/{your-framework}/README.md 읽기
  3. 패턴 매칭 - 예제에서 유사한 코드 패턴 찾기
  4. 다이어그램 생성 - 가이드의 템플릿 사용
  5. 검증 - 검증 스크립트 사용

디자인 문서 생성 중이신가요?

  1. 템플릿 유형 선택 - 아키텍처, API, 기능, 데이터베이스 또는 시스템
  2. 템플릿 로드 - assets/{type}-design-template.md에서 읽기
  3. 섹션 채우기 - 자리 표시자를 실제 내용으로 교체
  4. 다이어그램 추가 - 각 섹션에 필요에 따라 다이어그램 가이드 로드
  5. 기호 사용 - 전체에 유니코드 기호로 향상
  6. 저장 - 타임스탬프와 함께 docs/design/에 저장

계층적 시스템 작동 방식

전통적 접근 방식 (비효율적)

  • 전체 스킬 문서 로드 (~50KB)
  • AI가 모든 템플릿과 예제 처리
  • 높은 토큰 사용량
  • 느린 응답 시간

계층적 접근 방식 (효율적)

  1. 사용자 요청 → AI가 의도 분석
  2. 결정 트리 활성화 → 필요한 가이드 결정
  3. 필요한 것만 로드 → 특정 가이드 읽기 (~2-5KB)
  4. 출력 생성 → 대상 템플릿 사용
  5. 토큰 효율적 → 필요 컨텍스트 10배 감소

예제 흐름

사용자: "내 Docker Compose 설정에 대한 배포 다이어그램 생성"

결정 트리:

1. 분석: "배포 다이어그램" + "Docker Compose"
2. 판단: deployment-diagrams.md 필요
3. 로드: references/guides/diagrams/deployment-diagrams.md (2KB)
4. 패턴 찾기: Docker Compose 템플릿 존재
5. 생성: 템플릿 + 유니코드 기호 사용
6. 출력: 30초 이내에 완전한 다이어그램

사용된 토큰: ~2,000 (전통적 방식의 ~10,000 대비)

완료 상태

✅ 완료:

  • 계층적 결정 트리 오케스트레이터
  • 템플릿이 있는 활동 다이어그램 가이드
  • 배포 다이어그램 가이드 (AWS, GCP, K8s, 서버리스, Docker)
  • 유니코드 기호 가이드 (100개 이상 기호)
  • 검증 기능이 있는 Mermaid 추출 스크립트
  • Mermaid to 이미지 변환 스크립트
  • Spring Boot 코드-투-다이어그램 예제
  • 디자인 문서 템플릿 (5가지 유형)
  • 고대비 스타일링 시스템

🚧 진행 중:

  • FastAPI 예제
  • React 컴포넌트 아키텍처 예제
  • Python ETL 파이프라인 예제

📋 계획됨:

  • 아키텍처 다이어그램 가이드
  • 시퀀스 다이어그램 가이드
  • 코드-투-다이어그램 마스터 가이드
  • Node.js/Express 예제
  • Java 웹 앱 예제

기여하기

새 다이어그램 유형 가이드를 추가하려면:

  1. references/guides/diagrams/{type}-diagrams.md에 가이드 생성
  2. 포함 사항:
    • 사용 시기
    • 기본 구문
    • 일반적인 패턴 (3-5개 템플릿)
    • 유니코드 기호 예제
    • 모범 사례
  3. SKILL.md 결정 트리 업데이트
  4. 코드 매핑이 있는 예제 추가

새 언어 예제를 추가하려면:

  1. examples/{framework}/에 디렉토리 생성
  2. README.md 추가:
    • 프레임워크 개요
    • 구조에서 아키텍처 다이어그램
    • 구성에서 배포 다이어그램
    • 코드에서 시퀀스 다이어그램
    • 로직에서 활동 다이어그램
  3. SKILL.md 코드-투-다이어그램 테이블 업데이트

라이선스

Claude Code Skills의 일부 - MIT 라이선스

관련 스킬

  • confluence - Confluence에 다이어그램 업로드
  • plantuml - 대체 다이어그램 형식

링크

  • GitHub 저장소
  • Skilz Marketplace 목록
  • Mermaid 공식 문서

버전: 2.0.0 업데이트: 2025-01-13 유지 관리자: SpillwaveSolutions

FAQ