315 lines
12 KiB
Markdown
315 lines
12 KiB
Markdown
# TechViz Harness 0.2.0
|
|
|
|
에이전트 하네스입니다. 기존 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·워터마크를 생성하지 않습니다.
|
|
|
|
## 파이프라인
|
|
|
|
```text
|
|
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 의존성이 없습니다.
|
|
|
|
```bash
|
|
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. 문서에 생성 지점 표시
|
|
|
|
```markdown
|
|
## 결제 요청 경로
|
|
|
|
클라이언트는 HTTPS로 인증 게이트웨이에 결제 요청을 보낸다.
|
|
인증 게이트웨이는 요청을 검증한 뒤 체크아웃 API로 전달한다.
|
|
|
|
<!-- techviz:generate id=payment-request -->
|
|
```
|
|
|
|
### 2. 문맥 준비
|
|
|
|
```bash
|
|
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 확인
|
|
|
|
```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
|
|
```
|
|
|
|
모델은 프롬프트 전체를 사용해 `.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",
|
|
"role": "service",
|
|
"shape": "box",
|
|
"evidence": [{"start_line": 11, "end_line": 13}],
|
|
"assumption": false
|
|
}
|
|
```
|
|
|
|
### 5. lint
|
|
|
|
```bash
|
|
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. 렌더링
|
|
|
|
```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
|
|
```
|
|
|
|
SVG에는 다이어그램 해독에 필요한 노드·경계·연결선·상태/시간 주석만 표시됩니다. `title`, `question`, `summary`는 접근성/문서 메타데이터이며 캔버스 헤드라인으로 렌더링되지 않습니다.
|
|
|
|
### 7. 여러 그림을 한 번에 생성했을 때 batch audit
|
|
|
|
```bash
|
|
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 \
|
|
--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
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
skills/technical-visualizer/SKILL.md
|
|
```
|
|
|
|
동기화 대상:
|
|
|
|
```text
|
|
.agents/skills/technical-visualizer/ Codex + Antigravity
|
|
.claude/skills/technical-visualizer/ Claude Code
|
|
```
|
|
|
|
```bash
|
|
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에 기록합니다.
|
|
|
|
## 저장소 구조
|
|
|
|
```text
|
|
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/
|
|
```
|
|
|
|
## 테스트와 재현성
|
|
|
|
```bash
|
|
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 탐지도 포함합니다.
|