기술 구조도를 고객용으로 다시 그릴 때는 용어를 쉽게 바꾸는 일과 구성 요소를 줄이는 일을 따로 결정하는 편이 좋습니다. AI 에이전트용 스킬인 diagram-design은 기존 Mermaid 그림을 HTML과 SVG 기반의 설명용 그림으로 다시 만드는 선택지입니다. 다만 보기 좋은 결과나 검사 통과만으로 원본의 연결 관계까지 보존됐다고 판단하면 안 됩니다. 원본과 대조할 항목을 먼저 정해 두면 작은 팀의 제안서와 인수인계 자료에 활용할 수 있습니다.
확인: 2026년 10월 15일. 공식 문서와 소스를 검토한 도입 해설입니다. 아래 구조는 설명을 위해 만든 가상 예시이며, 스킬 설치나 AI 그림 생성, 내보내기를 실행한 결과가 아닙니다.
지금 관심을 받는 프로젝트는 무엇인가요?
Cathryn Lavery의 diagram-design은 Claude Code, Codex 등에서 사용하는 다이어그램 제작 스킬입니다. 모델 자체나 Django에 설치하는 라이브러리는 아닙니다. 10월 15일 14:33 UTC에 확인한 GitHub 주간 Trending에는 전체 별 55,723개와 ‘10,706 stars this week’가 표시됐습니다. 이는 해당 화면의 기간별 관심 지표이지, 도입 기업 수나 출력 품질을 뜻하지 않습니다.
10월에 처음 나온 프로젝트는 아닙니다. 초기 공개 코드 기록은 4월 16일이며, 확인한 플러그인 manifest 버전은 10월 14일 갱신된 2.6.99입니다. 이 번호를 별도의 정식 GitHub Release로 해석하지는 않았습니다. 10월의 개발자 커뮤니티 소개와 반응도 있지만, 홍보성 소개와 개인 사용 소감은 독립적인 성능 검증과 구분해야 합니다.
‘쉬운 말’과 ‘간단한 구조’는 다른 요청입니다
출력 사양은 독자에 맞춘 표현인 audience와 구성 요소의 상세 수준인 detail을 별도로 둡니다. 고객에게 보여 준다는 이유만으로 둘 다 단순화할 필요는 없습니다. 가령 ‘Redis’를 ‘처리를 기다리는 작업 큐’로 풀어 쓰면서도 큐 자체와 연결 방향은 남길 수 있습니다.
원본 요소를 보존하면서 표현을 조정하려면 detail은 faithful, audience는 mixed를 출발점으로 삼고 원하는 용어 대응을 덧붙일 수 있습니다. 이 구분은 비동기 작업을 설명할 때 중요합니다. 웹 요청이 곧바로 작업을 끝내는지, 접수 뒤 다른 프로세스가 처리하는지는 고객의 기대와 장애 설명에 영향을 줍니다. 제목과 색상은 바꿔도 이 차이가 사라지면 다른 시스템을 설명하게 됩니다. 원본의 모든 요소가 필요한 경우에는 보존 범위를 명시하고, 숨길 항목이 있다면 이름과 이유를 따로 적도록 요청하세요.
노드 6개와 연결 7개가 같아도 틀릴 수 있습니다
가상 파일 변환 서비스를 생각해 보겠습니다. 구성 요소는 사용자, Django 웹, 작업 큐, 워커, PostgreSQL, 파일 저장소의 여섯 개입니다. 이 예시에서 원본으로 정한 연결은 다음 일곱 개입니다.
- 사용자 → Django 웹: 변환 요청
- Django 웹 → PostgreSQL: 접수 상태 기록
- Django 웹 → 작업 큐: 작업 전달
- 작업 큐 → 워커: 작업 수신
- 워커 → PostgreSQL: 처리 결과 기록
- 워커 → 파일 저장소: 변환 파일 저장
- 워커 → 작업 큐: 재시도 작업 전달
일곱 번째 화살표의 도착점을 ‘Django 웹’으로 잘못 바꿔도 노드 수와 연결 수는 그대로입니다. 따라서 개수 비교 다음에는 각 연결의 출발점, 도착점, 방향, 의미를 대조해야 합니다. 이것은 특정 도구에서 관측한 오류가 아니라, 개수만 세는 검토의 한계를 보여 주는 반례입니다. 위 구조 역시 실제 서비스의 트랜잭션 안전성이나 재시도 구현을 보장하는 설계가 아닙니다.
Mermaid 가져오기 지침은 원본을 그대로 렌더링하는 대신 다시 그리도록 하고, 원본과 결과의 수량 및 병합·생략 내역을 남기게 합니다. 이 기록은 검토의 출발점입니다. 스킬에 적힌 작업 지침이 매번 지켜졌다는 증거는 아니므로, ‘빠진 것이 없다’는 생성 결과의 설명도 원본과 함께 확인해야 합니다.
자동 검사와 사람이 맡을 검토를 나누세요
프로젝트의 HTML 검사는 CSS 참조, SVG 접근성, viewBox, 스크립트와 모션 등 결과 파일의 정적 조건을 살피는 데 도움을 줍니다. 그러나 self_check.py의 입력과 검사 범위를 보면, 원본 Mermaid와 결과 HTML의 업무 관계가 같은지를 입증하는 검사는 아닙니다. 자동 검사 성공과 의미 보존 승인을 별도 항목으로 관리하는 편이 안전합니다.
한국어 자료라면 긴 이름을 한 번 더 보세요. ‘비동기 파일 변환 작업 처리기’처럼 긴 라벨이 상자 밖으로 나가거나 줄바꿈 때문에 화살표를 가리지 않는지, 최종 전달 형식에서 확인합니다. HTML에서 괜찮았다고 PDF나 슬라이드의 글꼴 대체까지 확인된 것은 아닙니다. 검토 기록에는 ‘원본 큐 노드 → 결과의 작업 대기열’처럼 이름 대응도 남기면 다른 사람이 수정할 때 도움이 됩니다.
도입은 원본과 전달본을 함께 보관하는 방식으로
시작할 때는 이미 사용하는 에이전트에 맞는 공식 설치 경로와 지원 조건을 확인하고, 민감한 주소나 고객 정보가 없는 작은 그림부터 선택하세요. HTML 확인과 PNG 내보내기의 준비 조건은 다릅니다. PNG 경로에는 Python Playwright와 Chromium 같은 추가 도구가 필요하므로, 기존 환경에서 HTML 또는 SVG만으로 목적을 충족하는지 먼저 판단할 수 있습니다.
스킬은 MIT 라이선스지만 에이전트의 모델 이용료까지 무료라는 뜻은 아닙니다. 개인정보 안내에 따르면 프롬프트와 파일은 선택한 에이전트 공급자를 통해 처리되고, 기본 글꼴은 Google Fonts 요청을 만들 수 있습니다. 네트워크가 제한된 전달본은 시스템 글꼴 경로를 선택하고 실제 산출물을 확인해야 합니다. ‘HTML 한 파일’과 ‘외부 요청 없음’은 같은 조건이 아닙니다.
권하는 보관 단위는 원본 Mermaid, 생성 HTML, 최종 전달 파일, 이름 대응과 생략 기록입니다. 매번 코드와 함께 갱신하는 구조도라면 기존 Mermaid를 유지하는 편이 단순할 수 있습니다. 고객 설명용 결과가 필요할 때 diagram-design을 덧붙이되, 연결 관계를 확인할 수 없거나 수정 후 의미가 달라졌다면 원본으로 돌아가세요. 도입 판단의 핵심은 얼마나 멋있어졌는지보다, 쉬워진 설명이 여전히 같은 시스템을 가리키는지입니다.
댓글
댓글 쓰기