AI가 그린 Mermaid 다이어그램, 제품 수준으로 렌더링하기: Pele이 메운 문서 자동화의 마지막 퍼즐

AI 코딩 에이전트가 산출물에 포함하는 Mermaid 다이어그램이 빠르게 늘고 있습니다. 하지만 기본 렌더러는 테마나 스타일을 세밀하게 다루기 어려워 문서와 제품 UI에 그대로 쓰기에는 한계가 있습니다. 최근 공개된 Pele은 Mermaid 문법을 CSS 변수로 테마를 적용할 수 있는 SVG로 변환해 이 문제를 해결합니다. 덕분에 바이브 코딩 워크플로우에서 생성된 다이어그램을 일관된 브랜딩의 재사용 가능한 자산으로 만들 수 있습니다.

AI 코딩 도구가 Mermaid를 기본 언어로 선택한 이유

AI 기반 다이어그램 생성 도구들이 텍스트 설명을 Mermaid 코드로 바꿔 주는 기능을 앞다퉈 제공하고 있습니다. 시퀀스 다이어그램, 플로우차트, ERD, C4 아키텍처 다이어그램까지 평문 한 줄로 생성해 주는 흐름이 이미 익숙해졌습니다. Mermaid는 마크다운 코드 블록 안에 들어가는 텍스트 기반 문법이기 때문에 AI 에이전트가 자연스럽게 생성할 수 있고, 개발자도 diff로 변경 사항을 추적하고 버전 관리하기 편합니다.

실제로 바이브 코딩을 하다 보면 에이전트가 PR 설명이나 팀 위키에 아키텍처 다이어그램을 Mermaid 코드 블록으로 첨부하는 경우가 많습니다. 문제는 이 코드 블록을 렌더링하는 방식이 제각각이라는 점입니다. 기본 mermaid.js 렌더러는 SVG를 생성하지만 스타일이 인라인으로 박혀 있어서 문서나 제품에 끼워 넣으면 브랜드 색상과 어긋나는 일이 잦습니다. 표현 계층을 분리하지 않으면 AI가 아무리 좋은 다이어그램을 만들어도 실제 자산으로 쓰기 어렵습니다.

mermaid.js 기본 렌더링이 남기는 표현 계층의 공백

mermaid.js는 브라우저에서 Mermaid 코드를 SVG로 그려 주는 사실상의 표준 도구이지만, 테마 커스터마이징이 번거롭습니다. 다크 모드, 기업 브랜드 컬러, 특정 폰트 패밀리를 적용하려면 JavaScript 설정 객체를 다루거나 생성된 SVG 내부의 클래스를 직접 덮어써야 하는 경우가 많습니다. 이렇게 하면 팀마다 다른 스타일이 나타나고, AI 에이전트가 만든 다이어그램이 문서마다 제각각인 모습으로 흩어집니다.

여기서 필요한 관점은 'Mermaid 코드는 콘텐츠로 유지하고, 표현은 별도 계층으로 분리하는 것'입니다. 코드는 그대로 두고 렌더링 결과만 CSS 변수로 제어할 수 있다면, 같은 다이어그램을 다크 모드와 라이트 모드에서 각각 브랜드에 맞게 표현할 수 있습니다. 이런 요구를 정확히 겨냥한 도구가 바로 Pele입니다.

Pele: 테마 가능한 SVG로 바꾸는 경량 렌더러

Pele은 Mermaid 문법을 테마 적용 가능한 SVG로 렌더링하는 경량 라이브러리입니다. 공개된 정보에 따르면 mermaid.js보다 번들 크기가 약 6배 작고, 렌더링 속도는 100배에서 500배까지 빠르며, 외부 의존성이 없습니다. 최신 Mermaid 문법과 호환되기 때문에 AI가 생성한 다이어그램을 그대로 입력할 수 있습니다.

