아키텍처 다이어그램, 매번 손으로 그리기 싫어서 자동화해본 이야기

발단: Excalidraw는 좋은데 매번 그리기엔 너무 귀찮다

우리 팀은 아키텍처 설계하거나 블로그 쓸 때 항상 Excalidraw로 그림을 그린다. 깔끔하고 손그림 느낌도 나고, 뭔가 "엔지니어가 직접 그린" 감성이 있어서 좋았다.

근데 문제는, 이걸 매번 그리는 게 은근 시간이 든다는 거다.

컴포넌트 하나하나 배치하고, 화살표 연결하고, 라벨 달고. 거기에 "좀 이쁘게" 만들려면? 색 맞추고, 정렬하고, 간격 조절하고... 생각보다 1시간은 금방 날아간다. 그림 그리는 시간도 결국 비용이다.

그래서 생각했다. 이걸 자동화할 수 없을까? 최대한 인간의 개입을 줄이고, 이왕이면 우리 팀이 기존에 쓰던 Excalidraw 스타일로 뽑아낼 수 없을까?

첫 번째 시도: MCP로 Excalidraw 직접 편집하기

나는 이미 옵시디언이랑 Claude를 MCP로 연결해놓은 상태였다.

 

Excalidraw 파일 형식이 생각보다 복잡했다. JSON 구조 안에 각 요소의 좌표, 크기, 스타일, 연결 관계가 다 들어가 있는데, Claude가 이걸 정확하게 생성해서 넣어봤자 옵시디언에서 열면 오류가 뜨면서 안 열렸다. Excalidraw 라이브러리까지 다운받아서 접근시켜봤는데, 라이브러리 아이템에 이름(name)이 비어있어서 뭐가 뭔지 파악하기도 어려웠고, 결국 직접 편집은 포기했다.

진짜 머리를 싸맸다. 되게 당연히 될 줄 알았는데.

 

[정정] 나중에 알고 보니, Excalidraw 파일 형식 자체가 문제가 아니었다.

 

글을 쓰고 나서 다시 시도해봤는데, .excalidraw 파일(순수 JSON)을 직접 생성하는 건 잘 된다. excalidraw.com에서 열리고, 편집도 된다. Excalidraw JSON 스키마는 공식 문서에 잘 나와 있고, 각 element에 id, type, x, y, width, height, seed, versionNonce 같은 필드만 정확히 채워주면 된다.

그럼 뭐가 문제였냐? 옵시디언 Excalidraw 플러그인의 .excalidraw.md 형식이 문제였다. 이 플러그인은 일반 .excalidraw JSON을 그대로 저장하지 않는다. 마크다운 파일 안에 YAML frontmatter + LZ-String 압축된 JSON을 합쳐서 저장하는 자체 포맷을 쓴다. Claude가 MCP로 이 파일을 생성하려 했을 때, 이 압축 포맷을 정확히 맞추지 못해서 플러그인이 파싱에 실패한 거였다.

즉 정리하면:

• .excalidraw (순수 JSON) → ✅ Claude가 생성 가능. excalidraw.com에서 잘 열림
• .excalidraw.md (옵시디언 플러그인 전용) → ❌ LZ-String 압축 + 마크다운 래핑 때문에 실패

Mermaid는 되는데... 뭔가 부족하다

Excalidraw는 안 되지만 Mermaid는 잘 그려줬다. 텍스트 기반이라 Claude 입장에서는 훨씬 쉬운 거다. 옵시디언에서 Mermaid 렌더링도 기본 지원되니까 바로 확인도 가능했고.

 

근데 Mermaid로 아키텍처 다이어그램을 그려보면... 좀 답답하다. aws 아이콘을 넣을 수 없고, 레이아웃 제어가 제한적이고, 중첩 subgraph 쓰면 배치가 맘대로 안 되고. 화살표 방향 자유도도 낮다.

"그래, Mermaid로 대충 구조 잡고 Excalidraw로 옮기면 되지!" 라고 생각했다. 옵시디언 Excalidraw 플러그인에 Mermaid to Excalidraw 변환 기능이 있으니까.

근데 이것도 해보니까 결국 꽤 시간이 걸렸다. 변환하고 나면 위치 다 틀어져 있어서 하나하나 재배치해야 하고, 아이콘은 당연히 직접 넣어야 하고. 자동화라고 하기엔 좀 애매한 수준이었다.

Draw.io — 어? 이거 되는데?

그러다가 Draw.io를 시도해봤다. Claude한테 Draw.io XML 형식으로 출력해달라고 부탁해본 거다.

