AI(Claude나 ChatGPT)에게 시스템 구성도나 플로우차트(Flowchart)를 그리게 하는 것은 이제 드문 일이 아닙니다. 하지만 AI가 출력하는 Mermaid 등의 도표는 "구조는 맞지만,見た目(외관)이 수수하다", "아이콘이나 스크린샷을 넣고 싶지만 코드로 작업하기는 번거롭다"라는 고민이 따르기 마련입니다.

그래서 이번에는 **"AI에게 Mermaid로 도표의 구조(80%)를 만들게 하고, Excalidraw로 변환한 뒤, 사람이 수작업으로 미세 조정 및 이미지를 삽입하여 깔끔하게 완성하는(20%)"**라는 하이브리드 방식을 소개합니다.

또한, 환경 구축 없이 Mermaid를 Excalidraw 형식으로 일괄 변환할 수 있는 스크립트가 포함된 템플릿 모음도 공개하고 있습니다.

🔗 GitHub 리포지토리: thirtypower/Adraw

왜 이것을 사용하는가? (배경)

문서 작성에 있어 "이해하기 쉬운 도표"는 필수적이지만, 작성에는 매우 많은 시간이 소요됩니다.

Mermaid나 D2와 같은 코드 기반(Code-based) 도해 도구는 AI와의 궁합이 좋아 순식간에 도표의 로직을 만들 수 있지만, "클라우드 아이콘을 배치하고 싶다", "실제 화면 캡처를 옆에 붙이고 싶다"와 같은 리치(Rich)한 표현에는 적합하지 않습니다.

반면, Excalidraw와 같은 드로잉(Drawing) 도구는 이미지 삽입이나 손그림 스타일의 조정이 자유자재로 가능하지만, 처음부터 사각형이나 화살표를 배치하는 것은 번거롭습니다.

이 두 가지의 "장점만을 취하는 것"이 본 접근 방식입니다.

어떤 장점이 있는가?

압도적인 시간 단축

처음부터 도형을 나열하거나 텍스트를 입력하는 작업은 AI가 모두 해줍니다. 사람은 "이미 완성에 가까운 상태의 캔버스"에서 작업을 시작할 수 있습니다.

디자인과 배치의 완전한 자유

선의 색상, 겹침, 두께 등을 사람이 보기 편하도록 직관적으로 미세 조정할 수 있습니다. AI가 만든 답답한 레이아웃도 마우스로 가볍게 넓힐 수 있습니다.

이미지나 아이콘의 자유로운 삽입 (최강의 장점)

Excalidraw로 변환한 후에는 AWS/GCP 아이콘, 실제 UI 스크린샷, 팀 로고 등을 드래그 앤 드롭으로 자유롭게 붙일 수 있습니다. 코드 기반으로는 어려운 리치한 표현을 간단하게 구현할 수 있습니다.

논리적 오류 방지

AI와 텍스트(Mermaid) 기반으로 로직을 검토함으로써, 사전에 구조의 정합성을 확보할 수 있습니다.

구체적인 도표 예시 (Before / After)

예를 들어, AI에게 다음과 같은 간단한 Mermaid 코드를 작성하게 했다고 가정해 봅시다.

이를 본 기사의 스크립트로 .excalidraw로 변환하고, 사람이 약간의 손을 더하면 어떻게 될까요?

🛠️ Excalidraw에서의 수작업 (마무리) 예시:

User의 둥근 도형 옆에 실제 스마트폰 화면 스크린샷을 붙인다.

Web 서버 사각형을 AWS의 EC2 아이콘으로 교체한다.

데이터베이스를 AWS의 RDS 아이콘으로 바꾸고, 선을 주황색으로 변경하여 눈에 띄게 만든다.

전체 배치를 세로에서 가로로 드래그하여 여유 있게 만든다.

이와 같이, "뼈대는 AI가 쓰고, 사람은 아이콘이나 이미지를 툭툭 놓으며 보기 좋게 다듬기만 하면" 발표 자료 수준의 고퀄리티 도해를 몇 분 만에 완성할 수 있습니다.

Mermaid → Excalidraw 변환 스크립트

Node.js 환경을 준비하지 않아도, Windows 표준인 PowerShell과 Edge 브라우저(Headless 모드)를 사용하여 변환할 수 있는 스크립트를 작성했습니다.

@excalidraw/mermaid-to-excalidraw라는 공식 라이브러리를 브라우저 상에서 실행하여 결과 JSON을 추출하는 방식입니다.

# =============================================================
# mmd2excalidraw.ps1 — Mermaid(.mmd)를 Excalidraw(.excalidraw)로 변환
# 사용법: .\mmd2excalidraw.ps1 -MmdPath input.mmd -OutPath output.excalidraw
...

스크립트의 포인트

• Mermaid 기술에는 따옴표나 기호가 많이 포함되어 있으므로, Base64 인코딩을 통해 JS에 전달함으로써 이스케이프(Escape)로 인한 에러를 회피합니다.
• Node.js나 npm 환경 구축은 필요하지 않습니다. Windows 표준인 Edge를 이용합니다.

사용법

• 리포지토리의 스크립트를 사용하거나, 위 내용을 mmd2excalidraw.ps1로 저장합니다.
• AI가 생성한 Mermaid 코드를 sample.mmd 등의 이름으로 저장합니다.
• PowerShell에서 다음 명령어를 실행합니다.

.\mmd2excalidraw.ps1 -MmdPath sample.mmd -OutPath sample.excalidraw

그러면 sample.excalidraw 파일이 생성됩니다.

그 후 이 파일을 excalidraw.com에 드래그 앤 드롭하거나, VS Code의 Excalidraw 확장 기능으로 열기만 하면 됩니다!

향후 운용 및 정밀도 향상 방법

이 기법을 팀이나 개인 차원에서 더욱 강력하게 만들기 위한 운용 포인트입니다.

• 템플릿 축적: 본 리포지토리(Adraw)와 같이, "시스템 구성도", "처리 흐름도" 등의 정형화된 패턴을 AI용 프롬프트(CLAUDE.md 등)로 정의해 두면 출력이 안정화됩니다.
• 프롬프트 정교화: 초기 단계부터 Mermaid 구문 내에 "이 부분은 파란색으로 설정해줘"와 같이 스타일 지정(Style specification)을 포함하도록 AI에게 지시함으로써, 인간의 수작업(남은 20%)을 더욱 줄일 수 있습니다.
• 개인 의존성(Silo) 제거: 완성된 도표를 .excalidraw 파일로 리포지토리에 저장해 두면, 나중에 누구나 브라우저상에서 쉽게 편집 및 재사용이 가능해집니다.

마치며

"구조화나 언어화는 AI에게 맡기고, 시각적인 미세 조정이나 이미지 삽입만 인간이 수행한다"는 분업 스타일은 문서 작성에 있어 매우 효율적입니다.

여러분도 꼭 한번 시도해 보세요!

Discussion