hersaintel/stack-diagram

stack-diagram은(는) 무엇을 하나요?

Hermes 통합

<skill>을 이 SKILL.md가 포함된 디렉토리로 해석하고, 프로젝트 작업 디렉토리로 해석하지 마십시오. 번들 스크립트는 terminal을 통해 Python으로 실행하며, 절대 경로를 따옴표로 묶어 사용하십시오. 템플릿/참조 파일은 read_file을 사용하고, 아티팩트는 write_file/patch를 사용하십시오. Playwright를 위해 격리된 Python 환경을 선호하십시오. import만으로 브라우저 드라이버가 작동한다고 증명할 수 없습니다.

리포지토리 기반 요청의 경우, 먼저 노드와 엣지에 대한 증거를 기록하십시오. 종속성은 런타임 토폴로지를 확립하지 않습니다. 추론된 관계는 가정으로 레이블을 지정하고, 모호성이 아키텍처를 변경할 경우 질문하십시오. 명시적으로 사용자가 제공한 토폴로지는 증거입니다. 스택을 발견하기 위해 비밀 또는 관련 없는 파일을 절대 읽지 마십시오.

로컬 파일을 MEDIA:/absolute/path/to/out.html 및 MEDIA:/absolute/path/to/out.png(어두운 PNG 포함)로 전달하고, vision_analyze를 사용하여 두 테마를 모두 검사하십시오. HTML이 유일한 시각적 소스입니다. PNG는 Chromium에서 생성되며, 독립적인 SVG/PIL 렌더러가 아닙니다. 파일이 존재하기 전에 전달되었다고 표시하지 마십시오. 이 스킬은 brag을 호출하거나 수정하지 않습니다. 비디오가 요청된 경우에만 stack-video를 사용하십시오. 이는 독립적인 형제 스킬이며 필수 단계가 아닙니다.

업스트림 스크립트/리소스는 caru-ini/stack-diagram에서 보존됩니다. 이 팩의 UPSTREAM.md를 참조하십시오. 선택적 갤러리 지침은 여전히 명시적인 동의가 필요합니다. 이 팩을 설치하거나 게시하는 것은 갤러리 동의가 아닙니다.

엔지니어링 도면 스타일의 아키텍처 다이어그램을 생성합니다: 흰색 타일 위의 실제 로고, 레이블이 있는 그룹 상자(클라우드 제공업체 VPC 다이어그램과 유사), 고정폭 레이블이 있는 직교 화살표, 시원한 그래프 페이퍼 배경. 하나의 자체 포함된 HTML 파일이 소스이며, PNG / TSX / 아티팩트는 여기에서 파생됩니다.

요구 사항

• Python 3.9+ (fetch_icons.py, build.py 및 share.py에는 표준 라이브러리만 필요)
• 아이콘 소스(svgl.app, raw.githubusercontent.com, cdn.jsdelivr.net, aws.amazon.com 및 d1.awsstatic.com(AWS 아이콘용), services.google.com(Google Cloud 아이콘용), learn.microsoft.com 및 arch-center.azureedge.net(Azure 아이콘용), 그리고 name=URL의 경우 브랜드 자체 사이트 또는 리포지토리)에 대한 네트워크 액세스
• render_png.py용 Playwright + Chromium: pip install playwright && python3 -m playwright install --with-deps chromium

워크플로우

1. 콘텐츠(노드, 그룹, 엣지) 결정
2. 아이콘 가져오기 — scripts/fetch_icons.py
3. 좌표 계획 — references/geometry.md 읽기
4. assets/template.html에서 HTML 빌드 — scripts/build.py
5. PNG를 렌더링하고 살펴보기 전달하기 전에
6. 요청된 형식으로 전달
7. 선택적으로 공개 갤러리에 공유

1단계 — 콘텐츠

사용자의 기술/서비스 목록에서 다음을 결정합니다:

