fireworks-tech-graph 딥다이브
— 말로 시키면, 검사까지 통과한 다이어그램이 나온다

1한 줄 정체

fireworks-tech-graph는 "시스템을 말로 설명하면, AI가 다이어그램 설계도(JSON)를 쓰고, 파이썬 검증기가 기하·의미 규칙으로 검사한 뒤에만 SVG/PNG/GIF/HTML로 내보내 주는 Codex·Claude Code 겸용 에이전트 스킬"이다. 아키텍처·플로우차트·시퀀스 같은 기본형부터 UML 14종 전부, 그리고 RAG 파이프라인·Mem0 메모리·멀티 에이전트 같은 AI/에이전트 도메인 패턴까지 내장돼 있다. 비주얼 스타일은 12가지 — 플랫 아이콘, 다크 터미널, 블루프린트, Notion 클린, 글래스모피즘, Claude 공식풍, OpenAI 공식풍, 다크 럭셔리, 그리고 C4 리뷰·클라우드 배포·이벤트 스트림·SRE 골든 시그널용 엔지니어링 전용 4종.

동작 흐름을 압축하면 이렇다:

2왜 주목받는가 — "그럴듯한 그림"과 "검증된 도면"의 차이

타이밍부터 보자. 2026년 상반기는 에이전트 스킬 생태계가 폭발한 시기다. Claude Code와 Codex가 나란히 스킬 규격을 지원하면서 GitHub엔 스킬 레포가 쏟아졌는데, 대부분은 마크다운 지침 몇 장짜리다. 이 레포는 정반대 극단을 보여줬다 — 2026-04-10 첫 공개 후 석 달 동안 v1.0 → v1.1(엔지니어링 스타일 4종 + 통합 CLI) → v1.2(GIF 모션)로 달리며, JSON 스키마·단위 테스트·CI·npm 배포·릴리스 노트·회귀 베이스라인을 갖춘 "제품급 스킬"을 만들었다. 스킬 하나에 파이썬·JS 코드가 1.2만 줄 붙어 있는 경우는 드물다.

두 번째 이유가 본질이다. LLM에게 다이어그램을 그리게 해 본 사람은 다 안다 — 첫눈엔 그럴듯한데 자세히 보면 화살표가 박스를 관통하고, 라벨이 선 위에 겹치고, 레전드가 노드를 덮는다. 문법(XML)은 맞는데 시각적으로 엉망인, "문법 오류 없는 헛소리"의 그림 버전이다. 이 레포의 답은 미학을 측정 가능한 예산(budget)으로 번역한 것이다: 교차 0개, 엣지당 굽힘 ≤2, 전체 굽힘 ≤8, 우회율 ≤1.35배, 노드 간격 ≥40px, 컨테이너 여백 ≥20px, 라벨 이격 ≥4px. 이 숫자들은 문서가 아니라 실행되는 코드(composition_quality.py)로 존재하고, 위반하면 위반 코드(EDGE_BEND_BUDGET 등)와 함께 빨간불이 켜진다.

기존 도구들과 뭐가 다른가

