다이어그램 생성 스킬

목적

사용자의 설명, 문서, 코드 구조를 읽고 목적에 맞는 다이어그램 형식을 제안한 뒤 실제 다이어그램을 생성한다.

이 스킬은 ERD가 아닌 범용 시각화에 사용한다.

• 워크플로우
• 시스템/모듈 구조
• 세션 흐름
• 에이전트 협업 구조
• 문서/지식관리 구조
• 사용자 여정
• 배포/운영 흐름

핵심 원칙

• 먼저 목적과 독자를 파악한다.
• 형식이 명확하지 않으면 예시 형식을 보여주고 사용자가 선택하게 한다.
• 사용자가 빠른 결과를 원하면 AI가 가장 적합한 형식을 고르고, 선택 이유를 짧게 밝힌 뒤 바로 그린다.
• 형식 미지정 요청은 목적에 따라 자동 선택한다. 조건 분기, 합류, 계층 구조, 아키텍처, 상태 흐름, 렌더링 문서가 목적이면 Mermaid를 우선한다.
• 단순 CLI 절차, 짧은 사용 플로우, 원문 가독성이 중요한 안내는 Unicode를 사용한다.
• 사용자가 Mermaid, D2, PNG/SVG 렌더링, sequenceDiagram, C4 등 특정 형식을 명시하면 해당 형식을 우선하고 box-drawing 후보를 별도로 제안하지 않는다.
• 복잡한 관계, GitHub 렌더링, 장기 유지보수, 파일 산출이 핵심이면 Mermaid 또는 D2를 우선 고려한다.
• pure ASCII는 기본 후보에서 제외한다. 사용자가 명시하거나 Unicode 문자가 깨지는 환경이 확인된 경우에만 사용한다.
• DB 테이블 관계는 peach-erd 범위이므로 이 스킬에서 임의로 ERD 워크플로우를 대체하지 않는다.

형식 선택 가이드

형식	적합한 경우	산출물
Mermaid flowchart	조건 분기, 합류, 업무 흐름, 시스템 흐름, 계층 구조, 아키텍처 개요, hook/command 파이프라인	.mmd, Markdown Mermaid
Mermaid sequenceDiagram	주체 간 호출 순서, API 요청/응답, 에이전트 협업 순서	.mmd, Markdown Mermaid
Mermaid stateDiagram	상태 전이, 승인/검증 단계, 작업 라이프사이클	.mmd, Markdown Mermaid
Mermaid mindmap	개념 분류, 기능 목록, 문서 목차	.mmd, Markdown Mermaid
Unicode box-drawing	짧은 절차, 단순 목록형 흐름, README에서 렌더링 없이 원문 그대로 읽는 안내. 터미널풍 표현이 필요한 경우	Markdown text 코드블록
D2	미감이 중요한 아키텍처/서비스 관계도, 발표·문서용 SVG 산출	.d2, SVG/PNG
C4 스타일	시스템 경계, 컨테이너, 모듈 책임을 보여줄 때	Mermaid/D2/Structurizr 중 선택

워크플로우

1단계: 입력 파악

다음 중 무엇을 받았는지 확인한다.

• 자연어 설명
• 이미지/스케치 설명
• 문서 경로
• 코드/디렉터리 구조
• 기존 Mermaid/ASCII 초안

파일이나 코드 기반 요청이면 먼저 관련 파일을 읽어 근거를 확보한다. qmd가 설치되어 있고 대상 프로젝트 지침에 인덱스명이 있으면 해당 인덱스로 위치를 먼저 찾는다.

2단계: 형식 제안 또는 자동 선택

사용자가 형식을 지정하지 않았고 선택이 필요한 경우 아래처럼 제안한다. 조건 분기·합류·계층 구조는 Mermaid를 기본 추천으로 두고, 짧은 절차나 원문 가독성이 핵심이면 Unicode를 추천한다.

다이어그램 형식 후보입니다.

1. Mermaid flowchart
   - 장점: 흐름과 분기를 깔끔하게 렌더링 가능, SVG/PNG 저장 가능
   - 단점: 렌더러 문법에 민감하므로 라벨 작성 규칙을 지켜야 함

2. Unicode box-drawing
   - 장점: Markdown/위키 원문에서 바로 읽기 좋고 렌더링 도구가 필요 없음
   - 단점: 복잡한 관계나 자동 렌더링에는 약함. 한글 박스 정렬은 폰트/렌더러마다 흔들릴 수 있음

3. D2
   - 장점: 아키텍처/서비스 관계도를 더 현대적인 시각 품질로 렌더링하기 좋음
   - 단점: Mermaid보다 기본 지원 생태계가 좁음

제 판단으로는 [추천 형식]이 가장 적합합니다. 이유: [짧은 이유]
선택해주시면 그 형식으로 그리겠습니다. 바로 진행해도 되면 추천 형식으로 작성하겠습니다.

사용자가 "알아서", "추천해서", "바로 그려줘"라고 하면 선택 질문 없이 진행한다.

3단계: 다이어그램 작성

Unicode box-drawing

아래 규칙을 따른다.

