Markdown/MDX 문서
  ↓ prepare: 현재 섹션 + 앞/뒤 형제 섹션 + 라인 번호 + 문서 해시
Context Package
  ↓ Codex / Claude / Antigravity: 의도·대상 독자·그림 유형 선택
Grounded VizSpec JSON
  ↓ lint: 사실 근거·복잡도·방향·레이블·접근성·신선도 검사
Deterministic Renderers
  ├─ SVG             배포 기본
  ├─ draw.io         엔터프라이즈 편집/클라우드 스텐실
  ├─ Mermaid         Markdown 인접 다이어그램
  ├─ D2              자동 배치 아키텍처/데이터 흐름
  ├─ Graphviz DOT    밀집 의존성 그래프
  ├─ Excalidraw      개념 스케치/워크숍
  └─ alt.md          대체 텍스트와 구조화된 상세 설명
  ↓ insert
관리되는 문서 블록 + manifest

왜 중간 표현이 필요한가

그림 도구 문법과 기술적 의미를 한 단계에서 생성하면 다음 문제가 생깁니다.

보기 좋은 도형이 원문에 없는 관계를 사실처럼 표현한다.
Mermaid, draw.io, SVG마다 같은 의미가 서로 다르게 드리프트한다.
PR에서 시각 결과만 보고 “왜 이 노드와 화살표가 존재하는지” 검토하기 어렵다.
에이전트나 도구를 교체할 때 작성 규칙을 다시 구현해야 한다.

VizSpec은 모든 노드·엣지·경계에 원문 라인 범위 또는 명시적 가정을 기록합니다. 모델 JSON은 렌더링 전에 엄격한 필드·타입 검사를 거치며, 알 수 없는 필드나 문자열로 위장된 불리언 같은 암묵적 형변환을 허용하지 않습니다. 의미 검토를 통과한 하나의 IR에서 여러 형식을 결정적으로 생성합니다.

조사에서 반영한 공통 원칙

대형 클라우드/IT 기술문서와 공식 다이어그램 지침에서 반복되는 패턴을 하네스 정책으로 고정했습니다.

메시지·독자·수명주기에 맞는 그림 유형을 선택한다. 컨텍스트, 컨테이너/컴포넌트, 배포, 데이터 흐름, 시퀀스, 네트워크 등을 한 그림에 섞지 않습니다.
편집 가능한 원본과 배포 산출물을 함께 보존한다. SVG를 기본 배포물로 두고 draw.io/Mermaid/D2/DOT/Excalidraw 중 목적에 맞는 원본을 버전 관리합니다.
방향, 레이블, 범례, 경계를 명시한다. 양방향 화살표를 피하고 노드는 명사, 엣지는 동사·프로토콜·이벤트·데이터로 표기합니다.
점진적 공개를 사용한다. 하나의 거대한 그림 대신 개요에서 세부 뷰로 내려갑니다.
공식 서비스 아이콘은 정확한 제품을 표현할 때만 사용한다. 일반 개념은 일반 도형으로 유지하고, 아이콘만으로 제품명을 대체하지 않습니다.
접근성과 버전 관리를 설계에 포함한다. 색상만으로 의미를 구분하지 않고, SVG <title>/<desc>, 짧은 alt, 상세 설명, 문서 해시, manifest를 함께 생성합니다.

상세 근거와 도구 비교는 references/research-notes.md, references/source-catalog.md, references/visual-principles.md, references/format-selection.md에 정리되어 있습니다.

설치

Python 3.11 이상만 필요합니다. 기본 SVG와 편집 원본 생성에는 외부 패키지가 없습니다.

python -m venv .venv
source .venv/bin/activate
pip install -e .
techviz doctor

선택적으로 실제 도구 렌더링을 추가할 수 있습니다.

dot: Graphviz DOT → SVG/PNG
d2: D2 → SVG/PNG/PDF
mmdc: Mermaid CLI → SVG/PNG/PDF
diagrams.net 데스크톱 CLI: draw.io 변환

하네스 자체는 해당 실행 파일이 없어도 각 편집 소스를 생성합니다.

빠른 실행

1. 문서에 생성 위치 표시

## 결제 요청 경로

클라이언트는 HTTPS로 인증 게이트웨이에 결제 요청을 보낸다.
...

<!-- techviz:generate id=payment-request -->

2. 앞뒤 문맥 추출

techviz prepare docs/checkout.md \
  --marker payment-request \
  -o .techviz/payment-request/context.json

prepare는 현재 섹션과 앞/뒤 형제 섹션을 추출합니다. 이미 생성된 TechViz 블록은 원래 마커 한 줄로 축약한 정규화 뷰에서 해시와 라인 번호를 계산하므로, 재실행 시 이전 그림이 모델 문맥을 오염시키지 않습니다.