세 번째 이유는 "Loop Engineering"이라는 이름의 운영 철학이다. README가 다섯 원칙을 명시한다: ① 평가하라, 주장하지 말라(evaluate, don't assert) ② 결정적 검사 먼저 ③ 지각적 검증(PNG 읽기)은 그다음 ④ 수정은 진단된 부분만 겨냥 ⑤ 수렴은 유한하게(시각 리뷰 후 수정 최대 2회). 에이전트 워크플로를 설계해 본 사람이라면 이게 다이어그램만의 얘기가 아니라 "AI에게 일 시키고 결과를 믿을 수 있게 만드는 일반 패턴"임을 알아본다 — 트렌딩의 상당 지분이 이 각도다. 이미지 리더가 없는 런타임이면 visual_review: skipped (image reader unavailable)라고 정직하게 보고하게 한 디테일까지.

3기술 스택 전체 지도

핵심 스택은 의외로 보수적이다. 생성기·검증기·기하 엔진 전부가 파이썬 표준 라이브러리만으로 짜여 있다(fireworks_geometry.py 주석에 이유가 적혀 있다: "갓 설치한 스킬에서도, CI에서도, 사후 검사기에서도 같은 라우팅 계약을 강제하기 위해"). 외부 의존성은 출력 단계에만 붙는다.

① 코어 — Python 3.9+ (stdlib only)

• fireworks.py (220줄) — doctor / validate / render / check / inspect / export-html / animate / examples 8개 서브커맨드의 통합 CLI. 모든 출력이 JSON이라 에이전트가 파싱하기 좋다.
• generate-from-template.py (3,369줄) — 실제 SVG 생성기. 스타일 토큰 주입, 직교 라우팅, 포트 배정, 레전드 재배치까지 담당하는 최대 모듈.
• diagram_ir.py (201줄) — 입력 JSON을 스키마 v1로 정규화하는 타입 경계.
• semantic_contracts.py (694줄) — 스타일 카탈로그 + 엔지니어링 4종(스타일 9–12)의 도메인 검증.
• composition_quality.py (271줄) — 구도 품질 예산(교차·굽힘·간격) 판정.
• validate_svg.py (961줄) — 완성된 SVG의 XML·마커·기하·충돌 검사.
• motion.py (2,371줄) — SVG→GIF 모션 계획·검증·인코딩·원자적 설치.
• interactive_html.py (356줄) — SVG를 소독(sanitize)해 오프라인 뷰어 HTML로 포장.

② 래스터화 — 렌더러 3택

③ 모션 파이프라인 (선택 설치)

• svg2gif.js (2,887줄) — puppeteer-core@25.3.0으로 Chromium을 띄워 타임라인 프레임을 캡처하는 워커. FFmpeg/FFprobe로 인코딩·검증.
• 레포에서 두 번째로 큰 파일이 GIF 워커라는 사실 자체가, v1.2의 무게중심이 모션 검증에 있음을 보여준다.

④ 지식층 — 코드가 아닌 자산

• SKILL.md (500줄) — 워크플로 12단계, 다이어그램 타입별 레이아웃 규칙, 도형 어휘, 화살표 의미론, 검증 체크리스트.
• references/ 17개 문서 — 스타일 12종의 정확한 색 토큰·SVG 패턴, 구도 품질 계약, 모션 계약, 제품 아이콘 40여 종(OpenAI·Anthropic·Pinecone·Kafka·PostgreSQL…), PNG 내보내기 가이드.
• schemas/ — 다이어그램 JSON 스키마(v1). fixtures/ — 스타일별 회귀 기준 12세트. templates/ — 시작용 SVG 10종.

⑤ 품질·배포 인프라

• tests/ 9개 파일 — 기하 계약, IR, CLI, 모션, 설치 호환성까지 unittest로 커버. CI + 태그 릴리스 워크플로에서 실제 Chromium으로 12스타일 × 852개 프레임 비교 회귀까지 돈다.
• 배포 3경로 — ① npx skills add(권장) ② git clone ③ npm 패키지(@yizhiyanhua-ai/fireworks-tech-graph). npm tgz와 GitHub 릴리스 zip이 같은 페이로드인지 파일 해시로 CI가 대조한다(tools/distribution.py --check).

4아키텍처 심화 — 비결정적 AI 위에 결정적 검증기를 얹는 법

이 레포의 아키텍처를 한 문장으로 요약하면 "비결정층과 결정층의 분리"다. 창의성이 필요한 일(요청 해석, 무엇을 어디에 놓을지)은 LLM이 하고, 정확성이 필요한 일(라우팅 계산, 규칙 검사, 인코딩)은 전부 파이썬이 같은 입력이면 항상 같은 출력이 나오게 처리한다. 층과 층 사이의 인터페이스가 바로 다이어그램 IR(중간 표현) JSON이다.

인터페이스가 되는 IR JSON — 실제 생김새

동봉된 회귀 픽스처 fixtures/mem0-style1.json을 줄여 보면 이렇다. 에이전트가 쓰는 건 좌표가 박힌 SVG가 아니라 이 수준의 선언적 구조다:

{
  "schema_version": 1,
  "mode": "memory",  "style": 1,  "quality_profile": "showcase",
  "title": "Mem0 Memory Architecture",
  "containers": [ { "id": "memory-core", "label": "Memory Manager", … } ],
  "nodes": [
    { "id": "llm",    "kind": "double_rect", "label": "LLM", … },
    { "id": "vector", "kind": "cylinder",    "label": "Vector Store", … }
  ],
  "arrows": [
    { "source": "manager", "target": "vector",
      "flow": "write",            ← 의미(색·점선을 스타일이 결정)
      "source_port": "bottom",    ← 어느 변에서 나갈지
      "corridor_y": [420],         ← "이 복도로 지나가라" 힌트
      "motion_role": "memory-write", "motion_stage": 5 } ← GIF 순서
  ],
  "legend": [ { "flow": "write", "label": "memory write" }, … ]
}

주목할 설계 선택: 화살표에 좌표 대신 flow: "write" 같은 의미를 적게 하고, 색·굵기·점선은 스타일 계층이 결정한다. 도형도 마찬가지 — LLM은 이중 테두리 사각형, 에이전트는 육각형, 벡터 스토어는 줄무늬 실린더라는 도형 어휘(shape vocabulary)가 12스타일 전체에서 일관된다. 덕분에 "스타일 2로 다시"라고 하면 구조는 그대로 두고 시각층만 갈아끼울 수 있다.

1차 관문: 스키마 정규화 (diagram_ir.py)

모든 입력은 렌더링 코드에 닿기 전에 normalize_diagram()을 통과한다. 여기서 잡는 것: 중복 ID(노드끼리는 물론 노드↔컨테이너 간에도), 존재하지 않는 노드를 가리키는 화살표, NaN·Infinity 좌표, 잘못된 waypoint 형식, 미지원 스키마 버전. 옛 형식(legacy JSON)도 받아 주되 v1로 정규화해서 넘긴다 — 하위 호환과 엄격함을 동시에 가져가는 전형적인 "versioned IR" 패턴이다.

2차 관문: 의미 계약 (semantic_contracts.py) — 이 레포의 가장 독창적인 부분

스타일 9–12는 단순 테마가 아니라 도메인 규칙이 붙은 문서 양식이다. 각 스타일이 기본 의미 프로파일을 데려온다:

재미있는 디테일: 프로파일·스타일 별칭 사전에 "事件地铁图"(이벤트 지하철도), "可靠性脉冲"(신뢰성 펄스) 같은 중국어 표현이 영어와 나란히 등록돼 있다. 중국어권 사용자를 처음부터 1급 시민으로 설계한 것 — README도 영·중 이중이다.

3차 관문: 구도 품질 예산 (composition_quality.py)

기하적으로 "합법"인 다이어그램과 "보기 좋은" 다이어그램은 다르다. 이 모듈은 후자를 숫자로 정의한다. 프로파일 두 개가 내장:

판정 결과는 점수로도 나온다: 100 − (위반 × 12 + 브리지 × 8 + 초과 굽힘 × 2). 위반마다 NODE_GAP, EDGE_ROUTE_STRETCH 같은 코드와 실측값·한계값이 붙어 나오므로, 에이전트는 "어디를 얼마나 고쳐야 하는지"를 기계가 알려주는 피드백으로 받는다. 수정 루프가 감으로 돌지 않는 이유다.

라우팅 — 결정적 직교 배선

화살표는 전부 직각(orthogonal)으로만 꺾인다. 생성기가 노드·헤더·레전드·타이틀을 장애물로 놓고 경로를 계산하며, 같은 변에 여러 화살표가 몰리면 포트를 결정적으로 분산 배정한다. 에이전트가 개입하고 싶으면 IR에 힌트를 얹는다: corridor_x/y(이 복도로 지나가라 — 부드러운 선호), route_points(정확한 경유지 — 단 위험한 지점은 거부됨), source_port/target_port(출입 변 지정). 도저히 피할 수 없는 교차엔 점프 아크(bridge)를 그려 "선이 겹친 게 아니라 넘어간 것"임을 시각적으로 못박고, 같은 선분끼리의 공선 겹침은 치명 오류로 처리한다.

모션 — GIF마저 계약으로 검증한다

v1.2의 야심작. "이 다이어그램 움직이게 해줘(生成 GIF)"라고 하면 motion.py가 생성된 SVG를 받아 GIF로 굽는데, 여기도 자유 애니메이션이 아니라 12개 스타일별 모션 계약이 있다:

• 타임라인 고정 — 기본 5.75초/115프레임/20fps. 프레임 1–36에서 연결선이 의미 순서(motion_stage)대로 그려지고, 38–109는 데이터가 흐르는 "정착 상태", 110–114에서 리셋 후 무한 루프.
• 프레임 유니크니스 게이트 — 최소 75개 프레임은 래스터가 서로 달라야 하고 인접 중복은 금지. "움직이는 척하는 정지 GIF"를 기계로 걸러낸다. 유일한 예외(리셋 경계인 110번 프레임 반복)까지 intentional_reset_boundary_repeat이라는 이름으로 분류해 둔다.
• 검증 증거 동봉 — 출력마다 <이름>.motion.json 리포트가 따라붙고, FFprobe로 해상도·프레임 수·루프를 재검증한 뒤 임시파일 → os.replace의 원자적 설치로만 최종 파일을 놓는다.
• 스타일 시그니처 — 스타일 7은 "API 레일 위 3칸짜리 토큰 기차", 스타일 12는 "ECG 파형 + 트레이스 워터폴 스캐너"처럼 스타일마다 고정된 움직임 정체성이 있고, 이 계약들은 사람이 승인한(user-approved) 기준선으로 박제돼 회귀 테스트가 지킨다.

오프라인 HTML 뷰어 — 소독 먼저

export-html은 SVG 하나를 팬/줌/라이트·다크 테마/소스 복사/1–4× PNG·JPEG·WebP 내보내기가 되는 단일 오프라인 HTML로 포장한다. 포장 전에 sanitize_svg가 스크립트·이벤트 핸들러·외부 참조·foreignObject·외부 CSS를 전부 거부한다 — 생성물이 어디로 공유될지 모르니 뷰어 자체를 공격 표면으로 만들지 않겠다는 방어다.

5디렉토리 구조 해부

가장 특이한 지점은 마지막 줄이다. 레포 안에 skills/fireworks-tech-graph/라는 이름으로 레포 전체가 한 번 더 복제돼 들어 있다. 이유: npx skills add CLI가 저장소 루트를 설치하면 루트 SKILL.md만 집어 가는 버전이 있어서, 중첩 경로를 지정해 완전한 폴더가 설치되도록 만든 우회다. 사본이 둘이면 어긋나기 마련인데, 그래서 tools/check_project_consistency.py가 CI에서 두 트리의 동일성을 검사한다 — "복제본은 반드시 기계로 대조한다"는 이 레포다운 해법.

6학습 포인트 — 기술별 배울 것

7시스템 / 실행 요구사항

설치 (권장 경로)

# 중첩 경로까지 지정해야 완전한 스킬이 설치된다 (루트만 주면 SKILL.md만 집는 버전이 있음)
npx -y skills@1.5.17 add \
  yizhiyanhua-ai/fireworks-tech-graph/skills/fireworks-tech-graph \
  --agent codex claude-code -g -y --copy
# → ~/.claude/skills/fireworks-tech-graph (Claude Code)
# → ~/.agents/skills/fireworks-tech-graph (Codex)

통합 CLI 8개 서브커맨드

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 로드맵 (주차별)

10핵심 키워드 사전

11참고 링크

• GitHub 저장소: github.com/yizhiyanhua-ai/fireworks-tech-graph
• 쇼케이스(GitHub Pages): yizhiyanhua-ai.github.io/fireworks-tech-graph — 12스타일 GIF 한눈에
• 1차 소스: SKILL.md(워크플로 전체) · docs/CAPABILITIES.md(능력 계약서) · scripts/composition_quality.py(예산 숫자 원본) · fixtures/*.json(IR 실물)
• npm 패키지: @yizhiyanhua-ai/fireworks-tech-graph
• 에이전트 스킬 문서: Claude Code Skills · Codex 쪽은 learn.chatgpt.com의 build-skills 문서
• 비교 대상: Mermaid(DSL 방식) · draw.io(수작업 방식)
• 참고 개념: orthogonal edge routing, graph drawing aesthetics, JSON Schema, golden-file testing, C4 model, golden signals(SRE), atomic file replace