에이전트 하네스입니다. 기존 Markdown/MDX 기술문서의 앞뒤 문맥을 읽어 문서에 근거한 diagram-only 기술 시각화를 생성합니다. Codex, Claude Code, Antigravity가 같은 Agent Skill, CLI, VizSpec IR을 사용합니다.

0.2.0에서 해결한 문제

0.1.x의 예제 갤러리는 렌더러의 목표 품질을 보여 주었지만 실행 파이프라인과 연결되지 않았습니다. 그 결과 모델은 예제를 보지 않은 채 일반 노드 목록을 생성했고 런타임은 모든 문서를 같은 위상 정렬과 둥근 박스로 그릴 수 있었습니다. 전역 제목·질문·footer도 SVG 안에 반복되었습니다.

0.2.0은 이 문제를 런타임 계약 수준에서 수정합니다.

문맥에 맞는 로컬 reference grammar를 자동 선택합니다.
선택된 preview와 실제 실행 가능한 runtime spec 경로를 모델 프롬프트에 넣습니다.
VizSpec 1.1에 composition.profile, node role, shape/detail/emphasis를 추가했습니다.
profile별 전용 compositor를 사용합니다.
comparison과 timeline을 제외한 끊어진 카드 묶음을 하드 오류로 차단합니다.
문맥에서 선택되지 않은 profile/reference 사용을 lint 오류로 차단합니다.
여러 결과가 하나의 topology로 붕괴하는 현상을 audit-batch로 검출합니다.
SVG는 diagram-only이며 보이는 제목·부제·footer·워터마크를 생성하지 않습니다.

파이프라인

Markdown / MDX
  │
  ├─ techviz prepare
  │    현재 섹션 + 앞/뒤 섹션 + canonical line + SHA-256
  │    + 문맥 기반 reference 후보
  ▼
Context Package
  │
  ├─ techviz references
  │    reference preview / executable spec / score / matched terms
  │
  ├─ techviz prompt
  │    candidate profile set + 구조 규칙 + anti-pattern + VizSpec 1.1 scaffold
  ▼
Codex / Claude / Antigravity
  ▼
Grounded VizSpec 1.1
  │
  ├─ techviz lint
  │    근거, profile 역할, 연결성, 문맥 적합성, 접근성, 기하 검사
  │
  ├─ profile-specific deterministic compositor
  ▼
SVG + draw.io + Mermaid + D2 + DOT + Excalidraw + alt.md
  │
  ├─ techviz audit-batch
  │    다수 결과의 template/topology collapse 검사
  ▼
Managed Markdown block + manifest

설치

Python 3.11 이상이 필요합니다. 기본 SVG와 편집 원본 생성에는 외부 Python 의존성이 없습니다.

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

선택 도구:

dot: Graphviz 출력 렌더링
d2: D2 출력 렌더링
mmdc: Mermaid 출력 렌더링
diagrams.net CLI: draw.io 변환

빠른 실행

1. 문서에 생성 지점 표시

## 결제 요청 경로

클라이언트는 HTTPS로 인증 게이트웨이에 결제 요청을 보낸다.
인증 게이트웨이는 요청을 검증한 뒤 체크아웃 API로 전달한다.

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

2. 문맥 준비

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

context.json에는 문서 해시, canonical line range, 현재/인접 섹션과 함께 visual_reference_candidates가 기록됩니다. 이미 생성된 관리 블록은 원래 marker 한 줄로 축약되므로 이전 그림이 다음 모델 입력을 오염시키지 않습니다.

3. 선택된 reference 확인

techviz references .techviz/payment-request/context.json

출력 예:

payment-event-flow             component-flow           score=28  matched=request, 요청, 이벤트
  preview: examples/01-component-flow/payment-event-flow.preview.png
  runtime: examples/runtime-profiles/01-component-flow/spec.json
payment-approval-sequence      sequence                 score=8   matched=승인
  preview: examples/08-sequence/payment-approval-sequence.preview.png
  runtime: examples/runtime-profiles/08-sequence/spec.json

에이전트 호스트가 이미지를 열 수 있으면 preview를 확인하고 반드시 runtime spec.json도 읽습니다. 이미지 입력이 없는 호스트를 위해 동일한 구조 규칙이 프롬프트에 텍스트로 포함됩니다.

4. 모델 프롬프트 생성

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

모델은 프롬프트 전체를 사용해 .techviz/payment-request/spec.json을 작성합니다. 스키마만 보고 직접 작성하지 않습니다.

VizSpec 1.1의 핵심 블록:

{
  "version": "1.1",
  "composition": {
    "profile": "component-flow",
    "diagram_only": true,
    "reference_ids": ["payment-event-flow"],
    "rationale": "요청·저장·승인·이벤트가 하나의 방향성 있는 경로를 이룬다.",
    "focus_node": "checkout-api"
  }
}

모든 사실 노드·엣지·경계에는 원문 라인 근거가 있습니다.

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

5. lint

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

주요 hard gate:

근거 없는 사실 요소
문서 해시·anchor 불일치
문맥에서 선택되지 않은 profile/reference
두 개 이상 노드인데 중심 관계가 없는 카드 묶음
중심 관계에 참여하지 않는 노드가 20%를 초과
profile 필수 역할 누락
sequence order 누락/중복
timeline position 누락/중복
comparison detail 누락
source gap
끊어진 참조, 재귀 그룹, 잘못된 타입
엣지의 무관 노드 관통과 기하 충돌