• 노드: 각 기술 = 하나의 노드(이름 + http server, sqlite db와 같은 짧은 소문자 역할)
• 그룹: 런타임, 제공업체 또는 리포지토리를 공유하는 것들 주위에 상자를 그립니다(예: 런타임 상자를 포함하는 클라우드 제공업체 상자, 도구용 모노리포 상자). 한 단계 중첩은 괜찮습니다. 더 깊으면 복잡해집니다. 그룹 레이블은 브랜드 고유의 대소문자로 작성하십시오(GitHub, npm). 템플릿은 작성된 대로 표시합니다.
• 엣지, 세 가지 종류:
  • 강조 색상 실선 = 기본 요청/데이터 흐름(하나의 연속적인 경로가 가장 잘 읽힙니다)
  • 중립 실선 = 보조 내부 연결
  • 중립 점선 = 개발/배포 시간 관계(CI, git hook, IaC 배포)

사용자가 도구의 평평한 목록만 제공한 경우, 도구가 무엇인지로부터 합리적인 그룹과 흐름을 추론하십시오. 도구가 모호하여 다이어그램이 어느 쪽이든 틀릴 경우에만 질문하십시오.

2단계 — 아이콘

python3 scripts/fetch_icons.py <icons-dir> tanstack hono drizzle "betterauth:better-auth" "orpc=https://orpc.unnoq.com/logo.webp"
python3 scripts/fetch_icons.py <icons-dir> "aws:aws/AWS-Cloud-logo" "vpc:aws/vpc" "fargate:aws/fargate" "s3:aws/s3"
python3 scripts/fetch_icons.py <icons-dir> "gcp:google-cloud" "run:gcp/cloud-run" "lb:gcp/load-balancing" "sql:gcp/cloud-sql"
python3 scripts/fetch_icons.py <icons-dir> "azure:azure/Azure-A" "app:azure/app-service" "vnet:azure/vnet" "sql:azure/sql-database"

사양 형식: name(슬러그로 사용되는 이름), name:slug(다른 슬러그), name=URL(명시적 URL), name:aws/<Name>(공식 AWS 아이콘), name:gcp/<Product>(공식 Google Cloud 아이콘), name:azure/<Name>(공식 Azure 아이콘). 스크립트는 다음 순서로 시도합니다: svgl → devicon → gilbarbara/logos, 파일과 manifest.json을 작성하고, 채우기가 흰색인 아이콘에 플래그를 지정합니다. svgl(svgl.app)이 첫 번째인 이유는 최신 개발 브랜드(TanStack, Better Auth, Hono...)의 공식 마크를 제공하기 때문입니다. 로고에 라이트/다크 버전이 있는 경우, 라이트 버전은 <name>이 되고(두 테마에서 타일은 흰색), 다크 버전은 그룹 레이블용으로 <name>_dark로 저장됩니다. svgl은 정확한 제목만 일치시키므로, 놓치면 다음 소스로 넘어갑니다. svgl의 API는 wordmark 변형도 제공합니다. 넓은 그룹 레이블에 가끔 유용하지만, 타일에는 사용하지 마십시오.

메커니즘보다 더 중요한 규칙:

• 로고를 다시 색칠하지 마십시오. 사용자가 알아차립니다. 로고가 흰색이거나 흰색 타일에 비해 너무 밝으면 채우기를 건드리지 말고 대신 어두운 타일(tile dark 클래스)에 배치하십시오. manifest의 white_fill 플래그는 휴리스틱입니다. 흰색 채우기는 색상이 있는 마크(tRPC, Ubuntu)의 내부 세부 사항일 수 있으므로, 어두운 타일을 사용하기 전에 SVG를 살펴보십시오.
• 공식 마크만 사용하십시오. simple-icons는 의도적으로 소스가 아닙니다. 해당 글리프는 단색으로 다시 그려진 것이며, 사용자들이 보자마자 잘못되었다고 말합니다. 모든 소스가 실패(FAIL)하면, 공식 파일을 찾아 name=URL로 전달하십시오. 프로젝트의 리포지토리(루트 logo*.svg, docs/, assets/, public/)와 사이트(/logo.svg, /favicon.svg, /images/logo.svg)에서 찾아보십시오. 일부 마크는 리포지토리(예: Lefthook의 마크는 evilmartians/lefthook의 루트에 있는 logo_sign.svg)에만 있습니다.
• 추상적인 개념은 그림 문자를 사용하고 텍스트는 사용하지 마십시오. "dev environment", "cron", "queue", "cache" 또는 "webhook receiver"와 같은 노드는 브랜드가 없습니다. name:lucide/<icon>(예: devenv:lucide/terminal, cron:lucide/clock; lucide.dev/icons에서 검색)을 통해 Lucide 아이콘을 사용하십시오. 타일 안에 텍스트를 넣거나 이모지를 사용하지 마십시오.
• 벤더 하위 제품(Cloudflare D1/R2/KV...)은 일반적으로 별도의 로고가 없습니다. 타일에 벤더 로고를 재사용하고 노드 이름이 차이점을 전달하게 하십시오("Cloudflare D1" / "sqlite db").
• AWS는 AWS 자체 아이콘을 사용합니다. 각 서비스에는 하나가 있습니다. name:aws/<Name>으로 가져오고, 런타임에 AWS의 공식 아이콘 패키지에서 읽습니다(예: lambda:aws/lambda, aws:aws/AWS-Cloud-logo, s3:aws/s3). AWS- / Amazon- 접두사는 선택 사항이며, 일반적인 약어(s3, sqs, sns, ses, ecs, eks, ecr, elb, alb, nlb, iam, kms, msk, vpc)가 작동하며, 실패하면 모든 이름을 출력합니다. 슬러그 aws, amazonwebservices 및 aws-*는 동일한 패키지로 이동하며, 패키지에 없는 것은 타사 복사본으로 대체되지 않고 FAIL됩니다. 서비스에는 항상 aws/ 접두사를 작성하십시오. dynamodb와 같은 단독 이름은 여전히 타사 체인을 거칩니다. 패키지와 느슨한 아이콘 파일을 리포지토리 밖에 보관하십시오. AWS는 다이어그램에서 아이콘을 허용하며, 재배포는 확인되지 않았습니다.
• AWS 영역은 AWS 자체 그리기 규칙을 따릅니다. 서비스 아이콘은 자체 사각형을 가지며 밝은 배경과 어두운 배경에서 모두 작동하므로, tile bare를 사용하십시오. 흰색 타일은 프레임만 두 배로 만듭니다. 그 안에 있는 사람 및 일반 노드는 템플릿의 lt/dk 쌍과 함께 AWS의 일반 아이콘(user:aws/General-User, General-Users, General-Client, General-Internet, General-Server)을 tile bare res로 사용합니다. 그룹은 AWS Cloud의 경우 템플릿의 group aws(레이블에 aws:aws/AWS-Cloud-logo 포함)를 사용하고, 나머지에는 region, az, vpc, private 또는 public을 사용합니다. 사각형 모서리, 외곽선만, 레이블은 잉크색, 벤더 색조 없음, 14px 대신 모서리에 30px 아이콘을 사용합니다. VPC 내부에서는 분할을 알거나 안전하게 추론할 수 있는 경우(공용의 인터넷 직면 로드 밸런서, 개인용 앱 서버 및 데이터베이스) 공용 및 개인 서브넷을 표시하십시오. 평평한 VPC는 AWS 사람들이 가장 먼저 알아차리는 것입니다. 내부 엣지는 하나의 색상과 열린 화살촉을 사용합니다: <path class="aws" ... marker-end="url(#open)"/>, 개발/배포에는 aws dash, 일반 .el 레이블, 해당 범례는 없습니다. 노드 이름은 Amazon S3 / AWS Fargate로 지정하고, S3 / Fargate와 같은 단독 이름은 사용하지 마십시오. ALB와 같은 짧은 형식은 전체 이름(Elastic Load Balancing) 아래 역할 줄에 넣습니다. 이름은 두 줄을 차지할 수 있지만, Amazon / AWS는 첫 번째 단어 줄에 유지되어야 합니다. 접두사 바로 뒤에 줄 바꿈이 발생하면 해당 노드의 너비를 넓히십시오(left:<centerX-76>px; width:152px).
• Google Cloud는 Google 자체 아이콘을 사용합니다. name:gcp/<Product>로 가져오고, 런타임에 Google의 공식 패키지에서 읽습니다(예: run:gcp/cloud-run, lb:gcp/load-balancing, memorystore:gcp/memorystore). 핵심 제품(Cloud Run, Cloud SQL, Cloud Storage, BigQuery, GKE, Compute Engine, Vertex AI...)만 자체 아이콘이 있습니다. 다른 모든 제품은 Google 가이드에 따라 카테고리 아이콘을 사용합니다. Cloud Load Balancing 및 Cloud CDN은 모두 Networking을, Memorystore 및 Firestore는 모두 Databases를 사용합니다. 제품 이름을 쓰면 스크립트가 아이콘을 선택합니다. Cloud / Google 접두사는 선택 사항이며, 일부 짧은 형식(vpc, iam, kms, iap, gce, gcs)이 작동하며, 실패하면 모든 이름을 출력합니다. gcp/storage는 Storage 카테고리입니다. Cloud Storage는 gcp/cloud-storage입니다. 슬러그 gcp-* 및 google-cloud-*는 동일한 패키지로 이동하며, 패키지에 없는 것은 타사 복사본으로 대체되지 않고 FAIL됩니다. 해당 복사본은 사용 중지된 육각형 아이콘으로, Google은 사용하지 말라고 말합니다. 제품에는 항상 gcp/ 접두사를 작성하십시오. bigquery와 같은 단독 이름은 여전히 타사 체인을 거칩니다. gcp:google-cloud는 그룹 레이블용 Google Cloud 마크입니다. Gemini 및 Firebase는 패키지에 없습니다. gemini 및 firebase를 사용하십시오. 패키지와 느슨한 아이콘 파일을 리포지토리 밖에 보관하십시오. Google은 다이어그램 및 문서용으로 아이콘을 제공하며, 재배포는 확인되지 않았습니다.
• Google Cloud 다이어그램은 일반 스타일을 유지하며 Google 그룹을 사용합니다. Google 자체 다이어그램(단색 파란색 패널, 가로 카드)은 의도적으로 복사되지 않습니다. 아이콘은 일반 흰색 타일에 배치되고, 엣지와 범례는 평소와 동일하게 유지됩니다. 그룹은 Google Cloud의 경우 템플릿의 group gcp(레이블에 gcp:google-cloud 포함)를 사용하고, vpc, region, subnet 또는 zone을 사용합니다. VPC는 글로벌이고 서브넷은 리전별이므로, 리전을 VPC 내부에 배치하고 VPC를 리전 내부에 배치하지 마십시오. 외부 로드 밸런서, Cloud Storage, Cloud Run과 같은 글로벌 및 서버리스 서비스는 VPC 외부에 유지됩니다. 아이콘이 공유되므로 항상 제품의 전체 이름(Cloud Load Balancing, LB가 아님)을 쓰고, 이름이 줄 바꿈될 노드의 너비를 넓히십시오(left:<centerX-76>px; width:152px).
• Azure는 Microsoft 자체 아이콘을 사용합니다. 각 서비스에는 하나가 있습니다. name:azure/<Name>으로 가져오고, 런타임에 Microsoft의 공식 패키지에서 읽습니다(예: app:azure/app-service, azure:azure/Azure-A, vault:azure/key-vault). Azure- / Microsoft- 접두사 및 복수형 s는 선택 사항이며, 일반적인 짧은 형식(aks, vm, vnet, nsg, waf, blob, cosmos, redis, postgres, functions, front-door, apim, ai-search)이 작동하며, 실패하면 모든 이름을 출력합니다. 슬러그 azure, microsoft-azure 및 azure-*는 동일한 패키지로 이동하며, 패키지에 없는 것은 타사 복사본으로 대체되지 않고 FAIL됩니다. 서비스에는 항상 azure/ 접두사를 작성하십시오. cosmos와 같은 단독 이름은 여전히 타사 체인을 거칩니다. Microsoft Entra ID는 별도의 아이콘 세트를 가지고 있습니다. 공식 파일을 name=URL로 전달하십시오. Microsoft는 아키텍처 다이어그램, 교육 자료 및 문서에서만 이러한 아이콘을 사용할 수 있도록 허용합니다. 아이콘을 자르거나, 뒤집거나, 회전하거나, 모양을 변경하지 말고, 나타내는 Microsoft 서비스에만 사용하고 패키지와 느슨한 아이콘 파일을 리포지토리 밖에 보관하십시오.
• Azure 다이어그램은 일반 스타일을 유지하며 Microsoft 그룹 색상을 사용합니다. Microsoft 자체 다이어그램은 의도적으로 복사되지 않습니다. 아이콘은 일반 흰색 타일에 배치되고, 엣지와 범례는 평소와 동일하게 유지됩니다. 그룹은 Azure의 경우 템플릿의 group azure(레이블에 azure:azure/Azure-A 포함)를 사용하고, rg, region, vnet, subnet 또는 zone을 사용하며, vnet 또는 subnet 레이블은 해당 아이콘(vnet:azure/vnet, subnet:azure/subnet)을 전달합니다. VNet은 하나의 리전에 속하므로 리전 내부에 배치됩니다. Front Door와 같은 글로벌 서비스는 리전 외부에 유지됩니다. App Service는 App Service Environment에서 실행되지 않는 한 VNet 외부에 있으며, 프라이빗 엔드포인트를 통해 연결된 PaaS 서비스는 역할이 private endpoint인 경우 VNet 내부에 배치될 수 있습니다. Microsoft는 각 아이콘 옆에 서비스의 전체 이름(Azure SQL Database, SQL이 아님)을 요구하므로, 이름이 줄 바꿈될 노드의 너비를 넓히십시오(left:<centerX-76>px; width:152px).
• 벤더의 규칙은 해당 벤더의 영역에만 적용됩니다. AWS, Google Cloud 및 Azure 규칙은 다이어그램에 다른 것이 없더라도 해당 벤더의 그룹 내부에만 적용됩니다. 그 외부의 모든 것(예: 옆에 있는 사용자 또는 그룹으로 들어오는 엣지)은 일반 타일, 그룹, 엣지 및 범례를 유지합니다.
• 비브랜드 노드(사용자, 브라우저, 인터넷, 장치, 베어메탈 서버): assets/generic/의 글리프를 노드 이름 아래 아이콘 디렉토리에 복사하거나 name:lucide/<icon>을 사용하십시오. 이모지를 사용하지 마십시오. 이는 브랜드 로고가 아니므로 다이어그램의 잉크 색상으로 색조를 지정하는 것이 괜찮습니다(가져오기 스크립트가 Lucide에 대해 자동으로 수행합니다).
• 그룹 레이블 아이콘은 14px로 렌더링됩니다. 정사각형 글리프 마크가 필요합니다. 워드마크와 넓은 잠금 장치는 해당 크기에서 흐릿해집니다. 기본 아이콘이 워드마크인 경우 레이블용으로 브랜드의 정사각형 아이콘을 별도로 가져오십시오(svgl에 일반적으로 있습니다. 그렇지 않으면 프로젝트 자체 아이콘 또는 파비콘 파일).
• 그룹 레이블은 그룹의 색조 위에 위치하며 흰색 타일 위에 있지 않습니다. 따라서 어두운 테마에서는 검은색 부분이 있는 마크가 사라집니다. fetch_icons.py가 <name>_dark를 저장한 경우 템플릿의 lt/dk 쌍을 레이블에 사용하십시오. 어두운 변형이 없고 마크에 검은색 부분이 있는 경우 레이블의 <img>에 plate 클래스를 추가하십시오(어두운 테마에서만 흰색 배경).
• 래스터 로고(png/webp)는 괜찮습니다. 빌드 스크립트가 복사합니다. .ico는 복사하지만 변환하지 않습니다. 가능하면 SVG를 선호하십시오.
• 가져오기 캐시에 없는 아이콘이 있는 경우(예: 과거 실행에서) --force를 전달하거나 fetch_icons.py를 다시 실행하십시오.