가장 중요한 특징은 CSS 변수로 테마를 적용한다는 점입니다. 개발자는 자신의 디자인 시스템에 정의된 색상, 선 두께, 폰트 변수를 Pele 출력 SVG에 그대로 상속시킬 수 있습니다. 별도의 JavaScript 설정 없이 CSS만으로 다크 모드 전환과 브랜드 적용이 가능하기 때문에 제품 UI나 팀 문서에 바로 통합하기 좋습니다. Mermaid 코드는 유지하면서 표현 계층만 분리할 수 있다는 뜻입니다.

바이브 코딩 파이프라인에 통합하는 실전 시나리오

예를 들어 AI 코딩 에이전트가 PR 설명에 시스템 아키텍처 다이어그램을 Mermaid 코드 블록으로 생성했다고 가정해 보겠습니다. CI 단계에서 이 코드 블록을 추출해 Pele로 SVG를 렌더링하고, 팀 위키나 PR 본문에 일관된 스타일로 삽입하는 스크립트를 구성할 수 있습니다. 이렇게 하면 PR마다 다른 스타일이 섞이는 문제가 사라지고, 다이어그램을 파일로 저장해 재사용할 수도 있습니다.

또한 '코드보다 먼저 쌓이는 문서'가 흔해지는 바이브 코딩 환경에서 Pele은 단순한 렌더러 이상의 역할을 합니다. AI 에이전트가 생성한 다이어그램을 표현 계층이 잘 정돈된 SVG 자산으로 바꿔 주기 때문에, 팀은 문서를 다시 그리거나 스타일을 고치는 수고 없이 결과물을 바로 위키와 제품에 녹여낼 수 있습니다. 이는 에이전트 산출물을 일회성 텍스트가 아니라 지속적으로 관리할 수 있는 자산으로 전환하는 핵심 단계입니다.

마무리: 에이전트 산출물을 자산으로 전환하는 마지막 퍼즐

AI가 그린 Mermaid 다이어그램은 이제 양적으로는 충분히 많아졌지만, 표현과 관리 측면에서 여전히 갭이 있었습니다. Pele은 테마 가능한 SVG 렌더링으로 이 갭을 메우고, 개발자가 Mermaid 코드를 유지한 채 재사용성과 브랜딩을 동시에 챙길 수 있게 해 줍니다. 바이브 코딩 워크플로우에서 다이어그램 생성부터 문서 통합까지의 파이프라인이 한층 매끄러워지는 셈입니다.

다만 렌더링된 SVG도 결국 사람이 검토하고 버전을 관리해야 진짜 자산이 됩니다. AI가 생성한 다이어그램과 분석을 팀이 편하게 확인하고 저장할 때마다 불변 버전으로 쌓아 두려면 md-log 같은 휴먼 인 더 루프 리뷰 레이어가 유용합니다. Pele이 표현 계층을, md-log가 검토와 아카이브를 담당하면 문서 자동화의 마지막 퍼즐이 완성됩니다.

참고 자료

• Mermaid diagrams: an AI skill for project management
• AI Diagram Generator | MermaidViewer
• AI Flowchart Generator — Text to Mermaid Diagrams
• Pele · Mermaid diagrams as themeable SVG
• kepano on X: "This is Pele, my new rendering library for diagrams and charts, compatible with the latest Mermaid syntax. - 100-500× faster than mermaid.js - 6× smaller bundle - No dependencies - Easy to theme - Responsive to device width In pursuit of making Obsidian insanely fast and cohesively… / X
• Pele – Mermaid diagrams as themeable SVG | Hacker News
• kepano on X: "Pele renders Mermaid diagrams faster than you'd run from a volcano! Read the docs and try the playground: https://t.co/z0sKkAAlXL" / X
• Obsidian on X: "Pele is a fast, beautiful, open source renderer for Mermaid diagrams we created for the next version of Obsidian. You can already try it in the Pele playground and integrate it into your own apps." / X
• Octagonal typefaces