assumption: true는 lint warning이지만 render, build, insert 단계에서는 기본적으로 게시를 차단합니다.

6. 렌더링

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

SVG에는 다이어그램 해독에 필요한 노드·경계·연결선·상태/시간 주석만 표시됩니다. title, question, summary는 접근성/문서 메타데이터이며 캔버스 헤드라인으로 렌더링되지 않습니다.

7. 여러 그림을 한 번에 생성했을 때 batch audit

techviz audit-batch .techviz --pattern "**/spec.json"

audit-batch는 레이블과 id를 제거한 topology fingerprint를 계산합니다. 25개 그림의 이름만 달라지고 구조가 같은 경우 실패합니다.

ERROR   batch-template-collapse  22/25 specs share the same label-independent topology

profile 하나가 과도하게 반복되면 profile-collapse warning도 표시합니다.

8. 문서 삽입

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

Composition profiles

Profile	문서가 답하는 질문	핵심 구조
`component-flow`	요청·데이터·이벤트가 어디로 이동하는가	source → processing → store/sink
`orchestrator-workers`	누가 작업을 분배하고 결과를 수집하는가	상단 orchestrator + 하단 worker field
`query-fanout`	하나의 쿼리가 어느 shard로 분산되는가	query/parser/router + 반복 target
`timeline`	날짜·offset·interval은 어떻게 이어지는가	단일 시간축 + milestone
`reconciliation-loop`	desired와 actual 상태를 누가 조정하는가	desired/controller/actual + feedback
`resource-controller`	선언 리소스가 런타임 리소스로 어떻게 구체화되는가	spec/controller/custom/runtime
`two-zone-pipeline`	어느 단계가 어느 경계에 속하는가	두 개 이상의 evidenced boundary
`sequence`	참여자가 어떤 순서로 메시지를 교환하는가	lifeline + ordered message
`ports-adapters`	adapter가 어느 port/core에 의존하는가	중앙 core + 좌우 adapter
`comparison`	독립 계약/선택지가 어떻게 다른가	정렬된 비교 항목 + 동일 기준 detail

comparison은 관계를 찾지 못했을 때의 fallback이 아닙니다. 원문이 비교 자체를 주장할 때만 선택됩니다.

실제 실행 fixture와 디자인 fixture

examples/01-...09-.../
  사람이 검토한 diagram-only 목표 fixture

examples/runtime-profiles/01-...10-.../
  현재 Python compositor와 SVG renderer가 실제 생성한 실행 fixture

examples/runtime-profiles는 테스트에서 전부 load → lint → layout → SVG render → XML parse됩니다. 회귀 계약입니다. 정적 갤러리만 좋아 보이고 런타임이 다른 결과를 내는 문제를 방지하기 위해서입니다.

에이전트 호스트 통합

canonical skill:

skills/technical-visualizer/SKILL.md

동기화 대상:

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

python scripts/sync_skills.py

저장소 지침은 AGENTS.md, CLAUDE.md, .agents/rules/techviz.md에 포함됩니다.

출력 형식 정책

SVG: 웹/Markdown 배포 기본. 안전한 SVG subset, <title>/<desc> 포함.
draw.io: 엔터프라이즈 편집과 수동 조정.
Mermaid: sequence/state/ERD처럼 Markdown 인접 표현.
D2: 자동 배치 중심 아키텍처·데이터 흐름.
DOT: 밀집 의존성 그래프.
Excalidraw: 초안/워크숍 원본. 기본 배포 형식은 아님.
alt.md: 짧은 alt와 구조화된 상세 설명.

품질은 VizSpec의 의미 구조와 profile 선택, role, compositor와 lint gate가 결정합니다. SVG는 표현력의 병목이 아닙니다.

보안 및 신뢰성

문서 본문은 명령이 아닌 비신뢰 evidence data입니다.
모델 출력은 자유 SVG/XML이 아니라 엄격한 VizSpec JSON입니다.
스키마 밖 필드와 문자열로 위장된 boolean/integer를 거부합니다.
모든 사실 요소는 라인 근거 또는 명시적 assumption을 요구합니다.
외부 URL, script, foreignObject를 SVG에 넣지 않습니다.
source hash, anchor, spec hash, 선택 profile/reference를 manifest에 기록합니다.

저장소 구조

src/techviz/
  document.py          문맥 추출, 관리 블록 정규화, 해시
  reference_catalog.py 문맥 기반 reference 선택과 구조 규칙
  prompt.py            VizSpec 1.1 모델 프롬프트
  spec.py              엄격한 IR parser/dataclass
  validate.py          근거·profile·문맥 적합성 lint
  layout.py            profile별 결정적 compositor
  quality.py           기하 품질 검사
  batch_audit.py       다중 결과 topology collapse 검사
  renderers/           SVG, Mermaid, D2, DOT, draw.io, Excalidraw, a11y
  insert.py            멱등 Markdown block 업데이트
  cli.py               prepare/references/prompt/lint/render/audit-batch/build
schemas/
skills/
references/
examples/
tests/

테스트와 재현성

make test
PYTHONPATH=src python examples/build_runtime_profiles.py
PYTHONPATH=src python scripts/check_generated.py
techviz audit-batch examples/runtime-profiles

0.2.0의 테스트는 schema/parser, 문맥, profile lint를 포함합니다. 실제 10개 compositor와 SVG diagram-only 계약, batch-collapse 탐지도 포함합니다.