3. 에이전트가 VizSpec 생성

techviz prompt .techviz/payment-request/context.json \
  -o .techviz/payment-request/prompt.md

Codex, Claude 또는 Antigravity가 이 프롬프트/스킬을 이용해 spec.json을 작성합니다. 중요한 계약은 다음과 같습니다.

{
  "id": "checkout-api",
  "label": "체크아웃 API",
  "kind": "service",
  "evidence": [
    {"start_line": 11, "end_line": 13}
  ],
  "assumption": false
}

경계 역시 사실 주장이므로 같은 계약을 적용합니다. assumption: true인 요소는 근거 배열이 비어 있어야 하며, 근거와 가정을 한 요소에 동시에 표시하면 린트 오류입니다.

{
  "id": "private-network",
  "label": "Private network",
  "kind": "network",
  "evidence": [
    {"start_line": 30, "end_line": 31}
  ],
  "assumption": false
}

4. 품질 게이트

techviz lint .techviz/payment-request/spec.json \
  --context .techviz/payment-request/context.json

검사 항목:

중복/잘못된 ID와 끊어진 참조
근거가 없는 노드·엣지·경계
문서 범위를 벗어난 근거 라인
문서 해시 불일치와 오래된 스펙
비어 있는 핵심 레이블
레이블 과장, 무레이블 엣지, 자기 루프
시퀀스 순서 누락
엣지가 다른 노드를 관통하는 배치
엣지 교차·장거리 중첩과 문서 폭에 맞지 않는 캔버스
12개 노드/18개 엣지를 넘는 복잡도
alt/상세 설명 누락 또는 중복
미승인 가정

lint는 명시적 가정을 경고로 보여 주어 반복 작업은 허용하지만, render, build, insert는 기본적으로 가정이 하나라도 있으면 게시를 차단합니다. 문서 작성자가 검토·승인한 경우에만 --allow-assumptions를 사용하며, 그 결정과 가정 개수는 manifest에 기록됩니다.

5. 다중 형식 컴파일

techviz render .techviz/payment-request/spec.json \
  --context .techviz/payment-request/context.json \
  --formats svg,drawio,mermaid,d2,dot,excalidraw,a11y \
  -o docs/assets/payment-request

6. 문서 업데이트

techviz insert docs/checkout.md \
  --spec .techviz/payment-request/spec.json \
  --svg docs/assets/payment-request/payment-request.svg \
  --editable docs/assets/payment-request/payment-request.drawio

또는 한 번에 실행합니다.

techviz build .techviz/payment-request/spec.json \
  --context .techviz/payment-request/context.json \
  -o docs/assets/payment-request \
  --document docs/checkout.md

생성 블록에는 SVG, 상세 설명, 편집 원본, VizSpec 링크와 컨텍스트 해시가 들어가며 같은 ID로 재실행하면 안전하게 교체됩니다.

그림 유형 선택

문서가 답해야 하는 질문	기본 유형	권장 편집 소스
시스템 안/밖과 상호작용 주체는 누구인가?	Context	draw.io / D2 / Structurizr
책임과 정적 의존성은 어떻게 나뉘는가?	Architecture / Container / Component	draw.io / D2 / Structurizr
어디에 배치되고 어떤 경계를 넘는가?	Deployment / Network	draw.io
데이터는 어디서 생겨 변환·저장·배출되는가?	Data flow	D2 / draw.io
한 시나리오가 시간순으로 어떻게 진행되는가?	Sequence	Mermaid
절차와 결정 조건은 무엇인가?	Flow	Mermaid / draw.io
유효 상태와 전이는 무엇인가?	State	Mermaid
엔터티와 관계/카디널리티는 무엇인가?	ERD	Mermaid / draw.io
무엇이 무엇에 의존하는가?	Dependency	Graphviz DOT
구현이 아닌 개념적 작동 원리는 무엇인가?	Concept	Excalidraw / SVG

형식 정책

SVG를 배포 기본으로 사용하는 이유

확대해도 깨지지 않고 텍스트 검색이 가능하다.
Markdown/웹 문서에 직접 포함하기 쉽다.
<title>, <desc>, 메타데이터를 포함할 수 있다.
XML 텍스트이므로 저장소에서 변경을 추적할 수 있다.

생성 SVG는 스크립트, 외부 참조, foreignObject를 사용하지 않습니다. 외부 도구가 내보낸 임의 SVG를 그대로 신뢰하는 대신 하네스 렌더러가 안전한 하위 집합을 생성합니다.

