donghyeon.kang/technical-visualization-haness
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

설계 개편

Browse Source
This commit is contained in:
DongHyeonka
2026-07-24 16:31:12 +09:00
parent f43e909162
commit 8daa568746
70 changed files with 6554 additions and 956 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+189 -183
View File
@@ -1,59 +1,61 @@
# TechViz Harness
# TechViz Harness 0.2.0
기존 기술문서의 앞뒤 문맥을 읽고, 문서에 근거한 기술 시각화를 생성하는 에이전트 하네스입니다. Codex, Claude Code, Antigravity가 같은 **Agent Skill + CLI + VizSpec IR**을 사용하도록 구성되어 있습니다.
기존 Markdown/MDX 기술문서의 앞뒤 문맥을 읽고, 문서에 근거한 **diagram-only 기술 시각화**를 생성하는 에이전트 하네스입니다. Codex, Claude Code, Antigravity가 같은 Agent Skill, CLI, VizSpec IR을 사용합니다.
![생성 예시](examples/assets/payment-request.svg)
![실제 런타임 생성 예시](examples/assets/payment-request.svg)
## 핵심 설계
## 0.2.0에서 해결한 문제
직접 SVG나 draw.io XML부터 생성하지 않습니다. 다음 컴파일 파이프라인을 사용합니다.
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·워터마크를 생성하지 않습니다.
## 파이프라인
```text
Markdown/MDX 문서
↓ prepare: 현재 섹션 + 앞/뒤 형제 섹션 + 라인 번호 + 문서 해시
Markdown / MDX
│
├─ techviz prepare
│ 현재 섹션 + 앞/뒤 섹션 + canonical line + SHA-256
│ + 문맥 기반 reference 후보
▼
Context Package
↓ Codex / Claude / Antigravity: 의도·대상 독자·그림 유형 선택
Grounded VizSpec JSON
↓ lint: 사실 근거·복잡도·방향·레이블·접근성·신선도 검사
Deterministic Renderers
├─ SVG 배포 기본
├─ draw.io 엔터프라이즈 편집/클라우드 스텐실
├─ Mermaid Markdown 인접 다이어그램
├─ D2 자동 배치 아키텍처/데이터 흐름
├─ Graphviz DOT 밀집 의존성 그래프
├─ Excalidraw 개념 스케치/워크숍
└─ alt.md 대체 텍스트와 구조화된 상세 설명
↓ insert
관리되는 문서 블록 + manifest
│
├─ 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
```
### 왜 중간 표현이 필요한가
그림 도구 문법과 기술적 의미를 한 단계에서 생성하면 다음 문제가 생깁니다.
- 보기 좋은 도형이 원문에 없는 관계를 사실처럼 표현한다.
- Mermaid, draw.io, SVG마다 같은 의미가 서로 다르게 드리프트한다.
- PR에서 시각 결과만 보고 “왜 이 노드와 화살표가 존재하는지” 검토하기 어렵다.
- 에이전트나 도구를 교체할 때 작성 규칙을 다시 구현해야 한다.
`VizSpec`은 모든 노드·엣지·경계에 원문 라인 범위 또는 명시적 가정을 기록합니다. 모델 JSON은 렌더링 전에 엄격한 필드·타입 검사를 거치며, 알 수 없는 필드나 문자열로 위장된 불리언 같은 암묵적 형변환을 허용하지 않습니다. 의미 검토를 통과한 하나의 IR에서 여러 형식을 결정적으로 생성합니다.
## 조사에서 반영한 공통 원칙
대형 클라우드/IT 기술문서와 공식 다이어그램 지침에서 반복되는 패턴을 하네스 정책으로 고정했습니다.
1. **메시지·독자·수명주기에 맞는 그림 유형을 선택한다.** 컨텍스트, 컨테이너/컴포넌트, 배포, 데이터 흐름, 시퀀스, 네트워크 등을 한 그림에 섞지 않습니다.
2. **편집 가능한 원본과 배포 산출물을 함께 보존한다.** SVG를 기본 배포물로 두고 draw.io/Mermaid/D2/DOT/Excalidraw 중 목적에 맞는 원본을 버전 관리합니다.
3. **방향, 레이블, 범례, 경계를 명시한다.** 양방향 화살표를 피하고 노드는 명사, 엣지는 동사·프로토콜·이벤트·데이터로 표기합니다.
4. **점진적 공개를 사용한다.** 하나의 거대한 그림 대신 개요에서 세부 뷰로 내려갑니다.
5. **공식 서비스 아이콘은 정확한 제품을 표현할 때만 사용한다.** 일반 개념은 일반 도형으로 유지하고, 아이콘만으로 제품명을 대체하지 않습니다.
6. **접근성과 버전 관리를 설계에 포함한다.** 색상만으로 의미를 구분하지 않고, SVG `<title>/<desc>`, 짧은 alt, 상세 설명, 문서 해시, manifest를 함께 생성합니다.
상세 근거와 도구 비교는 [`references/research-notes.md`](references/research-notes.md), [`references/source-catalog.md`](references/source-catalog.md), [`references/visual-principles.md`](references/visual-principles.md), [`references/format-selection.md`](references/format-selection.md)에 정리되어 있습니다.
## 설치
Python 3.11 이상만 필요합니다. 기본 SVG와 편집 원본 생성에는 외부 패키지가 없습니다.
Python 3.11 이상이 필요합니다. 기본 SVG와 편집 원본 생성에는 외부 Python 의존성이 없습니다.
```bash
python -m venv .venv
@@ -62,29 +64,27 @@ 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 변환
하네스 자체는 해당 실행 파일이 없어도 각 편집 소스를 생성합니다.
- `dot`: Graphviz 출력 렌더링
- `d2`: D2 출력 렌더링
- `mmdc`: Mermaid 출력 렌더링
- diagrams.net CLI: draw.io 변환
## 빠른 실행
### 1. 문서에 생성 위치 표시
### 1. 문서에 생성 지점 표시
```markdown
## 결제 요청 경로
클라이언트는 HTTPS로 인증 게이트웨이에 결제 요청을 보낸다.
...
인증 게이트웨이는 요청을 검증한 뒤 체크아웃 API로 전달한다.
<!-- techviz:generate id=payment-request -->
```
### 2. 앞뒤 문맥 추출
### 2. 문맥 준비
```bash
techviz prepare docs/checkout.md \
@@ -92,68 +92,90 @@ techviz prepare docs/checkout.md \
-o .techviz/payment-request/context.json
```
`prepare`는 현재 섹션과 앞/뒤 형제 섹션을 추출합니다. 이미 생성된 TechViz 블록은 원래 마커 한 줄로 축약한 정규화 뷰에서 해시와 라인 번호를 계산하므로, 재실행 시 이전 그림이 모델 문맥을 오염시키지 않습니다.
`context.json`에는 문서 해시, canonical line range, 현재/인접 섹션과 함께 `visual_reference_candidates`가 기록됩니다. 이미 생성된 관리 블록은 원래 marker 한 줄로 축약되므로 이전 그림이 다음 모델 입력을 오염시키지 않습니다.
### 3. 에이전트가 VizSpec 생성
### 3. 선택된 reference 확인
```bash
techviz references .techviz/payment-request/context.json
```
출력 예:
```text
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. 모델 프롬프트 생성
```bash
techviz prompt .techviz/payment-request/context.json \
-o .techviz/payment-request/prompt.md
```
Codex, Claude 또는 Antigravity가 이 프롬프트/스킬을 이용해 `spec.json`을 작성합니다. 중요한 계약은 다음과 같습니다.
모델은 프롬프트 전체를 사용해 `.techviz/payment-request/spec.json`을 작성합니다. 스키마만 보고 직접 작성하지 않습니다.
VizSpec 1.1의 핵심 블록:
```json
{
"version": "1.1",
"composition": {
"profile": "component-flow",
"diagram_only": true,
"reference_ids": ["payment-event-flow"],
"rationale": "요청·저장·승인·이벤트가 하나의 방향성 있는 경로를 이룬다.",
"focus_node": "checkout-api"
}
}
```
모든 사실 노드·엣지·경계는 원문 라인 근거를 가집니다.
```json
{
"id": "checkout-api",
"label": "체크아웃 API",
"kind": "service",
"evidence": [
{"start_line": 11, "end_line": 13}
],
"role": "service",
"shape": "box",
"evidence": [{"start_line": 11, "end_line": 13}],
"assumption": false
}
```
경계 역시 사실 주장이므로 같은 계약을 적용합니다. `assumption: true`인 요소는 근거 배열이 비어 있어야 하며, 근거와 가정을 한 요소에 동시에 표시하면 린트 오류입니다.
```json
{
"id": "private-network",
"label": "Private network",
"kind": "network",
"evidence": [
{"start_line": 30, "end_line": 31}
],
"assumption": false
}
```
### 4. 품질 게이트
### 5. lint
```bash
techviz lint .techviz/payment-request/spec.json \
--context .techviz/payment-request/context.json
```
검사 항목:
주요 hard gate:
- 중복/잘못된 ID와 끊어진 참조
- 근거가 없는 노드·엣지·경계
- 문서 범위를 벗어난 근거 라인
- 문서 해시 불일치와 오래된 스펙
- 비어 있는 핵심 레이블
- 레이블 과장, 무레이블 엣지, 자기 루프
- 시퀀스 순서 누락
- 엣지가 다른 노드를 관통하는 배치
- 엣지 교차·장거리 중첩과 문서 폭에 맞지 않는 캔버스
- 12개 노드/18개 엣지를 넘는 복잡도
- alt/상세 설명 누락 또는 중복
- 미승인 가정
- 근거 없는 사실 요소
- 문서 해시·anchor 불일치
- 문맥에서 선택되지 않은 profile/reference
- 두 개 이상 노드인데 중심 관계가 없는 카드 묶음
- 중심 관계에 참여하지 않는 노드가 20%를 초과
- profile 필수 역할 누락
- sequence order 누락/중복
- timeline position 누락/중복
- comparison detail 누락
- source gap
- 끊어진 참조, 재귀 그룹, 잘못된 타입
- 엣지의 무관 노드 관통과 기하 충돌
`lint`는 명시적 가정을 경고로 보여 주어 반복 작업은 허용하지만, `render`, `build`, `insert`는 기본적으로 가정이 하나라도 있으면 게시를 차단합니다. 문서 작성자가 검토·승인한 경우에만 `--allow-assumptions`를 사용하며, 그 결정과 가정 개수는 manifest에 기록됩니다.
`assumption: true`는 lint warning이지만 `render`, `build`, `insert` 단계에서는 기본적으로 게시를 차단합니다.
### 5. 다중 형식 컴파일
### 6. 렌더링
```bash
techviz render .techviz/payment-request/spec.json \
@@ -162,16 +184,23 @@ techviz render .techviz/payment-request/spec.json \
-o docs/assets/payment-request
```
### 6. 문서 업데이트
SVG에는 다이어그램 해독에 필요한 노드·경계·연결선·상태/시간 주석만 표시됩니다. `title`, `question`, `summary`는 접근성/문서 메타데이터이며 캔버스 헤드라인으로 렌더링되지 않습니다.
### 7. 여러 그림을 한 번에 생성했을 때 batch audit
```bash
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 audit-batch .techviz --pattern "**/spec.json"
```
또는 한 번에 실행합니다.
`audit-batch`는 레이블과 id를 제거한 topology fingerprint를 계산합니다. 25개 그림의 이름만 달라지고 구조가 같은 경우 다음과 같이 실패합니다.
```text
ERROR batch-template-collapse 22/25 specs share the same label-independent topology
```
profile 하나가 과도하게 반복되면 `profile-collapse` warning도 표시합니다.
### 8. 문서 삽입
```bash
techviz build .techviz/payment-request/spec.json \
@@ -180,129 +209,106 @@ techviz build .techviz/payment-request/spec.json \
--document docs/checkout.md
```
생성 블록에는 SVG, 상세 설명, 편집 원본, VizSpec 링크와 컨텍스트 해시가 들어가며 같은 ID로 재실행하면 안전하게 교체됩니다.
## Composition profiles
## 그림 유형 선택
| 문서가 답해야 하는 질문 | 기본 유형 | 권장 편집 소스 |
| Profile | 문서가 답하는 질문 | 핵심 구조 |
|---|---|---|
| 시스템 안/밖과 상호작용 주체는 누구인가? | 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 |
| `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이 아닙니다. 원문이 비교 자체를 주장할 때만 선택됩니다.
### SVG를 배포 기본으로 사용하는 이유
## 실제 실행 fixture와 디자인 fixture
- 확대해도 깨지지 않고 텍스트 검색이 가능하다.
- Markdown/웹 문서에 직접 포함하기 쉽다.
- `<title>`, `<desc>`, 메타데이터를 포함할 수 있다.
- XML 텍스트이므로 저장소에서 변경을 추적할 수 있다.
```text
examples/01-...09-.../
사람이 검토한 diagram-only 목표 fixture
생성 SVG는 스크립트, 외부 참조, `foreignObject`를 사용하지 않습니다. 외부 도구가 내보낸 임의 SVG를 그대로 신뢰하는 대신 하네스 렌더러가 안전한 하위 집합을 생성합니다.
examples/runtime-profiles/01-...10-.../
현재 Python compositor와 SVG renderer가 실제 생성한 실행 fixture
```
### draw.io를 아키텍처 편집 기본으로 사용하는 이유
AWS, Azure, Google Cloud, IBM, Oracle 등 공급자 스텐실을 활용하는 엔터프라이즈 아키텍처 전달에 익숙하고, 수동 연결선/경계 조정이 쉽습니다. 배포 SVG와 별도로 `.drawio` 원본을 보존해 편집 의미가 사라지지 않게 합니다.
### Mermaid/D2/DOT/Excalidraw의 역할
- Mermaid: 저장소 Markdown과 가까운 소형 다이어그램, 특히 sequence/state/ERD.
- D2: 자동 배치가 중요한 데이터 흐름과 아키텍처.
- DOT: 밀집 그래프의 레이아웃 최적화.
- Excalidraw: 초안·워크숍·개념 설명. 정밀 최종 아키텍처의 기본값은 아닙니다.
`examples/runtime-profiles`는 테스트에서 전부 load → lint → layout → SVG render → XML parse됩니다. 정적 갤러리만 좋아 보이고 런타임이 다른 결과를 내는 문제를 방지하기 위한 회귀 계약입니다.
## 에이전트 호스트 통합
하나의 canonical skill을 세 위치로 동기화합니다.
canonical skill:
```text
skills/technical-visualizer/SKILL.md canonical
.agents/skills/technical-visualizer/SKILL.md Codex + Antigravity
.claude/skills/technical-visualizer/SKILL.md Claude Code
skills/technical-visualizer/SKILL.md
```
동기화 대상:
```text
.agents/skills/technical-visualizer/ Codex + Antigravity
.claude/skills/technical-visualizer/ Claude Code
```
```bash
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`를 사용합니다.
저장소 지침은 `AGENTS.md`, `CLAUDE.md`, `.agents/rules/techviz.md`에 포함됩니다.
에이전트별 프롬프트를 세 벌 유지하지 않고, 결정적 작업은 CLI에 두고 의미 판단만 모델에 맡깁니다.
## 출력 형식 정책
## 보안 모델
- **SVG:** 웹/Markdown 배포 기본. 안전한 SVG subset, `<title>/<desc>` 포함.
- **draw.io:** 엔터프라이즈 편집과 수동 조정.
- **Mermaid:** sequence/state/ERD처럼 Markdown 인접 표현.
- **D2:** 자동 배치 중심 아키텍처·데이터 흐름.
- **DOT:** 밀집 의존성 그래프.
- **Excalidraw:** 초안/워크숍 원본. 기본 배포 형식은 아님.
- **alt.md:** 짧은 alt와 구조화된 상세 설명.
문서 기반 에이전트는 본문 안의 프롬프트 인젝션에 노출됩니다. 하네스는 다음 경계를 둡니다.
SVG는 표현력의 병목이 아닙니다. 품질을 결정하는 것은 VizSpec의 의미 구조, profile 선택, role, compositor와 lint gate입니다.
- 문서 내용은 명령이 아니라 비신뢰 증거 데이터로 선언한다.
- 모델 출력은 자유 형식 SVG/XML이 아니라 제한된 VizSpec JSON이며, 스키마 밖 필드와 잘못된 타입을 거부한다.
- 사실 요소는 라인 근거를 요구한다.
- 렌더러가 안전한 SVG 하위 집합을 생성한다.
- 외부 URL, 스크립트, 임베디드 HTML을 SVG에 넣지 않는다.
- 렌더와 문서 삽입 전에 스펙을 린트하고, 미승인 가정은 게시 단계에서 차단한다.
## 보안 및 신뢰성
프로덕션 적용 시 CI에서 `techviz lint`와 생성 파일 재현성 검사를 필수 체크로 두는 것을 권장합니다. 승인된 가정을 게시해야 하는 예외 경로는 `--allow-assumptions` 사용 여부와 manifest diff가 코드 리뷰에 남도록 구성합니다.
- 문서 본문은 명령이 아닌 비신뢰 evidence data입니다.
- 모델 출력은 자유 SVG/XML이 아니라 엄격한 VizSpec JSON입니다.
- 스키마 밖 필드와 문자열로 위장된 boolean/integer를 거부합니다.
- 모든 사실 요소는 라인 근거 또는 명시적 assumption을 요구합니다.
- 외부 URL, script, `foreignObject`를 SVG에 넣지 않습니다.
- source hash, anchor, spec hash, 선택 profile/reference를 manifest에 기록합니다.
## 저장소 구조
```text
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
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/
vizspec.schema.json
skills/
technical-visualizer/SKILL.md
references/
visual-principles.md
format-selection.md
diagram-types.md
research-notes.md
examples/
tests/
```
## 테스트
## 테스트와 재현성
```bash
make test
PYTHONPATH=src python examples/build_runtime_profiles.py
PYTHONPATH=src python scripts/check_generated.py
techviz audit-batch examples/runtime-profiles
```
예제를 다시 생성합니다.
```bash
make example
```
## 현재 범위와 다음 확장
이 프로토타입은 Markdown/MDX 문서와 일반적인 노드-엣지 기술 다이어그램을 우선합니다. 다음 확장은 구조적으로 열려 있습니다.
- AsciiDoc, reStructuredText, Docusaurus/MkDocs AST 어댑터
- Structurizr DSL/C4 다중 뷰 백엔드
- PlantUML/Kroki 백엔드
- 공급자 공식 아이콘 레지스트리와 라이선스 메타데이터
- SVG 텍스트 실제 치수 측정과 자동 줄바꿈 개선
- 교차선·엣지-노드 충돌을 가중한 품질 점수와 자동 재배치
- 시퀀스/ERD/배포 전용 SVG 레이아웃
- 문서 diff 기반 선택적 재생성
- PR 코멘트 리포터와 SVG 시각 diff
- 사람 승인 워크플로와 가정 해소 상태
중요한 확장 원칙은 동일합니다. **문서 사실 → 검토 가능한 의미 모델 → 결정적 렌더링** 순서를 유지합니다.
0.2.0의 테스트는 schema/parser, 문맥, profile lint, 실제 10개 compositor, SVG diagram-only 계약, batch-collapse 탐지를 포함합니다.