3단계 — 좌표

좌표계와 제약 조건은 references/geometry.md를 참조하십시오. 일반적인 용량의 한 그룹 다이어그램은 1024×768 캔버스를 사용합니다. 한 그룹에 3개 초과의 노드가 있는 경우. 다음 예제를 참조하십시오:

# 노드
- `k6` (load testing)
- `spring` (java http server)
- `hono` (typescript http server)
- `tanstack` (react query / ssr)
- `next` (react framework)
- `shadcn` (component lib)
- `planetscale` (mysql)
- `upstash` (redis)

# 그룹
`turborepo` monorepo:
- `next` (react framework)
- `hono` (typescript http server)
- `shadcn` (component lib)
- 내부 타일이 있는 `turborepo` 상자, 레이블에 turborepo 아이콘

`vps` (vm 브랜드 없음 — lucide server 아이콘):
- `k6` (load testing)
- `spring` (java http server)
- `planetscale` (mysql)
- `upstash` (redis)
- 서버 아이콘이 있는 `vps` 상자

# 엣지 — 기본 흐름
k6 → spring (http)
k6 → hono (http)
spring → planetscale (sql)
hono → upstash (redis)
next → hono (api)
next → planetscale (?)
→ next는 탄스택 쿼리가 mysql을 폴링하므로 planetscale에 연결됨