draw.io를 아키텍처 편집 기본으로 사용하는 이유

AWS, Azure, Google Cloud, IBM, Oracle 등 공급자 스텐실을 활용하는 엔터프라이즈 아키텍처 전달에 익숙하고, 수동 연결선/경계 조정이 쉽습니다. 배포 SVG와 별도로 .drawio 원본을 보존해 편집 의미가 사라지지 않게 합니다.

Mermaid/D2/DOT/Excalidraw의 역할

Mermaid: 저장소 Markdown과 가까운 소형 다이어그램, 특히 sequence/state/ERD.
D2: 자동 배치가 중요한 데이터 흐름과 아키텍처.
DOT: 밀집 그래프의 레이아웃 최적화.
Excalidraw: 초안·워크숍·개념 설명. 정밀 최종 아키텍처의 기본값은 아닙니다.

에이전트 호스트 통합

하나의 canonical skill을 세 위치로 동기화합니다.

skills/technical-visualizer/SKILL.md          canonical
.agents/skills/technical-visualizer/SKILL.md  Codex + Antigravity
.claude/skills/technical-visualizer/SKILL.md  Claude Code

python scripts/sync_skills.py

Codex: 저장소의 AGENTS.md와 .agents/skills/technical-visualizer를 사용합니다.
Claude Code: CLAUDE.md와 .claude/skills/technical-visualizer를 사용합니다.
Antigravity: .agents/skills/technical-visualizer와 .agents/rules/techviz.md를 사용합니다.

에이전트별 프롬프트를 세 벌 유지하지 않고, 결정적 작업은 CLI에 두고 의미 판단만 모델에 맡깁니다.

보안 모델

문서 기반 에이전트는 본문 안의 프롬프트 인젝션에 노출됩니다. 하네스는 다음 경계를 둡니다.

문서 내용은 명령이 아니라 비신뢰 증거 데이터로 선언한다.
모델 출력은 자유 형식 SVG/XML이 아니라 제한된 VizSpec JSON이며, 스키마 밖 필드와 잘못된 타입을 거부한다.
사실 요소는 라인 근거를 요구한다.
렌더러가 안전한 SVG 하위 집합을 생성한다.
외부 URL, 스크립트, 임베디드 HTML을 SVG에 넣지 않는다.
렌더와 문서 삽입 전에 스펙을 린트하고, 미승인 가정은 게시 단계에서 차단한다.

프로덕션 적용 시 CI에서 techviz lint와 생성 파일 재현성 검사를 필수 체크로 두는 것을 권장합니다. 승인된 가정을 게시해야 하는 예외 경로는 --allow-assumptions 사용 여부와 manifest diff가 코드 리뷰에 남도록 구성합니다.

저장소 구조

src/techviz/
  document.py       문맥·섹션·정규화·해시
  prompt.py         모델 중립 프롬프트
  spec.py           VizSpec 데이터 모델과 엄격한 모델 출력 파서
  validate.py       의미/근거/복잡도/접근성 린터
  layout.py         결정적 계층형 배치, 포트 분산, 직교 엣지
  quality.py        관통·교차·중첩·캔버스 기하 품질 검사
  renderers/        SVG, Mermaid, D2, DOT, draw.io, Excalidraw, a11y
  insert.py         멱등 문서 블록 업데이트
  cli.py            prepare/prompt/lint/render/insert/build/doctor
schemas/
  vizspec.schema.json
skills/
  technical-visualizer/SKILL.md
references/
  visual-principles.md
  format-selection.md
  diagram-types.md
  research-notes.md
examples/
tests/

테스트

make test

예제를 다시 생성합니다.

make example

현재 범위와 다음 확장

이 프로토타입은 Markdown/MDX 문서와 일반적인 노드-엣지 기술 다이어그램을 우선합니다. 다음 확장은 구조적으로 열려 있습니다.

AsciiDoc, reStructuredText, Docusaurus/MkDocs AST 어댑터
Structurizr DSL/C4 다중 뷰 백엔드
PlantUML/Kroki 백엔드
공급자 공식 아이콘 레지스트리와 라이선스 메타데이터
SVG 텍스트 실제 치수 측정과 자동 줄바꿈 개선
교차선·엣지-노드 충돌을 가중한 품질 점수와 자동 재배치
시퀀스/ERD/배포 전용 SVG 레이아웃
문서 diff 기반 선택적 재생성
PR 코멘트 리포터와 SVG 시각 diff
사람 승인 워크플로와 가정 해소 상태

중요한 확장 원칙은 동일합니다. 문서 사실 → 검토 가능한 의미 모델 → 결정적 렌더링 순서를 유지합니다.