bybit-exchange/svg-diagram

svg‑diagram – AI 에이전트가 생성하는 SVG용 하우스 스타일 및 린터

무엇인가요 – 수작업으로 작성한 SVG 다이어그램에 대한 엄격한 시각적 스타일을 정의하고, 완성된 SVG가 그 스타일을 따르는지 검사하는 명령줄 린터(svg‑lint)를 제공하는, 의존성 없이 작동하는 소형 Node 도구입니다. 이 저장소는 Claude, Gemini, Copilot 등 여러 인기 있는 코딩 에이전트에 설치 가능한 스킬(markdown 파일 SKILL.md)을 포함하고 있어, 에이전트가 박스 크기, 텍스트 배치, 연결선 그리기, 색상 선택을 정확히 수행할 수 있도록 합니다.

AI 에이전트에게 왜 중요한가요 – 현대의 코드 생성 에이전트는 아키텍처 스케치, 플로우차트, 벤치마크 등 다이어그램을 출력해야 하는 경우가 많습니다. 모호한 "예쁘게 만들어"가 아니라 명확한 산술적 레시피를 제공함으로써, 출력 결과는 결정론적이며, 텍스트로만 검토 가능하고, 린터로 자동 검증이 가능해집니다. 이는 생성 후 수동 편집을 줄이고, 에이전트 간 일관성을 보장합니다.

주요 기능

• 하우스 스타일 – 고정된 viewBox 마진, 폰트 크기, 색상 트리플, 화살표 머리 기하학, CJK 호환 폰트 스택, 명시적 이스케이프 규칙. 모든 규칙은 SKILL.md에 문서화되어 있습니다.
• 의존성 없는 린터 – tools/svg‑lint/bin/svg‑lint.mjs라는 단일 Node 스크립트로, npm install 없이도 어떤 기계에서도 실행 가능합니다. 12가지 검사(이스케이프, viewBox, 폰트 스택, 박스 치수, 베이스라인, 간격, 화살표 마커, 오버플로우, 겹침, 팔레트, 연결선 기하학, 문서 모델의 타당성 검사)를 수행합니다.
• 에이전트 독립적 설치 – npx skills add bybit-exchange/svg-diagram -g 명령어로 스킬과 린터가 수십 개의 에이전트에 적절한 디렉터리에 복사됩니다. 스킬의 프론트마터 name이 설치 경로를 결정하므로, 저장소를 이동해도 설치가 깨지지 않습니다.
• 인간이 읽기 쉬운 수정 제안 – 각 린터 실패는 현재 값, 허용 범위/값, 그리고 1줄짜리 "수정" 제안을 보고합니다. 예: font-family: absent → 'PingFang SC', ….
• 준수 다이어그램 갤러리 – 10개의 예제 SVG가 모든 규칙(레이아웃, 작성 루프, 린터 게이트, 데이터 흐름, 스킬 라이프사이클, 리포지토리 아키텍처, 다중 에이전트 설치, CJK 폰트 처리, 계층적 라우팅, A/B 벤치마크)을 시각적으로 보여줍니다.
• 테스트 스위트 – npm run lint:svg:all은 동봉된 SVG를 검증하고, npm test는 984개의 유닛 테스트를 실행하여 린터와 스킬의 신뢰성을 보장합니다.

사용 방법

1. 에이전트용 스킬 설치:

   npx skills add bybit-exchange/svg-diagram -g   # 모든 에이전트용 글로벌 설치
   

2. 새 에이전트 세션에서 다이어그램을 요청하세요. 에이전트는 svg‑diagram 스킬을 사용 중임을 알리며, 해당 스킬에 정의된 산술 규칙을 따릅니다.
3. 에이전트가 diagram.svg를 출력한 후, 린터로 준수 여부를 검증합니다:

   node ~/.claude/skills/svg-diagram/tools/svg-lint/bin/svg-lint.mjs diagram.svg
   

   머신 리드블 출력을 원하면 --json을 추가하세요.
4. 검사가 실패하면, 수정 힌트에 따라 SVG를 편집하거나, 스킬 설명을 조정한 후 다시 실행하세요.

이 프로젝트가 존재하는 이유 – AI 생성 다이어그램을 코드처럼 검토 가능하게 만들기 위함입니다: 모든 좌표가 명시적이고, 모든 스타일이 프레젠테이션 속성이며, 린터가 레이아웃 엔진이나 외부 CSS에 의존하지 않고 공유된 시각 언어에 부합하는지 보장합니다. 이는 재현성 향상, diff 기반 리뷰 간소화, 그리고 플랫폼 간 CJK 문자 정확한 렌더링을 보장합니다.

라이선스 – MIT.