그랬더니 오. 나름 제대로 나왔다. 컴포넌트 배치도 괜찮고, 화살표 연결도 맞고, 심지어 AWS 스타일 아이콘까지 알아서 넣어줬다. Draw.io에서 File → Open으로 열면 바로 편집 가능한 상태. 물론 몇 개 아이콘은 안 맞거나 위치가 어색한 게 있었지만, 그 정도는 직접 드래그해서 고치면 됐다.

진짜 "어? 이게 된다고?" 하는 순간이었다. 한참을 Excalidraw 직접 편집이랑 Mermaid 변환으로 삽질하다가 Draw.io XML이 바로 먹히니까 좀 허무하면서도 속이 시원했다.

최종 워크플로우: 3가지 포맷 동시 생성

이것저것 실험해본 결과, 아키텍처 다이어그램 그릴 때 가장 효율적인 방법을 찾았다. Claude한테 3가지 포맷을 동시에 만들어달라고 하는 거다.

근데 왜 3가지나 필요한가? 하나로 퉁치면 안 되나? 각각 역할이 다르다.

1. React JSX — 미리보기 + 빠른 피드백용

Claude 대화창(Artifact)에서 바로 렌더링된다. 눈으로 확인하면서 "이 부분 화살표 방향 바꿔줘", "색깔 좀 바꿔줘" 같은 수정을 대화로 바로 요청할 수 있다.

솔직히 3가지 중에서 비주얼 퀄리티는 이게 제일 좋다. SVG 기반이라 깔끔하고, 색감이나 레이아웃도 예쁘게 잘 나온다.

근데 단점이 명확하다. 이건 코드다. Draw.io나 Excalidraw처럼 마우스로 드래그해서 위치 조정하거나, 컴포넌트를 옮기거나 하는 게 안 된다. 수정하려면 다시 Claude한테 말로 설명해야 한다. "왼쪽 서브넷을 오른쪽으로 옮겨줘" 같은 걸 일일이 말로 해야 하는 거다. 그래서 **"이 구조 맞는지 먼저 확인하는 용도"**로 쓴다. 최종 결과물이 아니라 미리보기.

• 장점: 비주얼 퀄리티 최고, 대화창에서 바로 확인, 수정 요청이 대화로 가능
• 단점: 마우스로 직접 편집 불가. 
• Excalidraw 변환: 사실상 불가능. 용도 자체가 다름

2. Draw.io XML — 편집용

Draw.io에서 바로 열어서 편집할 수 있다. 이게 핵심이다. 마우스로 드래그해서 위치 바꾸고, 화살표 수정하고, 텍스트 고치고. 일반적인 다이어그램 편집 경험 그대로다. 게다가 AWS, GCP 같은 클라우드 아이콘을 Draw.io 내장 라이브러리에서 끌어다 쓸 수 있다. Claude가 생성할 때부터 아이콘 스타일을 적용해주니까, 열자마자 꽤 완성도가 있다.

그리고 중요한 건, 이건 굳이 Excalidraw로 안 바꿔도 된다. Draw.io 자체가 이미 충분히 강력한 다이어그램 도구다. PNG/SVG로 내보내기도 되고, 블로그에 넣을 이미지도 바로 뽑을 수 있다. "꼭 Excalidraw 스타일이어야 해"라는 집착만 내려놓으면 여기서 끝내는 게 가장 효율적이다.

• 장점: 마우스로 자유롭게 편집, 아이콘 지원, 완성도 높음, 이미지 내보내기 편리
• 단점: Excalidraw 스타일과 다름 
• Excalidraw 변환: 직접 변환 기능은 없음. 근데 대부분의 경우 변환할 필요도 없다

3. Mermaid — Excalidraw로 가는 유일한 자동화 경로

Mermaid를 넣은 이유는 사실 하나다. Excalidraw 에 "Mermaid to Excalidraw" 변환 기능이 있다. 옵시디언 Excalidraw에서 새 파일 만들 때 Mermaid 코드를 붙여넣으면, 그걸 Excalidraw 요소들로 변환해준다.

즉, Claude가 Mermaid 코드를 생성 → 복사 → Excalidraw에 붙여넣기 → 변환. 이러면 Excalidraw 파일이 만들어진다. 변환 후에 위치 재배치나 아이콘 추가는 직접 해야 하지만, 빈 캔버스에서 0부터 시작하는 것보단 훨씬 빠르다.

• 장점: Excalidraw 변환 가능(!), 텍스트 기반이라 Git 친화적, 옵시디언 기본 렌더링 지원
• 단점: 아이콘 없음, 레이아웃 제어 제한적, 변환 후 수동 정리 필요
• Excalidraw 변환: Excalidraw 플러그인의 Mermaid to Excalidraw 기능으로 가능

프롬프트 템플릿

