마크다운 및 머메이드 작성
개요
이 스킬은 과학적 문서를 마크다운에 머메이드 다이어그램을 포함한 형식을 기본 및 표준 형식으로 사용하여 작성하는 방법을 가르치고 표준을 강제합니다.
핵심 생각: .md 파일 안에 머메이드 다이어그램으로 표현된 관계는 어떤 이미지보다 가치가 있습니다. 텍스트이므로 Git에서 깔끔하게 diff됩니다. 빌드 단계가 필요 없습니다. GitHub, GitLab, Notion, VS Code 및 모든 마크다운 뷰어에서 기본적으로 렌더링됩니다. 동일한 관계를 설명하는 산문보다 더 적은 토큰을 사용합니다. 그리고 나중에 항상 정제된 이미지로 변환할 수 있습니다. 하지만 텍스트 버전은 진실의 원천(source of truth)으로 남습니다.
"보고서와 파일을 .md 형식의 일반 텍스트로 많이 만들수록, 머메이드도 간단한 '스크립트 언어'일 뿐만 아니라 더 좋습니다. 이는 다운스트림 렌더링, 특히 AI 생성 이미지(관계를 설명하기 위해 긴 형식의 텍스트 대신 머메이드를 사용하여 < 토큰)에 도움이 됩니다. 또한 머메이드는 마크다운과 함께 렌더링되어 인간이나 AI가 거의 모든 곳에서 쉽게 사용할 수 있습니다."
— Clayton Young (@borealBytes), K-Dense Discord, 2026-02-19
이 스킬을 사용해야 하는 경우
다음과 같은 경우 이 스킬을 사용하세요:
- 과학 문서 작성 — 보고서, 분석, 원고, 방법론 섹션
- 모든 문서 작성 — README, 사용 방법, 결정 기록, 프로젝트 문서
- 모든 다이어그램 작성 — 워크플로, 데이터 파이프라인, 아키텍처, 타임라인, 관계
- 버전 관리될 모든 출력물 생성 — Git에 들어간다면 마크다운이어야 함
- 다른 스킬과 함께 작업 — 이 스킬은 다른 모든 출력을 감싸는 문서 계층을 정의합니다
- 누군가 "다이어그램을 추가"하거나 "관계를 시각화"해 달라고 요청할 때 — 항상 머메이드 우선
구조적 또는 관계형 다이어그램에 Python matplotlib, seaborn 또는 AI 이미지 생성으로 시작하지 마십시오. 이는 2단계와 3단계로, 머메이드가 필요한 것을 표현할 수 없을 때만 사용합니다(예: 실제 데이터가 포함된 산점도, 사실적인 이미지).
🎨 소스 형식 철학
텍스트 기반 다이어그램이 승리하는 이유
| 중요한 점 | 마크다운의 머메이드 | Python / AI 이미지 |
|---|---|---|
| Git diff 가독성 | ✅ | ❌ 바이너리 blob |
| 재생성 없이 편집 가능 | ✅ | ❌ |
| 산문 대비 토큰 효율성 | ✅ 더 작음 | ❌ 더 큼 |
| 빌드 단계 없이 렌더링 | ✅ | ❌ 호스팅 필요 |
| 비전 없이 AI가 파싱 가능 | ✅ | ❌ |
| GitHub / GitLab / Notion에서 작동 | ✅ | ⚠️ 호스팅 시 |
| 접근성(스크린 리더) | ✅ accTitle/accDescr | ⚠️ 대체 텍스트 필요 |
| 나중에 이미지로 변환 가능 | ✅ 언제든지 | — 이미 이미지 |
3단계 워크플로
flowchart LR
accTitle: 3단계 문서화 워크플로
accDescr: 1단계 마크다운의 머메이드는 항상 필수이며 진실의 원천입니다. 2단계와 3단계는 정제된 출력을 위한 선택적 다운스트림 변환입니다.
p1["📄 1단계<br/>마크다운의 머메이드<br/>(항상 — 진실의 원천)"]
p2["🐍 2단계<br/>Python 생성<br/>(선택 사항 — 데이터 차트)"]
p3["🎨 3단계<br/>AI 생성 시각 자료<br/>(선택 사항 — 정제)"]
out["📊 최종 결과물"]
p1 --> out
p1 -.->|"필요시"| p2
p1 -.->|"필요시"| p3
p2 --> out
p3 --> out
classDef required fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
classDef optional fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
classDef output fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
class p1 required
class p2,p3 optional
class out output
1단계는 필수입니다. 2단계나 3단계로 진행하더라도 머메이드 소스는 커밋된 상태로 유지됩니다.
머메이드가 표현할 수 있는 것
머메이드는 24가지 다이어그램 유형을 다룹니다. 거의 모든 과학적 관계가 그중 하나에 적합합니다:
| 사용 사례 | 다이어그램 유형 | 파일 |
|---|---|---|
| 실험 워크플로 / 결정 로직 | Flowchart | references/diagrams/flowchart.md |
| 서비스 상호 작용 / API 호출 / 메시징 | Sequence | references/diagrams/sequence.md |
| 데이터 모델 / 스키마 | ER diagram | references/diagrams/er.md |
| 상태 머신 / 라이프사이클 | State | references/diagrams/state.md |
| 프로젝트 타임라인 / 로드맵 | Gantt | references/diagrams/gantt.md |
| 비율 / 구성 | Pie | references/diagrams/pie.md |
| 시스템 아키텍처 (확대/축소 수준) | C4 | references/diagrams/c4.md |
| 개념 계층 구조 / 브레인스토밍 | Mindmap | references/diagrams/mindmap.md |
| 시간순 이벤트 / 역사 | Timeline | references/diagrams/timeline.md |
| 클래스 계층 구조 / 유형 관계 | Class | references/diagrams/class.md |
| 사용자 여정 / 만족도 지도 | User Journey | references/diagrams/user_journey.md |
| 2축 비교 / 우선 순위 지정 | Quadrant | references/diagrams/quadrant.md |
| 요구 사항 추적성 | Requirement | references/diagrams/requirement.md |
| 흐름 크기 / 리소스 분포 | Sankey | references/diagrams/sankey.md |
| 숫자 추세 / 막대 + 선 차트 | XY Chart | references/diagrams/xy_chart.md |
| 구성 요소 레이아웃 / 공간 배열 | Block | references/diagrams/block.md |
| 작업 항목 상태 / 작업 열 | Kanban | references/diagrams/kanban.md |
| 클라우드 인프라 / 서비스 토폴로지 | Architecture | references/diagrams/architecture.md |
| 다차원 비교 / 기술 레이더 | Radar | references/diagrams/radar.md |
| 계층적 비율 / 예산 | Treemap | references/diagrams/treemap.md |
| 바이너리 프로토콜 / 데이터 형식 | Packet | references/diagrams/packet.md |
| Git 브랜칭 / 병합 전략 | Git Graph | references/diagrams/git_graph.md |
| 코드 스타일 시퀀스 (프로그래밍 구문) | ZenUML | references/diagrams/zenuml.md |
| 다이어그램 구성 패턴 | Complex Examples | references/diagrams/complex_examples.md |
💡 쉬운 유형이 아닌 올바른 유형을 선택하세요. 모든 것에 플로우차트를 기본값으로 사용하지 마십시오. 시간순 이벤트에는 타임라인이 플로우차트보다 낫습니다. 서비스 상호 작용에는 시퀀스가 플로우차트보다 낫습니다. 표를 스캔하여 일치시키세요.
🔧 핵심 워크플로
1단계: 문서 유형 식별
처음부터 작성하기 전에 템플릿이 있는지 확인하세요:
| 문서 유형 | 템플릿 |
|---|---|
| 풀 리퀘스트 기록 | templates/pull_request.md |
| 이슈 / 버그 / 기능 요청 | templates/issue.md |
| 스프린트 / 프로젝트 보드 | templates/kanban.md |
| 아키텍처 결정 (ADR) | templates/decision_record.md |
| 프레젠테이션 / 브리핑 | templates/presentation.md |
| 연구 논문 / 분석 | templates/research_paper.md |
| 프로젝트 문서 | templates/project_documentation.md |
| 사용 방법 / 튜토리얼 | templates/how_to_guide.md |
| 상태 보고서 | templates/status_report.md |
2단계: 스타일 가이드 읽기
.md 파일을 작성하기 전에: references/markdown_style_guide.md를 읽으세요.
내면화해야 할 핵심 규칙:
- 문서당 H1 하나 — 제목입니다. 더 이상 없습니다.
- H2 제목에만 이모지 — H2당 이모지 하나, H3/H4에는 없음
- 모든 항목 인용 — 모든 외부 주장은 전체 URL과 함께 각주
[^N]를 받음 - 굵게는 드물게 — 단락당 최대 2-3개의 굵은 용어, 전체 문장은 절대 안 됨
- 모든
</details>뒤에 가로줄 — 필수 - 비교, 구성, 구조화된 데이터에는 산문보다 표
- 텍스트 벽보다 다이어그램 — 흐름, 구조 또는 관계를 설명한다면 머메이드 추가
3단계: 다이어그램 유형 선택 및 가이드 읽기
머메이드 다이어그램을 만들기 전에: references/mermaid_style_guide.md를 읽으세요.
그런 다음 특정 유형 파일(예: references/diagrams/flowchart.md)을 열어 예시, 팁 및 복사-붙여넣기 템플릿을 확인하세요.
모든 다이어그램에 대한 필수 규칙:
accTitle: 짧은 이름 3-8 단어
accDescr: 이 다이어그램이 무엇을 보여주는지 설명하는 한두 문장.
%%{init}지시문 없음 — GitHub 다크 모드 깨짐- 인라인
style없음 —classDef만 사용 - 노드당 최대 이모지 하나 — 레이블 시작 부분에
snake_case노드 ID — 레이블과 일치
4단계: 문서 작성
템플릿에서 시작합니다. 마크다운 스타일 가이드를 적용합니다. 다이어그램을 별도의 "그림" 섹션이 아닌 관련 텍스트와 함께 인라인으로 배치합니다.
5단계: 텍스트로 커밋
임베디드 머메이드가 포함된 .md 파일이 커밋되는 것입니다. PNG 또는 AI 이미지도 생성한 경우, 해당 이미지는 보조 자료입니다. 마크다운이 소스입니다.
⚠️ 일반적인 함정
레이더 차트 구문 (radar-beta)
잘못됨:
radar
title Example
x-axis ["A", "B", "C"]
"Series" : [1, 2, 3]
올바름:
radar-beta
title Example
axis a["A"], b["B"], c["C"]
curve series["Series"]{1, 2, 3}
max 3
radar-beta사용,radar아님 (베어 키워드가 존재하지 않음)- 차원을 정의하려면
axis사용,x-axis아님 - 데이터 시리즈를 정의하려면
curve사용, 콜론이 있는 인용 레이블 아님 accTitle/accDescr없음 — radar-beta는 접근성 주석을 지원하지 않음. 항상 다이어그램 위에 설명적인 이탤릭체 단락을 추가하세요.
XY 차트 vs 레이더 혼동
| 다이어그램 | 키워드 | 축 구문 | 데이터 구문 |
|---|---|---|---|
| XY 차트 (막대/선) | xychart-beta | x-axis ["Label1", "Label2"] | bar [10, 20] 또는 line [10, 20] |
| 레이더 (거미/그물) | radar-beta | axis id["Label"] | curve id["Label"]{10, 20} |
지원되는 유형에서 accTitle/accDescr 잊기
일부 다이어그램 유형만 accTitle/accDescr을 지원합니다. 지원하지 않는 유형의 경우, 항상 코드 블록 바로 위에 설명적인 이탤릭체 단락을 배치하세요:
세 가지 방법을 다섯 가지 성능 차원에 걸쳐 비교하는 레이더 차트. 참고: 레이더 차트는 accTitle/accDescr을 지원하지 않습니다.
radar-beta
...
🔗 다른 스킬과의 통합
scientific-schematics와 함께
scientific-schematics는 AI 기반 출판 품질 이미지(PNG)를 생성합니다. 머메이드 다이어그램을 스케치의 브리핑으로 사용하세요:
워크플로:
1. .md에서 개념을 머메이드로 생성 (이 스킬 — 1단계)
2. 동일한 개념을 scientific-schematics에 설명하여 정제된 PNG 생성 (3단계)
3. 둘 다 커밋 — .md는 소스로, PNG는 보조 그림으로
scientific-writing와 함께
scientific-writing이 원고를 생성할 때, 모든 다이어그램과 구조적 그림은 이 스킬의 표준을 따라야 합니다. 작성 스킬은 산문과 인용을 처리하고, 이 스킬은 시각적 구조를 처리합니다.
워크플로:
1. scientific-writing을 사용하여 원고 초안 작성
2. 워크플로, 아키텍처 또는 관계를 보여주는 모든 그림에 대해:
- 자리 표시자를 이 스킬의 가이드를 따르는 머메이드 다이어그램으로 교체
3. 진정으로 사실적/복잡한 렌더링이 필요한 그림에만 scientific-schematics 사용
literature-review와 함께
Literature review는 많은 관계 데이터가 포함된 요약을 생성합니다. 이 스킬을 사용하여:
- 문헌 환경의 개념 지도(Mindmap) 생성
- 출판 타임라인 표시(Timeline 또는 Gantt)
- 방법론 비교(Quadrant 또는 Radar)
- 논문에 설명된 데이터 흐름 다이어그램(Sequence 또는 Flowchart)
출력 문서를 생성하는 모든 스킬과 함께
어떤 스킬의 문서든 최종 확정하기 전에 이 스킬의 체크리스트를 적용하세요:
- 문서가 템플릿을 사용합니까? 그렇다면 올바른 템플릿에서 시작했습니까?
- 모든 다이어그램이
accTitle+accDescr과 함께 머메이드입니까? -
%%{init}없음, 인라인style없음,classDef만? - 모든 외부 주장이
[^N]으로 인용되었습니까? - H1 하나, H2에만 이모지?
- 모든
</details>뒤에 가로줄?
📚 참조 색인
스타일 가이드
| 가이드 | 경로 | 줄 수 | 내용 |
|---|---|---|---|
| 마크다운 스타일 가이드 | references/markdown_style_guide.md | ~733 | 제목, 서식, 인용, 표, 머메이드 통합, 템플릿, 품질 체크리스트 |
| 머메이드 스타일 가이드 | references/mermaid_style_guide.md | ~458 | 접근성, 이모지 세트, 색상 클래스, 테마 중립성, 유형 선택, 복잡성 계층 |
다이어그램 유형 가이드 (24가지 유형)
각 파일에는 다음이 포함됩니다: 프로덕션 품질 예시, 해당 유형에 특화된 팁, 복사-붙여넣기 템플릿.
references/diagrams/ — architecture, block, c4, class, complex_examples, er, flowchart, gantt, git_graph, kanban, mindmap, packet, pie, quadrant, radar, requirement, sankey, sequence, state, timeline, treemap, user_journey, xy_chart, zenuml
문서 템플릿 (9가지 유형)
templates/ — decision_record, how_to_guide, issue, kanban, presentation, project_documentation, pull_request, research_paper, status_report
예시
assets/examples/example-research-report.md — 적절한 제목 계층, 여러 다이어그램 유형(flowchart, sequence, gantt), 표, 각주 인용, 접을 수 있는 섹션 및 모든 스타일 가이드 규칙이 적용된 완전한 과학 연구 보고서입니다.
📝 저작자 표시
이 스킬의 모든 스타일 가이드, 다이어그램 유형 가이드 및 문서 템플릿은 Apache-2.0 라이선스에 따라 SuperiorByteWorks-LLC/agent-project 저장소에서 이식되었습니다.
- 소스: https://github.com/SuperiorByteWorks-LLC/agent-project
- 저자: Clayton Young / Superior Byte Works, LLC (@borealBytes)
- 라이선스: Apache-2.0
이 스킬(scientific-agent-skills의 일부)은 MIT 라이선스에 따라 배포됩니다. 포함된 Apache-2.0 콘텐츠는 이 스킬 전체의 파일 헤더에 보존된 대로 저작자 표시를 유지하여 다운스트림 사용과 호환됩니다.