terra-form

Terraform → 클라우드 인프라 다이어그램

*.tf를 읽어 내장 엔진의 TS DSL을 저작하고 렌더한다. 산출물은 자동배치·직교 라우팅이 적용된 단일 .html(+.png/.svg)이다.

역할 분담: *.tf가 있는 클라우드 인프라(프로바이더 무관) → 이 스킬. tf가 없으면 → zzon-doc infra kind. 같은 프로젝트에서 zzon-doc 개요(컨텍스트)와 terra-form 인프라 상세가 공존하는 게 정상이다. 어휘 규칙: IaC 기반 클라우드/네트워크 장 = 클라우드 아이콘, 프로젝트 단위·C4 레이어 장 = 카테고리 카드(zzon-doc). 레거시 DiagramSpec을 클라우드 아이콘으로 올리려면 스펙에 "vocabulary": "aws" 한 줄이면 된다(매핑 불가 노드가 있으면 전체 카드 유지 — 혼용 없음).

프로바이더별 어휘 (스캔 단계에서 provider 블록으로 감지)

프로바이더	노드 어휘	그룹
aws	공식 AWS 아이콘 838종 (grep manifest.gen.ts)	vpc/region/subnet/account + AZ×티어 grid()·overlay()
google·azurerm 등	카테고리 카드(category/tech) + 필요 시 assets/extra-icons/에 공식 아이콘 추가(x.*)	generic 그룹 + 라벨 (VNet·리소스그룹 등은 라벨로 표기)

한 다이어그램 안에서 어휘를 섞지 않는다(validator가 막는다 — allowMixedVocabulary는 멀티클라우드 하이브리드 다이어그램처럼 의도가 명확할 때만). GCP/Azure 공식 아이콘 팩 파이프라인은 로드맵 — 추가 시 이 표만 갱신하면 된다.

0. 엔진 위치

플러그인 동봉: ${CLAUDE_PLUGIN_ROOT}/engine (bun+TS). 최초 1회 cd engine && bun install. $ENGINE은 이후 이 경로를 뜻한다. bun이 없으면 설치 안내 후 멈춘다.

1. 범위 잡기 (게이트 — 어기지 마라)

① tf 스캔 → ② 제안·승인 → ③ 작성. 승인 전에 DSL 파일을 만들지 마라.

1. 스캔: envs/*/main.tf(모듈 조합 = 그림의 그룹 구조) → 각 모듈의 resource 종류·수를 센다. env 간 변수 불일치(stale env — 모듈이 안 받는 변수를 넘기는 등)를 발견하면 그리기 전에 보고한다.
2. 제안은 반드시 이 형태로 — 리소스 ~20개 이하 & 목적 자명이면 기본값 명시 후 바로 진행, 그 외엔 한 묶음(최대 4문)으로 묻는다:
   • 환경/스코프: dev / prd / 특정 모듈만 (env가 갈리면 그림이 다르다 — 현행 env를 근거와 함께 추천). 멀티 프로바이더면 어느 클라우드를 그릴지도 함께
   • 상세 수준: 개요(서비스 단위) / 표준(리소스 단위) / 상세(서브넷·IAM까지)
   • 강조 관점: 요청 흐름 / 데이터 파이프라인 / 네트워크 경계 / CI·CD / 보안 → 엣지 layer 구성이 된다
   • 생략 규칙: IAM·로그·모니터링 생략 여부 — "전부 표시"는 명시적 동의를 받는다
3. 답을 한 줄로 복창하고 시작한다. 무엇을 생략했는지는 전달 시에도 반드시 명시한다.

2. DSL 저작 — 계약

• 파일 위치: 대상 프로젝트의 docs/zzon-doc/terra/<slug>.ts (다이어그램 소스도 그 프로젝트가 버전 관리한다). 구버전 기본값인 루트 zzon-doc/ 산출 폴더가 이미 있으면 그걸 계속 쓴다 — 아래 경로도 전부 그 폴더 기준으로 바꾼다.
• API 정본은 엔진의 examples/*.ts 4종 — 반드시 하나를 먼저 읽는다 (serverless-sample.ts가 서버리스, eks-cluster.ts가 격자+overlay, multi-account-lz.ts가 멀티계정, multi-region-cicd.ts가 멀티리전).
• 계층: d.group(kind:"aws-cloud") ▸ region ▸ 리소스. VPC의 AZ×티어는 grid()+cell(), 격자를 가로지르는 논리 그룹(ASG·노드풀)은 overlay().
• 액터는 d.actor(side:), 외부 SaaS·부속 행은 d.band("right"|"bottom") — 외부 관리형(DB SaaS 등)은 오른쪽 밴드가 관례.
• 엣지는 layer: 필수(request/pipeline/deploy/monitor…) — HTML 레이어 토글의 단위다.
• 같은 의미의 반복 리소스(크론 N개, ECR N개)는 노드 1개 + sublabel로 압축. 흐름 순번은 d.step().
• 설명 문장은 캔버스에 그리지 않는다 — description:(클릭 시 사이드바)에 담고, 라벨은 리소스 이름 위주로 짧게.
• 아이콘 키는 실재 확인: grep '"<키>"' $ENGINE/src/icons/manifest.gen.ts $ENGINE/src/icons/aliases.ts. 없으면 별칭 → 유사 서비스 → res.* 제네릭 순. 상표 제약 로고(Grafana 등)는 제네릭으로.
• 본질적으로 넓은/좁은 그림은 diagram(id, { aspectRatio })로 의도를 선언한다.
• tf에서 읽은 것만 옮긴다. 읽히지 않는 값(실 배포 상태)이 필요하면 terraform show -json을 요청한다.