init: technical-visualization-haness 하네스 설계
This commit is contained in:
DongHyeonka
@@ -1,2 +1,308 @@
|
||||
# technical-visualization-haness
|
||||
# TechViz Harness
|
||||
|
||||
기존 기술문서의 앞뒤 문맥을 읽고, 문서에 근거한 기술 시각화를 생성하는 에이전트 하네스입니다. Codex, Claude Code, Antigravity가 같은 **Agent Skill + CLI + VizSpec IR**을 사용하도록 구성되어 있습니다.
|
||||
|
||||
|
||||
|
||||
## 핵심 설계
|
||||
|
||||
직접 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
|
||||
- 사람 승인 워크플로와 가정 해소 상태
|
||||
|
||||
중요한 확장 원칙은 동일합니다. **문서 사실 → 검토 가능한 의미 모델 → 결정적 렌더링** 순서를 유지합니다.
|
||||
|
||||
Reference in New Issue
Block a user