이미지 생성 AI로 만든 도표가 수정하기 어렵고, 글마다 색과 배치가 달라지고, 웹페이지에 넣을 때 다시 손봐야 한다면 작업 흐름이 잘못된 것입니다.
가장 빠른 해법은 diagram-design을 Claude Code 스킬로 연결해 재사용 가능한 HTML과 인라인 SVG를 먼저 만드는 것입니다.
이 글은 Claude Code에서 기술 도표를 바로 만들고 싶은 개발자, 블로그와 제품 문서의 시각 스타일을 통일하려는 콘텐츠 팀, 에이전트 스킬 자동화를 검토하는 기술 책임자를 위한 안내서입니다.
마지막 업데이트: 2026년 8월 14일. 프로젝트 저장소의 안내 문서, 스킬 파일, 참고 파일과 최근 변경 내용을 기준으로 확인했습니다.
이미지가 아니라 편집 가능한 문서가 필요한 이유
기존 이미지 생성 방식은 보기 좋은 한 장을 만드는 데는 유리하지만 기술 문서에는 세 가지 문제가 남습니다.
첫째, 노드 이름이나 화살표 방향을 바꾸려면 원본 프롬프트부터 다시 작성해야 합니다. 둘째, 같은 팀이 만든 그림인데도 글꼴과 강조 색이 매번 달라집니다. 셋째, 웹페이지에 넣을 때 이미지 파일, 크기 조정, 대체 텍스트, 다시 내보내기 과정을 따로 관리해야 합니다.
diagram-design은 이 문제를 일반적인 그림 생성으로 풀지 않습니다. 프로젝트 안에 있는 스킬 지침과 참고 파일을 읽고, 설명 문장을 구조화한 뒤, 독립 실행이 가능한 HTML 안에 SVG를 넣는 방식입니다. 공식 저장소는 외부 자바스크립트, 빌드 과정, 별도 이미지 파일 없이 브라우저에서 열 수 있는 정적 결과물을 목표로 설명합니다. 공식 저장소의 출력 구조와 지원 유형을 확인하면 이 도구가 그림보다 문서 자동화에 가깝다는 점을 이해할 수 있습니다.
장면별 활용 방식
기술 블로그와 제품 문서
diagram-design은 어떤 도구인가요?
diagram-design은 Claude Code에 설치하는 서드파티 에이전트 스킬입니다. Claude Code의 기본 내장 기능이 아닙니다. 스킬은 필요한 순간에 지침과 참고 자료를 불러와 특정 작업을 수행하도록 확장하는 구조이며, Claude Code는 개인 경로나 프로젝트 경로의 스킬을 자동으로 찾을 수 있습니다. Claude Code 스킬 공식 문서는 스킬의 설치 위치, 자동 호출, 직접 호출 방식을 설명합니다.
기술 블로그에서는 다음처럼 요청할 수 있습니다.
이 서비스의 인증 흐름을 기술 블로그용 흐름도로 만들어 주세요.
결과는 독립 실행 HTML로 저장하고, 핵심 경로만 강조해 주세요.
생성 결과는 본문에 바로 삽입할 HTML이 될 수 있고, 필요하면 SVG나 PNG로 분리할 수 있습니다. HTML은 설명 카드와 제목을 포함한 문서형 결과에 적합합니다. SVG는 웹페이지의 인라인 요소, 디자인 도구, 발표 자료에 더 적합합니다.
구조도와 처리 흐름
공식 저장소에는 구조도, 흐름도, 순서도, 상태 전이도, 개체 관계도, 시간 흐름도, 수영 레인, 사분면, 계층 구조, 조직도, 벤 다이어그램, 층 구조, 깔때기, 방사형 차트, 반복 고리, 데이터 흐름 등 여러 시각 유형이 정리되어 있습니다. 현재 저장소는 27개의 시각 유형을 제공한다고 설명합니다. 지원 유형과 출력 예시를 작업 전에 확인하는 편이 좋습니다.
장면별 선택은 다음과 같이 나누면 됩니다.
- 서비스 구성 요소와 연결 관계는 구조도를 선택합니다.
- 조건과 분기 중심의 설명은 흐름도를 선택합니다.
- 시간 순서에 따른 요청과 응답은 순서도를 선택합니다.
- 로그인, 결제, 배포처럼 상태 변화가 핵심이면 상태 전이도를 선택합니다.
- 팀별 책임과 병렬 작업은 수영 레인으로 나눕니다.
- 기존 시스템과 개선 방향을 비교할 때는 현재 상태 구조나 층 구조를 사용합니다.
다만 구성 요소를 많이 넣는다고 좋은 도표가 되지는 않습니다. 저장소의 가져오기 규칙은 상세 수준을 세 단계로 나누며, 단순화 단계에서는 7개 이하, 균형 단계에서는 12개 이하, 충실 단계에서는 24개 이하의 노드 예시를 사용합니다. 이 수치는 모든 입력에 적용되는 강제 제한이라기보다 복잡도를 관리하기 위한 기준입니다. 가져오기 세부 수준과 축약 규칙을 참고해 처음부터 핵심 경로를 줄여 요청하는 것이 안전합니다.
브랜드 콘텐츠 생산
브랜드 색을 자동으로 입히면 기업용 디자인이 완성되나요?
그렇지는 않습니다. diagram-design은 웹사이트를 읽어 배경색, 기본 글자색, 강조 색, 글꼴 계열을 의미 역할로 매핑할 수 있습니다. 하지만 처음 적용한 결과는 브랜드 시스템의 초안으로 봐야 합니다. 로고 주변 여백, 인쇄용 색상, 접근성 기준, 부서별 예외 규칙까지 자동으로 보장하는 것은 아닙니다.
실무에서는 다음 순서가 안정적입니다.
- 콘텐츠 팀의 대표 웹페이지 주소를 준비합니다.
- Claude Code에 사이트 스타일을 읽고 도표용 규칙으로 정리해 달라고 요청합니다.
- 색상과 글꼴 매핑 결과를 사람이 검토합니다.
- 강조 색을 모든 노드에 적용하지 않고 핵심 경로에만 남깁니다.
- 완성된 스타일 파일을 프로젝트에 보관합니다.
- 새 도표를 만들 때 같은 스타일 파일을 다시 사용합니다.
이 과정을 거치면 글마다 새로 색을 고르는 시간이 줄어듭니다. 반대로 기본 팔레트를 그대로 사용하면 도표는 깔끔해 보여도 회사 브랜드와 일치한다고 말하기 어렵습니다. 기본 스타일과 브랜드 스타일을 구분하는 것이 구매와 도입 판단에서 중요합니다.
Claude Code 실행 흐름
Claude Code에서 diagram-design을 어떻게 호출하나요?
공식 저장소가 안내하는 플러그인 설치 흐름은 다음과 같습니다.
/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design
수정 가능한 설치가 필요하면 저장소를 복제한 뒤 스킬 경로를 연결할 수 있습니다.
git clone git@github.com:cathrynlavery/diagram-design.git ~/code/diagram-design
ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design
운영 환경에서는 단순히 설치 명령만 실행하지 말고 다음 절차를 지키는 편이 좋습니다.
- 별도 테스트 프로젝트를 만듭니다.
- 플러그인 설치 또는 로컬 경로 연결을 선택합니다.
- 새 Claude Code 세션에서 스킬이 보이는지 확인합니다.
- 작은 흐름도부터 생성해 HTML이 열리는지 확인합니다.
- 프로젝트의 스타일 지침을 검토하고 기본값을 그대로 쓰지 않습니다.
- 구조도나 순서도를 실제 문서 크기에 맞게 다시 생성합니다.
- 마지막으로 SVG와 PNG를 각각 내보내 결과를 확인합니다.
생성된 SVG는 수정할 수 있나요?
수정할 수 있습니다. SVG는 선, 글자, 경로가 포함된 벡터 문서이므로 Figma나 Illustrator 같은 편집 도구에서 일부 요소를 조정할 수 있습니다. 다만 이것은 원본 의미 구조가 보존된다는 뜻은 아닙니다. 내보낸 SVG는 시각 결과이며, 노드와 연결 관계를 다시 계산하는 원본 모델이 아닐 수 있습니다. 큰 구조를 바꿀 때는 SVG를 직접 고치기보다 Claude Code에서 HTML을 다시 생성하는 편이 안전합니다.
PNG 내보내기는 브라우저 자동화가 필요할 수 있습니다. 저장소는 Playwright와 Chromium 설치를 요구하는 흐름을 안내하며, Playwright 공식 문서도 브라우저 페이지를 PNG로 저장하는 화면 캡처 기능을 제공합니다. diagram-design의 내보내기 안내와 Playwright 화면 캡처 문서를 함께 확인해야 합니다.
자동화 전에 확인할 제한
실시간 협업 보드
여러 사람이 동시에 자유롭게 선을 그리고 메모를 붙이는 회의라면 diagram-design이 맞지 않습니다. 이 장면에서는 무한 캔버스와 손그림 스타일, 실시간 편집을 제공하는 Excalidraw가 더 자연스럽습니다. Excalidraw는 PNG, SVG, 자체 JSON 형식으로 내보낼 수 있습니다. Excalidraw의 공식 저장소 기능 안내를 기준으로 선택하면 됩니다.
코드 중심의 지속적인 문서 관리
도표의 원본을 텍스트로 관리하고, 코드 변경 때마다 문서에서 자동으로 다시 그리려면 Mermaid가 더 단순할 수 있습니다. Mermaid는 텍스트 문법으로 흐름도와 순서도 등을 정의하고, 문서 저장소에 원본을 함께 보관하기 쉽습니다. Mermaid 문법과 지원 유형에서는 흐름도, 순서도, 개체 관계도, 상태도 같은 문법 구조를 확인할 수 있습니다.
전용 편집 파일이 필요한 조직
디자인 팀이 특정 편집 프로그램의 원본 형식, 레이어, 코멘트, 승인 기록을 요구한다면 HTML과 SVG만으로는 부족할 수 있습니다. 이 경우 diagram-design은 최종 시안이나 문서용 결과물을 만드는 보조 도구로 두고, 원본 편집은 기존 디자인 시스템에서 진행하는 편이 좋습니다.
선택 기준 비교
| 선택지 | 가장 잘 맞는 장면 | 원본 관리 방식 | 출력 방식 | 주의할 점 |
|---|---|---|---|---|
| diagram-design | 반복 제작하는 기술 블로그와 제품 문서 | 스킬, HTML, 스타일 파일 | HTML, SVG, PNG | 복잡한 구조는 사람 검토가 필요합니다 |
| Mermaid | 코드 저장소와 함께 관리하는 문서 | 텍스트 문법 | 렌더링된 SVG와 PNG 등 | 시각 스타일을 세밀하게 맞추는 작업은 별도 조정이 필요합니다 |
| Excalidraw | 회의, 자유 배치, 실시간 화이트보드 | 자체 JSON 파일 | PNG, SVG, JSON | 브랜드형 반복 제작보다는 협업 캔버스에 가깝습니다 |
결정 규칙은 간단합니다. 웹 문서에 바로 넣고 같은 스타일로 반복 생성해야 한다면 diagram-design을 선택합니다. 변경 이력을 코드처럼 관리해야 한다면 Mermaid를 우선 검토합니다. 사람 손으로 빠르게 그리고 함께 수정해야 한다면 Excalidraw가 낫습니다.
기술 콘텐츠를 여러 편 만들면서 브라우저 렌더링과 파일 내보내기를 반복한다면 로컬 환경의 폰트, 브라우저 권한, 파일 경로가 병목이 됩니다. 이때는 Claude Code용 원격 맥 환경과 맥 미니 렌탈 구성을 함께 검토할 수 있습니다.
diagram-design은 모든 도표 도구를 대체하는 만능 해법이 아닙니다. 이미지 생성 AI는 결과를 다시 만들 때마다 편집 비용이 생기고, Mermaid는 시각 스타일의 자유도가 제한될 수 있으며, Excalidraw는 기업 문서용 반복 디자인에 맞지 않을 수 있습니다. 반대로 Kvmzen의 클라우드 맥 환경을 사용하면 Claude Code와 브라우저 자동화 도구를 같은 작업 공간에 두고, 설치 상태가 다른 여러 로컬 컴퓨터를 번갈아 관리하는 부담을 줄일 수 있습니다. 단발성 도표 하나라면 로컬 환경이 충분하지만, 지속적인 문서 생산과 HTML·SVG·PNG 내보내기를 운영하려면 원격 맥 환경이 더 현실적인 선택이 될 수 있습니다.