매번 이걸 설명하기 귀찮아서, 아예 프롬프트 템플릿을 만들었다. Claude한테 이 프롬프트만 던지면 3가지 포맷이 한 번에 나온다.

아래 아키텍처를 다이어그램으로 그려줘. 3가지 포맷으로 동시에 만들어줘:

1. **React JSX** (.jsx) — SVG 기반, 여기서 바로 미리보기용. 컬러풀하고 보기 좋게.
2. **Draw.io XML** (.drawio) — draw.io에서 바로 열 수 있는 형태. AWS/클라우드 아이콘 스타일 적용. 컴포넌트 간 화살표와 레이블 포함.
3. **Mermaid** (.mermaid) — 텍스트 기반 다이어그램. subgraph로 영역 구분, 스타일 적용.

### 디자인 규칙

- 중첩 그룹(VPC > Subnet > Instance 등)은 색상과 테두리로 구분
- 데이터 흐름 화살표는 실선, 메트릭/로그 수집은 점선
- 각 컴포넌트에 역할 이름 라벨 표기
- 외부 서비스(Slack, Email 등)는 다이어그램 밖에 배치
- 한국어 라벨 사용 (요청/응답, 알림 등)

### 아키텍처 설명:

[여기에 아키텍처를 자유롭게 설명] 예시:

- "현재 프로젝트의 코드를 분석해서 인프라 구조를 파악한 뒤 그려줘"
- "EC2 2대, RDS, S3, CloudFront로 구성된 웹서비스 아키텍처"
- "쿠버네티스 클러스터에 Istio 서비스 메시 구성"
- "이 docker-compose.yml을 보고 아키텍처를 그려줘"
- (스크린샷 첨부) "이거랑 비슷하게 그려줘"

결국 Excalidraw 직접 생성은 실패했다

원래 목표는 "Claude가 Excalidraw 파일을 직접 생성해서 옵시디언에서 바로 쓰는 것"이었는데, 그건 못 했다.

근데 현실적으로 생각해보면, Draw.io에서 완성해서 PNG로 내보내는 것만으로도 블로그 글에 쓰기엔 충분하다. "꼭 Excalidraw여야 해"라는 집착만 내려놓으면 워크플로우는 꽤 깔끔해진다. 그리고 진짜 Excalidraw가 필요한 순간에는 Mermaid를 변환 브릿지로 쓰면 된다. 완전 자동은 아니지만, 0에서 시작하는 것보다는 훨씬 낫다.

나만 겪는 게 아니었다는 걸 알게 된 게, 찾아보니 Excalidraw 형식을 프로그래밍적으로 생성하는 건 공식 라이브러리가 있긴 한데 브라우저 환경에서 돌아가는 거라 CLI나 MCP에서 쓰기엔 쉽지 않았다. 이 부분이 개선되면 진짜 풀 자동화가 가능해질 것 같다.

 

 

혹시 나처럼 매번 그림 그리기 귀찮았던 분이 있다면

상황별로 정리하면:

"빠르게 구조 확인만 하고 싶다" → React JSX. Claude 대화창에서 바로 보이고, 수정도 말로 하면 된다. 다만 마우스로 직접 만지는 건 안 되니까 최종 결과물로 쓰기보단 미리보기용.

"실무에서 편집 가능한 다이어그램이 필요하다" → Draw.io XML. 아이콘 있고, 마우스로 수정 가능하고, 이미지 내보내기도 된다. 대부분의 경우 이걸로 충분하다. 굳이 Excalidraw로 안 바꿔도 됨.

"우리 팀은 Excalidraw를 쓴다, 스타일 통일해야 한다" → Mermaid 생성 후 Excalidraw 변환. 변환 후 정리가 좀 필요하지만, 0에서 그리는 것보다는 훨씬 빠르다.

위에 공유한 프롬프트 템플릿 그대로 쓰면 3가지가 한 번에 나오니까, 상황에 맞게 골라 쓰면 된다.

일단 지금은 이 워크플로우로 만족하고 있다. 앞으로 계속 사용해보며 프롬프트를 발전시킬 계획이당.

 

정정 결론: Excalidraw 파일 생성은 가능

내가 쓴 글을 보고 다시 시도해봤더니 .excalidraw 파일 직접 생성이 잘 됐다. 한참을 "Excalidraw 형식이 복잡해서 안 돼"라고 생각하고 있었는데, 실제 원인은 옵시디언 Excalidraw 플러그인의 .excalidraw.md 포맷이었던 거다. 순수 .excalidraw JSON은 Claude가 충분히 생성할 수 있었다.

 

남은 과제: AWS 아이콘조차 클로드에게 맡길 수는 없을가?