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

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

- Canonical: https://nanoskill.ai/ko/skills/mermaid-agent-skill
- Markdown: https://nanoskill.ai/ko/skills/mermaid-agent-skill.md
- Author: SpillwaveSolutions
- Published: 2026-05-26T01:25:42.765Z
- Updated: 2026-07-19T03:48:37.206Z
- Language: ko
- Source type: github
- Popularity signal: 66

## Sources

- https://github.com/spillwavesolutions/design-doc-mermaid

## Install

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

## About

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

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

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

## Key features

- **지능형 다이어그램 생성**: 워크플로우, 인프라, 시스템 구성 요소, API 흐름을 위한 활동, 배포, 아키텍처, 시퀀스 다이어그램 등 다양한 머메이드 다이어그램을 생성합니다.
- **코드-다이어그램 변환**: 기존 코드베이스(예: 스프링 부트, FastAPI)나 구성 파일에서 다이어그램을 자동으로 생성하여 아키텍처, 배포, 시퀀스 흐름을 시각화합니다.
- **포괄적인 설계 문서 생성**: 아키텍처, API, 기능, 데이터베이스, 시스템 설계를 위한 사전 정의된 템플릿을 사용하여 머메이드 다이어그램이 포함된 완전한 설계 문서를 생성합니다.
- **유니코드 의미 기호 및 고대비 스타일링**: 100개 이상의 의미 있는 유니코드 기호와 가독성 향상을 위한 고대비 색상 구성표로 다이어그램의 명확성과 접근성을 높입니다.
- **다이어그램 관리를 위한 파이썬 유틸리티**: 파이썬 스크립트를 사용하여 머메이드 다이어그램을 추출, 검증하고 PNG/SVG 이미지로 변환하며, 배치 처리 및 컨플루언스와 같은 도구와의 통합을 지원합니다.

## Use cases

- **소프트웨어 아키텍처 시각화**: 개발자와 아키텍트는 코드나 구성 파일에서 아키텍처 및 배포 다이어그램을 생성하여 시스템 구성 요소와 인프라를 이해할 수 있습니다.
- **API 흐름 및 워크플로우 문서화**: 기술 문서 작성자와 엔지니어는 상세한 시퀀스 및 활동 다이어그램을 만들어 API 상호 작용, 비즈니스 프로세스, 사용자 여정을 설명할 수 있습니다.
- **설계 문서 생성 자동화**: 팀은 다양한 목적(API, 시스템, 기능)에 맞는 구조화된 설계 문서를 머메이드 다이어그램이 자동으로 포함된 상태로 빠르게 생성하여 시간을 절약하고 일관성을 보장할 수 있습니다.
- **최신 기술 문서 유지**: 코드나 구성에서 직접 다이어그램을 생성하여 문서를 최신 상태로 유지하고, 공유 및 협업을 위해 이미지 형식으로 쉽게 변환할 수 있습니다.

## Result preview

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

![mermaid-architect-demo1](https://file.nanoskill.ai/mermaid-architect-demo1.jpg)

![mermaid-architect-demo-2](https://file.nanoskill.ai/mermaid-architect-demo-2.jpg)

![mermaid-architect-demo-3](https://file.nanoskill.ai/mermaid-architect-demo-3.jpg)

## Result walkthrough

### 1단계：설치

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

![mermaid-architect-step-1](https://file.nanoskill.ai/mermaid-architect-step-1.jpg)

### 2단계：프로세스 설명

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

![mermaid-architect-step-2](https://file.nanoskill.ai/mermaid-architect-step-2.jpg)

### 3단계：결과 검토

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

![mermaid-architect-step-3](https://file.nanoskill.ai/mermaid-architect-step-3.jpg)

## Skill definition

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

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

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

## 설치

### Skilz Marketplace를 통한 원클릭 설치

[Skilz Marketplace](https://skillzwave.ai/skill/SpillwaveSolutions__design-doc-mermaid__design-doc-mermaid__SKILL/)에서 이 스킬을 즉시 설치하세요:

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

### 수동 설치

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

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

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

### 설치 확인

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

```bash
# 설치된 스킬 목록 확인
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. 유니코드 의미 기호

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

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

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

### 2. 고대비 스타일링

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

### 3. 파이썬 유틸리티

#### 다이어그램 추출

```bash
# 파일의 모든 다이어그램 목록
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
```

#### 이미지로 변환

```bash
# 단일 파일
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 스킬 시스템 (자동)
- 가이드 및 템플릿 (이 스킬에 포함)

### 검증 및 이미지 변환용
```bash
# 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 저장소](https://github.com/SpillwaveSolutions/design-doc-mermaid)
- [Skilz Marketplace 목록](https://skillzwave.ai/skill/SpillwaveSolutions__design-doc-mermaid__design-doc-mermaid__SKILL/)
- [Mermaid 공식 문서](https://mermaid.js.org/)

---

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

## FAQ

### 이 스킬은 어떤 유형의 머메이드 다이어그램을 생성할 수 있나요?

이 스킬은 활동 다이어그램, 배포 다이어그램, 아키텍처 다이어그램, 시퀀스 다이어그램을 생성할 수 있습니다. 워크플로우, 클라우드 인프라, 시스템 구성 요소, API 상호 작용의 시각화를 지원합니다.

### 코드-다이어그램 변환은 어떻게 작동하나요?

이 스킬은 코드 또는 구성 파일(예: 스프링 부트 application.yml)을 분석하고 사전 정의된 패턴과 가이드를 사용하여 배포 또는 시퀀스 다이어그램과 같은 해당 머메이드 다이어그램을 자동으로 생성합니다.

### 이 스킬로 전체 설계 문서를 만들 수 있나요?

예, 이 스킬에는 다양한 설계 문서(아키텍처, API, 기능, 데이터베이스, 시스템)용 템플릿이 포함되어 있습니다. 입력과 선택한 템플릿을 기반으로 머메이드 다이어그램이 포함된 완전한 문서를 생성할 수 있습니다.

### 머메이드 다이어그램 생성을 위한 계층적 시스템의 이점은 무엇인가요?

계층적 시스템은 의도를 효율적으로 분석하고 전체 스킬 문서 대신 필요한 가이드와 템플릿(일반적으로 2-5KB)만 로드합니다. 이를 통해 토큰 사용량이 크게 줄고 응답 시간이 빨라집니다.

### 이 스킬에 포함된 파이썬 유틸리티가 있나요?

예, 이 스킬은 마크다운 파일에서 머메이드 다이어그램을 추출하고 구문을 검증하여 PNG 또는 SVG 이미지 형식으로 변환하는 파이썬 스크립트를 제공합니다. 이러한 유틸리티는 배치 처리도 지원합니다.

### 유효성 검사 및 이미지 변환 기능을 사용하기 위한 요구 사항은 무엇인가요?

다이어그램 유효성 검사 및 이미지 변환을 위해서는 npm을 통해 \`mermaid-cli\`를 전역으로 설치해야 합니다 (\`npm install -g @mermaid-js/mermaid-cli\`). 파이썬 스크립트는 Python 3.7+가 필요합니다.