청사진 아키텍처 다이어그램
엔지니어링 도면처럼 그린 시스템: 격자 무늬 청사진(또는 밝은 "백청사진"), 모든 구성 요소는 종류별로 레이블이 있는 도형, 요청은 실선 화살표, 이벤트는 점선 화살표, 그룹은 점선 영역, 범례와 타이틀 블록이 있습니다. 사용자(또는 사람)가 diagram.json으로 시스템을 설명하면, 스크립트가 dagre를 사용하여 (번들로 제공되며 설치 불필요) 레이아웃을 계산하고 다음을 그립니다:
out/index.html: 모든 연결선을 따라 점이 이동하고 이벤트 흐름선이 흐르는 다이어그램. 디스크에서 열리며 창 크기에 맞게 조정됩니다.out/diagram.svg: 움직임이 없는 동일한 그림으로, 문서, 위키 및 슬라이드에 적합합니다.out/diagram.png: 두 배 크기의 정지 이미지로, headless Chrome을 사용하며 이미지가 필요한 모든 곳에 사용할 수 있습니다.
필요 사항
- Node.js 18 이상. 빌드에 다른 것은 필요하지 않습니다.
- PNG 출력을 위한 Chrome, Chromium 또는 Edge. 스크립트가 일반적인 위치에서 찾습니다. 찾지 못하면
CHROME_PATH를 설정하세요. - 다이어그램을 열거나 내보낼 때 Google Fonts의 JetBrains Mono 폰트를 위한 인터넷 접속 (없으면 시스템 monospace 폰트로 대체).
이 스킬의 폴더는 <skill> 아래에 있습니다. 즉, 이 SKILL.md가 있는 폴더입니다.
단계
1. 시스템 파악
사용자가 시스템을 설명하면 그들의 말을 사용합니다. 리포지토리를 읽으라는 요청을 받으면 그림을 그리기 전에 증거를 수집하고, 찾은 내용만 그립니다:
- 배포 가능 항목:
docker-compose*.yml서비스, KubernetesDeployment, Helm 차트,Procfile, 서버리스 설정 (serverless.yml,vercel.json,wrangler.toml), Terraform 리소스, 모노레포의 앱 (apps/,services/,packages/*중 시작 스크립트가 있는 것). - 데이터 저장소 및 브로커: 이미지 및 관리 리소스 (postgres, mysql, mongo, redis, kafka, rabbitmq, sqs, s3)와
DATABASE_URL,REDIS_URL,KAFKA_BROKERS, 버킷 이름 같은 연결 설정. - 연결: 다른 서비스를 가리키는 HTTP 클라이언트와 기본 URL, gRPC 스텁, 큐 생산자와 소비자 (토픽 및 큐 이름),
depends_on, 타사로의 아웃바운드 호출 (Stripe, LLM API, 이메일 제공업체). - 호출자: 웹 및 모바일 앱, CLI, cron 작업, 웹훅.
5~20개 노드로 유지하세요. 복제본과 작은 도우미는 속한 서비스로 병합하고, 한 장에 너무 많으면 여러 시트("sheet": "02 / 03")로 나누세요. 찾은 것이 아니라 추론한 내용이 있으면 반드시 알리고 사용자에게 알리세요.
2. diagram.json 작성
{
"title": "주문 서비스 · v2",
"subtitle": "시스템 아키텍처 · /services 및 docker-compose.yml에서 · 2026년 10월 21일",
"sheet": "01 / 01",
"direction": "LR",
"theme": "blueprint",
"groups": [{ "id": "core", "label": "주문 플랫폼" }],
"nodes": [
{
"id": "gateway",
"label": "API 게이트웨이",
"sub": "인증 · 속도 제한",
"kind": "service"
},
{
"id": "orders",
"label": "주문 서비스",
"sub": "v2 · Go · 6개 파드",
"kind": "service",
"group": "core",
"focus": true
},
{
"id": "db",
"label": "Postgres",
"sub": "주문 · 재고",
"kind": "database"
},
{
"id": "bus",
"label": "이벤트 버스",
"sub": "Kafka · 3개 토픽",
"kind": "queue"
}
],
"edges": [
{ "from": "gateway", "to": "orders", "label": "POST /orders" },
{ "from": "orders", "to": "db", "label": "SQL" },
{ "from": "orders", "to": "bus", "label": "order.created", "async": true }
]
}
| 필드 | 설명 | 제한 |
|---|---|---|
title | 시스템 또는 뷰의 이름 (필수); 타이틀 블록에도 들어감 | 60 |
subtitle | 그림이 보여주는 내용과 출처: 소스와 날짜 | 100 |
sheet | 타이틀 블록의 시트 번호, 예: "02 / 03" (기본값 01 / 01) | – |
direction | LR 왼쪽에서 오른쪽 (기본값, 요청 흐름에 적합) 또는 TB 위에서 아래 (파이프라인) | – |
theme | blueprint (진한 파랑, 기본값), whiteprint (밝음), 또는 색상: { "paper", "line", "accent", "dim" }을 16진수로 | – |
groups | 해당 노드 주위에 그려지는 영역: { "id", "label" } | – |
nodes[].id | 문자, 숫자, - 또는 _; 엣지가 참조 (필수) | – |
nodes[].label | 노드에 표시될 이름 (필수) | 28 |
nodes[].sub | 두 번째 줄: 언어, 런타임, 규모, 포함 내용 | 36 |
nodes[].kind | 도형: service (기본값), client, database, queue, cache, storage, function, external (타사, 점선) | – |
nodes[].group | 그룹 ID | – |
nodes[].focus | true로 설정하면 강조 색상으로 그림: 다이어그램의 주요 대상 | – |
edges[] | { "from", "to" } 노드 ID, 데이터 또는 제어 흐름 방향 | – |
edges[].label | 프로토콜, 엔드포인트, 토픽 또는 동사: HTTPS, POST /orders, order.created | 24 |
edges[].async | true이면 이벤트, 큐 및 fire-and-forget (점선, 흐름) | – |
팁:
- 엣지에는 실제로 전달되는 내용(엔드포인트, 토픽, 테이블, 동사)을 레이블로 붙이세요. 레이블이 아무것도 추가하지 않을 때만 생략하세요.
- 엣지는 요청 방향(호출자에서 호출 수신자)과 이벤트 방향(생산자에서 큐, 소비자)을 가리키게 하세요.
- 하나의 노드만
focus로 표시하세요. - 최대 40개 노드까지 허용되지만, 약 20개가 넘으면 그림이 읽기 어려워집니다.
3. 빌드 및 확인
node <skill>/scripts/build.mjs diagram.json out
파일을 검사하고 모든 문제를 한 번에 나열한 다음 (존재하지 않는 노드로 가는 엣지, 제한을 초과한 레이블 등) out/index.html과 out/diagram.svg를 작성합니다. out/index.html을 열고 확인하세요:
- 1단계의 모든 노드가 있고, 찾지 못한 것은 없으며,
- 엣지 방향이 올바르고 레이블을 읽을 수 있고,
- 그룹에 올바른 노드가 포함되어 있습니다.
레이아웃이 엉키면 다른 direction을 시도하거나 nodes와 edges의 순서를 변경하세요: 레이아웃은 순서에서 시작합니다.
4. PNG 내보내기
node <skill>/scripts/export-png.mjs out/index.html
그림 크기의 두 배로 out/diagram.png를 작성합니다. 실제 크기로 하려면 --scale=1을 추가하세요.
5. 결과물 전달
사용자에게 out/index.html (애니메이션), out/diagram.svg, out/diagram.png와 함께 diagram.json을 제공하여 시스템이 변경될 때 그림을 업데이트할 수 있도록 하세요: JSON을 편집하고 3단계와 4단계를 다시 실행합니다. 다이어그램이 리포지토리에 속한다면 docs/architecture/ 폴더에 JSON과 SVG를 두는 것이 좋습니다. SVG는 GitHub와 대부분의 위키에서 렌더링됩니다.
문제 해결
build: fix diagram.json first: 각 줄이 노드 또는 엣지와 변경해야 할 사항을 알려줍니다.- PNG 단계에서 Chrome을 찾을 수 없다고 표시됨:
CHROME_PATH를 설정하거나out/index.html을 열고 스크린샷을 찍으세요. - 텍스트가 다른 monospace 폰트로 표시됨: 페이지가 Google Fonts에 도달할 수 없었습니다. JetBrains Mono (무료)를 설치하여 오프라인에서 일치시키세요.
- 엣지가 많이 교차함:
direction을 전환하고, 엉킨 노드를nodes에서 더 앞이나 뒤로 이동시키거나, 시스템을 두 시트로 나누세요.
파일
scripts/build.mjs:diagram.json을 검사하고, 레이아웃을 계산하며 HTML과 SVG를 그립니다. 설치할 종속성이 없습니다.scripts/export-png.mjs: headless Chrome으로 PNG를 저장합니다.vendor/dagre.esm.js: dagre 그래프 레이아웃 라이브러리 (MIT), 번들로 제공되어 설치가 필요 없습니다. 라이센스는vendor/LICENSE-dagre.txt에 있습니다.examples/order-service/(청사진, 왼쪽에서 오른쪽) 및examples/rag-pipeline/(백청사진, 위에서 아래): 완성된diagram.json파일. Lookbk의 미리보기는 이 파일들로부터 그려집니다.NOTICE.md: 이 스킬이 사용하는 타사 소프트웨어 및 폰트.