4단계 — HTML 빌드

python3 scripts/build.py <assets-dir> <out.html>

5단계 — PNG 렌더링

python3 scripts/render_png.py <out.html> <out.png>
python3 scripts/render_png.py <out.html> <out-dark.png> --dark

문제 해결

• Playwright가 설치되지 않음: pip install playwright && python3 -m playwright install --with-deps chromium
• 빈 PNG / 회색 상자: render_png.py는 Mac에서 완전히 렌더링된 1024×768 뷰포트를 가져옵니다. 실패하면 MEDIA:로 PNG를 다운로드하여 검사하고, browser.new_context(viewport=...))를 사용하여 HTML에 필요한 것보다 넉넉한 뷰포트를 전달하십시오.
• 잘린 아이콘 또는 레이블: 뷰포트를 늘리거나 템플릿의 overflow: visible을 확인하거나 캔버스 치수를 늘리십시오.

전달

1. 시각적 검사를 위해 경로를 MEDIA: 구문으로 출력하십시오.
2. 최종 파일(예: out.png)에서 vision_analyze를 호출하여 최소한의 다크 테마 PNG를 검사하고 제품이 올바른지 확인하십시오.
3. HTML 문서를 로컬 파일로 작성하십시오.
4. PNG를 로컬 파일로 작성하십시오. 요청된 다른 형식도 마찬가지입니다.
5. HTML에서 PNG가 생성되었으므로 먼저 전달하십시오.

