# TechViz Harness

기존 기술문서의 앞뒤 문맥을 읽고, 문서에 근거한 기술 시각화를 생성하는 에이전트 하네스입니다. Codex, Claude Code, Antigravity가 같은 **Agent Skill + CLI + VizSpec IR**을 사용하도록 구성되어 있습니다.

![생성 예시](examples/assets/payment-request.svg)

## 핵심 설계

직접 SVG나 draw.io XML부터 생성하지 않습니다. 다음 컴파일 파이프라인을 사용합니다.

```text
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 기술문서와 공식 다이어그램 지침에서 반복되는 패턴을 하네스 정책으로 고정했습니다.

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와 편집 원본 생성에는 외부 패키지가 없습니다.

```bash
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. 문서에 생성 위치 표시

```markdown
## 결제 요청 경로

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

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

### 2. 앞뒤 문맥 추출

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

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

### 3. 에이전트가 VizSpec 생성

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

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

```json
{
  "id": "checkout-api",
  "label": "체크아웃 API",
  "kind": "service",
  "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. 품질 게이트

```bash
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. 다중 형식 컴파일

```bash
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. 문서 업데이트

```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
```

또는 한 번에 실행합니다.

```bash
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을 세 위치로 동기화합니다.

```text
skills/technical-visualizer/SKILL.md          canonical
.agents/skills/technical-visualizer/SKILL.md  Codex + Antigravity
.claude/skills/technical-visualizer/SKILL.md  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`를 사용합니다.

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

## 보안 모델

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

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

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

## 저장소 구조

```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
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
```

예제를 다시 생성합니다.

```bash
make example
```

## 현재 범위와 다음 확장

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

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

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