Content Mermaid
기술 프로세스 및 구조에 대한 Mermaid 다이어그램을 생성합니다. 이는 content-diagrams의 빠르고 구문 기반 대응입니다. 동일한 시각적 명확성 기준을 따르지만, 이미 정확한 기하학을 보장하는 언어를 기반으로 하므로 좌표를 확인하는 대신 올바른 다이어그램 유형을 선택하고 읽기 쉽고 일관된 색상 시스템을 구축하는 데 노력을 집중합니다.
content-diagrams와의 관계
두 스킬 모두 동일한 기준(읽기 쉬운 텍스트, 장식이 아닌 실제 색상 시스템, 밀도보다 명확성)을 공유하지만, content-diagrams는 자체적으로 SVG 기하학을 수동으로 계산하는 반면 이 스킬은 기하학을 전적으로 Mermaid의 레이아웃 엔진에 위임합니다. 다이어그램이 실제로 표시될 위치(네이티브 Mermaid 표면 vs. 정적 이미지만 표시하는 플랫폼)에 따라 습관이 아닌 기준으로 둘 중 하나를 선택하고, 확실하지 않으면 질문하세요. Mermaid 소스는 실제 재작업 없이 정적인 독립 그래픽으로 깔끔하게 스크린샷되지 않습니다.
여기에 검증 루프가 없는 이유
content-diagrams는 대부분의 노력을 기하학에 쏟습니다: SVG 선, 상자, 레이블은 Claude가 계산한 숫자에 불과하며, 계산된 숫자는 잘못될 수 있으므로 렌더링, 스크린샷, 자르기, 확인이 필요합니다.
Mermaid는 이러한 실패 모드를 완전히 제거합니다. 노드 너비, 텍스트 줄바꿈, 화살표 경로, 요소 간 충돌 방지는 렌더러의 작업이며 Claude의 작업이 아닙니다. 렌더러는 상자 위에 레이블을 배치하거나 선을 도형을 통해 경로 지정하지 않습니다. 여기서 검증 루프(렌더링된 다이어그램 스크린샷, 자르기, 겹침 확인)를 다시 도출하는 것은 도구가 이미 보장하는 것을 확인하기 위해 토큰과 지연 시간을 낭비할 뿐입니다.
여전히 잘못될 수 있는 것은 완전히 다르며, 전적으로 텍스트와 관련됩니다:
- 잘못된 구문(닫히지 않은 괄호, 노드 ID로 사용된 예약어, 일치하지 않는 화살표 유형)
- 정의되지 않은 노드 ID를 참조하는 엣지
- 잘못된 색상 대비(서로 실제로 읽히지 않는 채우기 및 텍스트 색상)
- 콘텐츠의 실제 구조에 맞지 않는 다이어그램 유형
따라서 여기서 검증은 다음을 의미합니다: 구문을 한 번 읽어 정확성 확인, 모든 classDef가 채우기와 실제로 대비되는 텍스트 색상을 쌍으로 가지는지 확인, 다이어그램 유형이 모델링되는 내용과 일치하는지 확인. 이미지 렌더링이 필요하지 않습니다.
다이어그램 유형 선택
콘텐츠가 구조적으로 무엇인지에 따라 유형을 선택하세요. 이는 content-diagrams의 모티프 선택에 해당하는 Mermaid의 방식입니다:
| 콘텐츠 구조 | Mermaid 유형 |
|---|---|
| 분기/루프가 있는 순차적 단계(프로세스, 워크플로우, 알고리즘) | flowchart TD(위-아래) 또는 LR(파이프라인/타임라인의 경우 왼-오) |
| 행위자/서비스 간 시간 순서 메시지(API 호출, 프로토콜 교환) | sequenceDiagram |
| 엔터티의 상태와 그 사이의 전이(수명 주기, 상태 머신) | stateDiagram-v2 |
| 데이터 모델 / 엔터티 관계(스키마, DB 테이블) | erDiagram |
| 객체 지향 구조(클래스, 상속, 인터페이스) | classDiagram |
| 기간과 종속성이 있는 일정 | gantt |
| 엄격한 순서가 없는 계층적 분류 / 브레인스토밍 | mindmap |
| 시간순 서사(프로젝트 기록, 버전 기록) | timeline |
| 2축 우선순위 지정(영향 vs. 노력 등) | quadrantChart |
모든 것을 flowchart로 기본 설정하지 마세요. "서비스가 서로를 호출하는 방식을 다이어그램으로 보여줘"와 같은 요청은 상자와 화살표로 그리기 쉽지만 sequenceDiagram에 해당합니다. "티켓이 거치는 상태를 보여줘"와 같은 요청은 다이아몬드가 상태를 대신하는 플로우차트가 아니라 stateDiagram-v2입니다.
색상 및 가독성 시스템
여기가 수동 검증이 여전히 중요한 유일한 곳입니다. Mermaid는 불평 없이 읽을 수 없는 색상 선택을 기꺼이 렌더링하기 때문입니다.
규칙: 모든 classDef는 채우기와 의도적으로 대비되도록 선택된 텍스트 색상을 쌍으로 가져야 합니다. color를 설정하지 않고 테마의 기본값이 작동하기를 바라지 마십시오. Mermaid의 기본 팔레트(검은색 텍스트가 있는 부드러운 녹색/분홍색/파란색)는 채우기와 텍스트가 함께 선택되었기 때문에 괜찮습니다. fill을 더 채도가 높거나 어두운 것으로 재정의하는 순간 color도 명시적으로 설정해야 합니다. 그렇지 않으면 일반적인 결함, 즉 상자는 읽을 수 있지만 텍스트가 실제로 대비되지 않는 현상을 재현하게 됩니다.
두 가지 팔레트 레시피 중 하나를 선택하여 하나의 다이어그램에 있는 모든 클래스에 일관되게 사용하십시오(혼합하지 마십시오):
- 진한 채우기 / 흰색 텍스트(기본값 — 입증됨, 높은 대비, 밝은 테마와 어두운 테마 모두에서 잘 읽힘):
classDef category1 fill:#1e3a5f,stroke:#0d1f33,stroke-width:2px,color:#ffffff - 밝은 색조 채우기 / 어두운 텍스트 / 채도 높은 테두리(다이어그램이 밝은 색조 규칙을 따르는 content-diagrams SVG 옆에 시각적으로 배치되어야 할 때 사용):
classDef category1 fill:#e1f0ff,stroke:#1e3a5f,stroke-width:2px,color:#1a1a1a
content-diagrams의 규칙을 직접 차용합니다: 카테고리당 하나의 색조, 해당 카테고리가 나타나는 모든 곳에 적용 — 한 번의 역할이 아닌, 해당 역할의 모든 노드에 동일한 채우기/테두리 색상. 역할별로 색조를 할당하십시오(예:
- 파란색 → 입력 / 데이터 / 백로그 항목
- 녹색 → 프로세스 / 활성 작업 단계
- 호박색 또는 갈색 → 결정 지점 / 게이트
- 보라색 → 출력 / 릴리스 / 종료 상태
- 빨간색 → 피드백 루프 / 실패 경로 / 회고
호스트의 밝음/어두움 모드에 의존하지 않도록 캔버스를 고정하십시오. 다이어그램의 첫 번째 줄에 init 지시문을 넣으십시오:
%%{init: {'theme': 'base', 'themeVariables': { 'fontFamily': 'Trebuchet MS, Verdana, Arial, sans-serif', 'fontSize': '16px', 'primaryColor': '#1e3a5f', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0d1f33', 'lineColor': '#666666', 'background': '#ffffff' } } }%%
theme: 'base'와 명시적인 themeVariables는 호스트 환경이 기본값으로 설정된 Mermaid 테마에 관계없이 다이어그램이 동일하게 보이도록 합니다. 기본 테마 이름(default, dark, forest 등)만으로는 충분하지 않습니다. 실제 색상은 렌더러가 결정하는 대로 남겨지기 때문입니다.
글꼴 크기: 노드가 몇 개 이상 있는 다이어그램의 경우 최소 16px; 다이어그램이 충분히 간단하여 가독성이 문제가 되지 않는 경우에만 14px. 다이어그램이 레이블을 맞추기 위해 14px 미만으로 축소되어야 한다면, 이는 content-diagrams에서와 동일한 "밀도보다 명확성" 신호입니다. 다이어그램을 분할하거나 콘텐츠를 줄이고, 텍스트를 더 이상 줄이지 마십시오.
스타일 적용 범위는 다이어그램 유형에 따라 다릅니다: flowchart, stateDiagram-v2, classDiagram은 모두 노드별 classDef/class 할당을 직접 지원하므로 위의 카테고리-색상 시스템을 노드별로 사용하십시오. sequenceDiagram, erDiagram, gantt는 요소별 스타일링이 훨씬 제한적입니다. 이러한 경우 노드 수준 클래스가 동일한 방식으로 작동할 것이라고 기대하기보다는 init 블록의 themeVariables(actorBkg, actorTextColor, noteBkgColor 등)에 노력을 기울이십시오.
화살표 문법
수동 코딩된 SVG와 달리 Mermaid는 -->|label| 텍스트가 수동으로 배치된 SVG 레이블처럼 도형 위에 떨어질 위험 없이 화살표 레이블을 자동 배치로 깔끔하게 렌더링합니다. 따라서 content-diagrams의 "텍스트를 화살표에서 멀리 유지, 범례로 해독" 기본값과 달리, 화살표에 직접 레이블을 지정하는 것은 괜찮으며 종종 더 명확합니다. 여기서도 레이블은 구문이 아닌 태그이므로 레이블을 짧은 조각("approved", "retry", "on failure")으로 유지하십시오.
content-diagrams에서 사용하는 동일한 광범위한 구분을 위해 선 스타일을 예약하십시오:
- 실선 화살표(
-->) → 기본/일반 흐름 - 점선 화살표(
-.->) → 피드백, 선택적 경로 또는 외부/간접 상호 작용 - 두꺼운 화살표(
==>) → 강조되거나 중요한 경로, 드물게 사용
레이블을 짧게 유지하고 서브그래프를 사용하여 그룹화
노드 텍스트는 짧은 구문이어야 하며 문장이 아니어야 합니다. Mermaid는 다른 도구와 마찬가지로 단락 길이의 레이블에서 어색하게 줄바꿈되거나 넘칠 수 있습니다. 노드에 여러 줄이 필요한 경우 자동 줄바꿈이 합리적인 위치에서 끊길 것이라고 믿기보다 레이블 안에 <br/>를 명시적으로 삽입하십시오.
subgraph를 사용하여 관련 단계를 클러스터링하십시오(예: 하나의 스프린트, 하나의 배포 단계, 하나의 서비스 경계 내 모든 것). 이는 그룹화 상자에 해당하는 Mermaid이며 style SubgraphName fill:...,stroke:... 줄로 자체 스타일을 지정할 수 있습니다. 서브그래프를 한 단계 이상 중첩하지 마십시오. 빠르게 읽기 어려워집니다.
워크플로우
- 기본 구조를 식별하고 구문을 작성하기 전에 위의 표에서 다이어그램 유형을 선택하십시오.
- 존재하는 역할(입력, 프로세스 단계, 결정, 출력, 피드백)에 카테고리 색상을 할당하십시오. classDef를 작성하기 전에 한두 문장으로 스케치하여 content-diagrams의 "모티프 추론 스케치" 단계와 동일하게 선택이 감사 가능하도록 하십시오.
- 다이어그램을 작성하십시오.
%%{init: ...}%%지시문으로 시작한 다음 구조, 그 다음classDef/class할당(또는 노드별 클래스를 지원하지 않는 유형의 경우 themeVariables)을 작성하십시오. - 구문을 자체 점검하십시오 — 엣지에 사용된 모든 노드 ID가 어딘가에 정의되어 있는지, 모든
classDef에fill과color가 모두 설정되어 있는지, 괄호/따옴표가 균형을 이루는지, 단락 길이의 레이블이 없는지 확인하십시오. 렌더링, 스크린샷 없음. - 아티팩트로 인라인 렌더링되도록
create_file을 통해.mermaid파일로 저장하십시오. 설명적인 슬러그를 사용하십시오:/mnt/user-data/outputs/<slug>.mermaid.present_files로 표시하십시오. - 사용자가 이식 가능한 정적 이미지로 다이어그램이 필요한 경우(Mermaid를 렌더링하지 않는 곳에 임베드하거나 보관 목적으로) 다음과 같이 명확히 말하십시오: 이 환경은 헤드리스 Mermaid-이미지 내보내기를 안정적으로 실행하지 않습니다(샌드박스된 네트워크가 일반적으로 도달할 수 없는 Chromium 다운로드에 의존함). 수동 내보내기를 위해 mermaid.live를 가리키거나, 실제 요구 사항이 독립 실행형 그래픽인 경우
content-diagrams로 전환하십시오.
하지 말아야 할 것
fill을 재정의한 후classDef의color를 설정하지 않은 상태로 두지 마십시오. 이것이 바로 이 스킬이 존재하는 정확한 대비 버그입니다.- 하나의 다이어그램 내에서 진한 채우기와 밝은 채우기 팔레트 레시피를 혼합하지 마십시오.
- 모든 요청을 기본적으로
flowchart로 설정하지 마십시오. 실제 구조(시퀀스, 상태, ER 등)와 일치하는 유형을 선택하십시오. - 여기서 content-diagrams의 렌더링/자르기/확인 루프를 재도입하지 마십시오. 이는 Mermaid의 레이아웃 엔진에는 없는 문제를 해결하는 것입니다.
- 노드 레이블에 단락 길이의 텍스트를 넣지 마십시오.
<br/>로 줄바꿈하거나 콘텐츠를 줄이십시오. - 서브그래프를 한 수준 이상 중첩하지 마십시오.
- 헤드리스 Mermaid 렌더링이 여기서 작동하지 않을 수 있다는 주의 사항 없이 이 샌드박스에서 깨끗한 PNG/SVG 내보내기를 약속하지 마십시오.