선택 사항 — 갤러리 공유

공개 갤러리에 다이어그램을 업로드하려면 share.py를 사용하고 사용자에게 확인을 요청하십시오.

python3 scripts/share.py <out.html> [out.png]

모든 사람이 스택 다이어그램을 찾고 공유할 수 있는 공개 URL을 반환합니다. 이 단계를 수행하기 전에 사용자에게 직접 물어보십시오. 절대 추측하지 마십시오.

대체 워크플로우 — AI 에이전트(Claude Code, Cursor, Codex)를 위한 직접 사용

AI 에이전트는 이 파일의 지침을 직접 따를 수 있습니다. 이 워크플로우는 Hermes 통합 및 미리 번들된 스크립트가 필요하지 않습니다. 대신, 적절한 콘텐츠, 좌표 및 아이콘을 사용하여 assets/template.html의 복사본을 수동으로 편집하고, 아래 단계와 일치하는 렌더링 스크립트를 참조할 수 있습니다.

AI 에이전트를 위한 지침

1. 템플릿 복사: assets/template.html을 읽고 작업 디렉토리에 복사하십시오.
2. 아이콘 가져오기: fetch_icons.py를 직접 또는 수동으로 실행하십시오.
3. 템플릿 편집: 기술 이름, 역할, 그룹, 엣지 및 좌표를 추가하여 HTML을 수정하십시오.
4. 빌드(선택 사항): 또는 빌드 스크립트를 사용하여 HTML을 조립할 수 있습니다.
5. 렌더링: Playwright를 사용하여 PNG를 생성하십시오.
6. 검증: PNG의 시각적 분석을 수행하십시오.
7. 전달: HTML 및 PNG 파일을 제공하십시오.