Diagram Design 사용법: Claude Code·Codex로 다이어그램 만드는 순서
Diagram Design은 Claude Code나 Codex 같은 코딩 에이전트에 다이어그램 제작 규칙을 더하는 외부 스킬·플러그인입니다. 별도의 웹 편집기에서 도형을 끌어다 놓는 방식이 아니라, 설명할 구조와 목적을 전달하면 에이전트가 HTML·SVG 기반 결과물을 만들도록 돕습니다.
자동화 흐름을 문서에 넣고 싶은데 상자 배치와 색상 정리에 시간을 쓰고 있다면 살펴볼 만합니다. 다만 보기 좋은 그림과 정확한 설계는 다릅니다. 여기서는 설치부터 첫 요청, 결과 검토와 내보내기까지 구분해 정리합니다.
자료 확인: 2026년 9월 16일 · 공식 README·사용 가이드 기반 안내입니다.
- Diagram Design 자체가 AI 모델은 아닙니다. 사용할 코딩 에이전트가 먼저 준비돼 있어야 합니다.
- 처음에는 작은 흐름 하나를 정적 HTML로 만든 뒤 검토하는 편이 좋습니다.
- 공개 저장소라는 사실과 모델 사용료가 무료라는 말은 다릅니다.
1. 어떤 작업에 쓰면 좋을까?
공식 문서는 아키텍처, 흐름도, 시퀀스, 데이터 모델 등 여러 유형을 제공합니다. 기본 결과는 정적 HTML이며, Mermaid·draw.io·Excalidraw 자료를 선택한 크기와 상세도에 맞춰 다시 그리는 기능도 안내합니다. 모든 요소를 그대로 옮기는 단순 변환과는 다릅니다.
| 설명할 내용 | 선택 기준 |
|---|---|
| 문의 처리나 업무 자동화 순서 | 처리 단계와 분기가 보이는 흐름도 |
| 앱·서버·데이터베이스의 관계 | 구성 요소와 연결을 보여주는 아키텍처 |
| 시간 순서에 따른 요청과 응답 | 메시지 순서를 구분하는 시퀀스 |
| 옵션 두 개의 장단점 | 그림보다 비교표가 명확할 수 있음 |
이 예제는 단순한 상자 나열이 아닙니다. Reader에서 들어온 요청, Astro Origin이 읽는 MDX 문서와 CMS, 다시 돌아가는 응답을 선 종류와 라벨로 구분합니다. 자신의 결과물에서도 먼저 무엇이 어디로 이동하는지를 읽어 보고, 그다음 색과 배치를 검토하세요.
2. 설치는 사용하는 에이전트에 맞춰 진행하기
설치 전에 준비할 네 가지
이 플러그인은 Claude Code나 Codex 자체를 설치해 주지는 않습니다. 먼저 사용할 도구에서 평소처럼 대화를 시작하고 프로젝트를 열 수 있는 상태인지 확인하세요. 호스트의 설치·로그인·구독 문제와 Diagram Design 설치 문제를 나누면 어디서 막혔는지 찾기 쉽습니다.
- 사용할 호스트: Claude Code와 Codex 중 실제로 쓰는 도구 하나를 고릅니다. 두 도구의 명령을 섞어 입력하지 않습니다.
- 작업 폴더: 결과 HTML을 보관할 프로젝트를 엽니다. 플러그인 내부 예제 폴더가 아니라 내 문서나 프로젝트에 결과를 저장하는 편이 관리하기 좋습니다.
- 작은 입력 자료: 단계 이름, 연결 방향, 독자, 반드시 남겨야 할 조건을 짧게 정리합니다. 첫 시도에는 실제 개인정보 대신 가상의 업무 흐름을 사용하세요.
- 첫 결과 형식: 우선 정적 HTML을 목표로 합니다. 브라우저로 확인하는 단계와 PNG 내보내기용 추가 환경 준비는 별개입니다.
아래는 마켓플레이스를 사용하는 설치 경로입니다. 처음부터 저장소를 복제하거나 스킬 폴더를 연결할 필요는 없습니다. 직접 플러그인 파일을 수정하는 개발용 설치는 별도 경로이므로 기본 설치와 섞지 마세요.
먼저 공식 저장소에서 구성 파일과 실행 스크립트를 확인하세요. 아래는 확인일 기준 개발자가 README에 안내한 명령입니다. 사용하는 클라이언트의 버전이나 조직 정책에 따라 설치 가능 여부는 달라질 수 있습니다.
Claude Code
일반 터미널이 아니라 Claude Code의 대화 화면 안에서 다음 슬래시 명령을 차례로 입력합니다.
/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-designCodex
Codex CLI를 사용하는 경우에는 터미널에서 다음 명령을 실행하도록 안내돼 있습니다.
codex plugin marketplace add cathrynlavery/diagram-design
codex plugin add diagram-design@diagram-design설치 후에는 현재 세션에서 스킬을 인식하는지 확인합니다. 명령을 찾을 수 없다면 이름을 바꿔 추측하기보다 클라이언트 버전과 최신 설치 문서부터 확인하세요.
설치가 끝났는지 확인하는 순서
- 명령 실행 위치부터 확인합니다. Claude Code의 슬래시 명령은 대화 화면에,
codex plugin명령은 터미널에 입력했는지 점검합니다. 설치 과정에서 안내가 나오면 해당 호스트의 안내를 따르세요. - 진단을 요청합니다. 호스트의 대화에서
run diagram-design doctor라고 요청할 수 있습니다. 공식 Cookbook이 안내하는 진단 방식이며, 진단 자체가 필요한 패키지를 자동 설치하는 절차는 아닙니다. - 작은 요청으로 인식을 확인합니다. 아래 예시를 전달한 뒤, 에이전트가 그리기 전에 유형·크기·생략할 내용을 확인하는지 살펴봅니다. 명령이 끝났다는 사실만으로 원하는 결과까지 검증됐다고 보지는 마세요.
첫 실행에서 브랜드나 스타일을 묻는 것은 정상적인 준비 과정일 수 있습니다. 별도 디자인이 필요하지 않다면 기본 스타일을 사용하겠다고 명확히 답하면 됩니다. 이 단계에서 설치를 반복하기보다 어떤 선택을 기다리는지 먼저 확인하세요.
3. 첫 요청은 작은 흐름 하나로 시작하기
처음부터 서비스 전체를 한 장에 담으면 누락과 복잡한 연결을 놓치기 쉽습니다. 예를 들어 고객 문의 자동화 중에서도 답변을 보내기 전 담당자가 검토하는 구간만 분리해 봅니다. 아래는 이 글을 위해 구성한 요청 예시이며, 실행 결과를 보장하는 문구는 아닙니다.
diagram-design 스킬로 고객 문의 처리 흐름도를 만들어 줘.
단계: 문의 접수 → 유형 분류 → 승인된 FAQ 조회 → 답변 초안 → 담당자 검토.
자동 발송 단계는 추가하지 마.
용도는 내부 문서, 크기는 doc-inline, 결과는 정적 HTML로 해 줘.
기본 스타일로 진행하고, 그리기 전에 노드와 생략할 내용을 확인해 줘.
파일은 docs/diagrams/support-review.html에 저장해 줘.첫 사용 때는 기본 스타일을 그대로 쓸지, 사이트 색상과 글꼴에 맞출지 확인하는 절차가 있습니다. 처음에는 기본 스타일로 구조부터 점검하고, 이후 브랜드를 맞추는 방식도 가능합니다. 관리형 설치 폴더의 스타일 파일을 직접 고치면 업데이트 때 덮어써질 수 있으므로 반복 작업에는 공식 문서의 이름 있는 프로필 방식을 확인하세요.
같은 방식으로 바꿔 볼 활용 예시 두 가지
다음은 요청을 구체화하는 방법을 보여 주는 예시입니다. 실제 업무 구조에 맞춰 단계와 조건을 수정한 뒤 사용하세요.
예시 2. 서비스 구성 설명: 웹 화면, API 서버, 데이터베이스처럼 구성 요소 간 관계를 설명할 때는 처리 순서보다 연결 구조에 집중합니다. 요청에 없는 인프라를 임의로 추가하지 못하도록 범위를 정해 두는 것이 핵심입니다.
웹 앱 → API 서버 → 데이터베이스의 관계를 아키텍처 개념도로 정리해 줘.
구성 요소는 이 세 개만 사용하고, 요청과 응답 방향을 구분해 줘.
정적 HTML로 만들고 docs/diagrams/service-overview.html에 저장해 줘.
그리기 전에 연결과 생략할 내용을 먼저 확인해 줘.예시 3. 콘텐츠 검수 절차: 기획 → 초안 → 사실 확인 → 담당자 승인 → 게시 흐름에서, 승인되지 않은 초안이 어디로 돌아가는지까지 지정합니다. 분기가 있는 업무는 정상 경로뿐 아니라 수정 경로도 보이는지가 중요합니다.
기획 → 초안 → 사실 확인 → 담당자 승인 → 게시 순서를 흐름도로 정리해 줘.
승인에서 반려되면 초안으로 돌아가는 분기를 표시해 줘.
검토 단계를 생략하거나 자동 게시 기능을 추가하지 마.
문서 삽입용 정적 HTML로 만들고 단계 목록부터 확인해 줘.4. 파일이 만들어졌다면 그림보다 내용을 먼저 확인하기
- HTML 열기: 생성된 파일을 브라우저에서 열어 글자가 잘리거나 도형이 겹치지 않는지 확인합니다.
- 흐름 확인: 화살표 방향과 단계 이름이 요청과 일치하는지, 예시의 담당자 검토가 남아 있는지 봅니다.
- 생략 확인: 기존 자료를 다시 그렸다면 병합·생략 내역을 확인합니다. 단순화된 그림을 원본 전체와 동일하다고 보면 안 됩니다.
- 공유 형식 결정: 구조가 맞을 때 SVG나 PNG 내보내기를 요청합니다.
Claude Code용 내보내기 예시는 다음과 같습니다. PNG 출력에는 Playwright와 Chromium 같은 추가 준비가 필요할 수 있습니다. 공식 내보내기는 다이어그램 부분을 대상으로 하므로 편집형 레이아웃의 제목·설명 카드까지 함께 포함된다고 가정하지 마세요.
/diagram-design:export-diagram docs/diagrams/support-review.htmlHTML은 되는데 PNG만 안 된다면?
먼저 HTML 파일을 브라우저에서 열어 내용과 배치를 확인하세요. HTML이 정상이라면 처음부터 다이어그램을 다시 만들기보다 내보내기 환경을 따로 점검하는 편이 좋습니다. 공식 Cookbook은 PNG용 로컬 준비 예시로 다음 명령을 안내합니다. Python을 사용할 수 있고 패키지 설치가 허용된 환경에서, PNG가 필요할 때만 진행하세요.
python -m pip install playwright
python -m playwright install chromium명령이 실행되지 않으면 임의의 Python 버전이나 설치 경로를 추측하지 말고, 현재 환경에서 사용할 수 있는 인터프리터와 조직 정책부터 확인합니다. Codex 등 다른 호스트에서는 특정 슬래시 명령이 통한다고 가정하기보다, 저장한 HTML을 PNG 또는 SVG로 내보내 달라고 자연어로 요청하는 방법을 사용할 수 있습니다.
완료 확인: HTML 파일이 실제 지정한 경로에 있는지, 브라우저에서 열리는지, 필수 단계와 화살표가 맞는지 확인한 후 이미지 파일을 열어 글자 잘림을 다시 살펴보세요. 설명 카드까지 포함한 전체 페이지가 필요하면 다이어그램 전용 내보내기와 구분해 브라우저의 인쇄·화면 캡처 방식을 검토합니다.
5. 비용·보안·문제 해결 체크리스트
- 비용: 저장소 자료 공개와 Claude Code·Codex의 모델 이용료는 별개입니다. 본인의 구독·API·조직 계약에 적용되는 사용량 조건을 확인하세요.
- 민감정보: 실제 고객명, 문의 원문, API 키 대신 가상의 이름과 구조만 전달하세요. 외부 스킬을 설치하기 전 파일 접근과 스크립트 실행 범위도 검토하는 것이 좋습니다.
- 스킬이 안 보일 때: 설치 대상 에이전트와 설치 완료 여부를 확인한 뒤, 문서에 맞게 새 세션에서 다시 확인합니다.
- 그림이 복잡할 때: 색부터 바꾸지 말고 개요와 상세를 두 장으로 나눠 보세요. 무엇을 생략해도 되는지 함께 지정합니다.
- PNG만 실패할 때: HTML이 열리는지부터 확인한 뒤 공식 doctor·내보내기 안내에서 의존성을 점검합니다.
자주 묻는 질문
디자인 프로그램을 완전히 대체하나요?
구조 설명과 반복되는 문서용 다이어그램에 초점을 맞춘 도구입니다. 자유로운 시각 편집이 중요한 작업까지 모두 대체한다고 보기보다, 초안을 만들고 검토하는 흐름에 맞는지 판단하세요.
결과물은 완전히 오프라인인가요?
HTML 파일을 로컬에서 열 수 있지만, 공식 문서는 Google Fonts 요청 가능성을 언급합니다. 완전한 오프라인 환경이나 보안이 중요한 내부 문서라면 폰트와 외부 자원 요청도 따로 확인해야 합니다.
정리: 첫 시도에서는 작은 흐름 하나를 HTML로 만들고, 방향·누락·검토 단계를 확인한 다음 원하는 형식으로 내보내세요. Diagram Design의 활용 여부는 그림의 장식보다 설명하려는 구조가 더 명확해졌는지로 판단하는 편이 좋습니다.
공식 예제의 저작권·라이선스
MIT License Copyright (c) 2025 Cathryn Lavery Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
공식 참고 자료
영어판으로 읽기: Read this guide in English
댓글
댓글 쓰기