• text 코드블록으로 제공한다.
• 상단 제목 박스를 둔다.
• 주요 노드는 ┌─┐, │, └─┘ 기반 사각형 박스로 표현한다.
• 주요 노드를 사각형 박스로 표현할 때는 라벨을 짧게 쓰고, 한글/영문 혼합으로 긴 문장을 넣지 않는다.
• 한글이 들어간 박스형 다이어그램은 표시폭이 렌더러/폰트마다 흔들릴 수 있으므로, 최종 문서에서 표시 상태를 확인한다.
• 흐름 방향은 │, ▼, ├, └ 등 box-drawing과 잘 맞는 문자를 사용한다.
• 보조 설명은 다이어그램 아래 짧은 bullet로 둔다.

예시:

┌──────────────────────────────────────────────┐
│                CLAUDE SESSION                │
└──────────────────────────────────────────────┘

┌────────────────────┐
│ SessionStart hook  │
│ cat wiki/hot.md    │
└─────────┬──────────┘
          ▼
┌────────────────────┐
│ prior context      │
│ injected           │
└─────────┬──────────┘
          ▼
┌──────────────────────────────────────────────┐
│       conversation + slash commands          │
└───────┬──────────────┬──────────────┬────────┘
        ▼              ▼              ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ wiki-ingest  │ │ save [slug]  │ │ autoresearch │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
       └────────────────┴────────────────┘
                        ▼
                ┌──────────────┐
                │ git commit   │
                │ + push       │
                └──────┬───────┘
                       ▼
                ┌──────────────┐
                │ Stop hook    │
                │ update hot   │
                └──────────────┘

Mermaid

기본은 Markdown Mermaid 코드블록으로 제공한다.

flowchart TD
    A[SessionStart hook] --> B[prior context injected]
    B --> C[conversation + slash commands]
    C --> D[/wiki-ingest]
    C --> E[/save slug]
    C --> F[/autoresearch x]
    D --> G[git commit + push]
    E --> G
    F --> G
    G --> H[Stop hook updates wiki/hot.md]

Mermaid 작성 규칙:

• 노드 라벨은 짧게 쓴다.
• 복잡한 설명은 노드 밖의 설명으로 분리한다.
• 한국어 라벨을 사용할 수 있으나 특수문자가 많으면 따옴표로 감싼다.
• 렌더링 오류가 날 수 있는 괄호, 콜론, 슬래시는 필요한 경우 라벨 문자열로 감싼다.
• /peach-* 같은 슬래시 명령은 반드시 Skill["/peach-team-dev"]처럼 quoted label로 작성한다. Skill[/peach-team-dev] 형태는 렌더러에서 파싱 오류가 날 수 있다.
• 조건 분기와 합류는 Mermaid가 Unicode보다 시인성이 좋은 경우가 많으므로, 문서용 워크플로우라도 분기가 핵심이면 Mermaid를 우선한다.

4단계: 저장 여부 판단

사용자가 파일 저장을 요청하면 기본 경로를 제안한다.

산출물	기본 경로
Mermaid 소스	docs/diagrams/{slug}.mmd
Unicode box-drawing 다이어그램	docs/diagrams/{slug}.md
D2 소스	docs/diagrams/{slug}.d2
Markdown 삽입 문서	요청 문서 내부
PNG/SVG 렌더링	docs/diagrams/{slug}.png, docs/diagrams/{slug}.svg

저장 경로가 지정되어 있으면 사용자의 경로를 우선한다.

5단계: Mermaid 렌더링

Mermaid 파일을 저장했고 사용자가 PNG/SVG 저장 또는 미리보기를 원하면 CLI를 사용한다.

npx @mermaid-js/mermaid-cli@latest \
  -i docs/diagrams/{slug}.mmd \
  -o docs/diagrams/{slug}.png \
  -s 2

npx @mermaid-js/mermaid-cli@latest \
  -i docs/diagrams/{slug}.mmd \
  -o docs/diagrams/{slug}.svg

렌더링 실패 시 Mermaid 문법을 수정하고 한 번 재시도한다.

6단계: 검증

완료 전 다음을 확인한다.

• 형식이 사용자 목적에 맞는가
• 형식 미지정 요청에서 목적에 따라 Mermaid/Unicode/D2를 선택했는가
• 자동 선택 요청에서는 선택한 형식이 목적·독자·저장/렌더링 요구에 맞는가
• Mermaid는 문법 오류 가능성이 낮은가
• Mermaid에 /peach-* 슬래시 명령이 있으면 quoted label을 사용했는가
• Unicode 박스형에 한글이 들어가면 표시폭 흔들림 위험을 점검했는가
• 저장 요청이 있었다면 실제 파일이 생성되었는가
• 렌더링 요청이 있었다면 PNG/SVG 생성 결과를 확인했는가

응답 형식

생성만 요청받은 경우:

추천 형식: [형식]
이유: [한 문장]

[다이어그램]

사용자가 형식을 명시한 경우에는 추천 형식/후보 목록을 생략하고 바로 해당 형식으로 작성한다.

파일까지 만든 경우:

생성 완료:
- 소스: docs/diagrams/{slug}.mmd
- 렌더링: docs/diagrams/{slug}.png, docs/diagrams/{slug}.svg

검증:
- Mermaid CLI 렌더링 성공