init: technical-visualization-haness 하네스 설계
This commit is contained in:
DongHyeonka
@@ -0,0 +1,41 @@
|
||||
# Diagram-type decision guide
|
||||
|
||||
## Context
|
||||
|
||||
Shows the system of interest, external people/systems, and directional interactions. It deliberately hides internal implementation. Use for onboarding, scope, and ownership discussions.
|
||||
|
||||
## Architecture / container / component
|
||||
|
||||
Shows stable responsibilities and dependencies at exactly one abstraction level. Use “container” for independently deployable/runnable units and “component” for meaningful internal modules only when the prose supports that distinction.
|
||||
|
||||
## Deployment / network
|
||||
|
||||
Shows runtime placement, regions/zones, compute nodes, network/trust boundaries, and deployment mappings. Do not add infrastructure inferred from common practice.
|
||||
|
||||
## Data flow
|
||||
|
||||
Shows sources, transformations, stores, sinks, and sensitive-boundary crossings. Label edges with data, events, or protocols. Separate control flow when it would obscure data movement.
|
||||
|
||||
## Sequence
|
||||
|
||||
Shows one scenario in chronological order. Every edge needs an explicit order. Use separate diagrams for success and materially different failure paths.
|
||||
|
||||
## Flow
|
||||
|
||||
Shows procedural steps and decisions. Decision labels should be questions; outgoing edges should state conditions. Avoid using a flowchart for static architecture.
|
||||
|
||||
## State
|
||||
|
||||
Shows valid states, triggering events, and transition constraints. Nodes are states, not actions.
|
||||
|
||||
## ERD
|
||||
|
||||
Shows entities and cardinality. Do not infer keys or cardinality from naming conventions.
|
||||
|
||||
## Dependency
|
||||
|
||||
Shows structural dependencies where graph topology is the primary message. Use Graphviz-style layout and filter low-value transitive or generated dependencies.
|
||||
|
||||
## Concept
|
||||
|
||||
Explains a mental model, trade-off, or mechanism without claiming implementation topology. Use generic shapes and label it clearly as conceptual.
|
||||
@@ -0,0 +1,30 @@
|
||||
# Format and tool selection
|
||||
|
||||
The harness separates **semantic source**, **editable source**, and **publication artifact**.
|
||||
|
||||
| Format | Best use | Strengths | Failure mode / constraint |
|
||||
|---|---|---|---|
|
||||
| VizSpec JSON | Canonical meaning and evidence | Tool-neutral, lintable, traceable, deterministic | Not intended for manual presentation |
|
||||
| SVG | Default publication in web/Markdown/docs | Scalable, searchable, accessible metadata, text diff | Keep scripts, external references, and `foreignObject` out |
|
||||
| draw.io / diagrams.net | Enterprise architecture and official cloud stencils | Familiar manual editing, strong connector semantics, broad vendor libraries | Plain exported SVG loses editing semantics unless diagram data/source is preserved |
|
||||
| Mermaid | Sequence, state, ERD, compact flow near Markdown | Small textual source, GitHub/GitLab rendering, easy review | Layout control and accessibility vary by renderer/version |
|
||||
| D2 | Auto-laid-out architecture and data flow | Concise source, SVG-first output, good layout defaults | Requires D2 for native rendering beyond generated source |
|
||||
| Graphviz DOT | Dense dependency and relationship graphs | Mature graph layout and crossing reduction | Less suitable for manual architecture storytelling |
|
||||
| Excalidraw | Concept sketch, workshop, informal explanation | Fast visual ideation and approachable editing | Hand-drawn semantics can imply lower precision; JSON diffs are noisy |
|
||||
| Structurizr DSL / C4 | Multiple architecture views from one model | One model can generate context/container/component/deployment views | Introduce when the repository needs a durable multi-view architecture model |
|
||||
| PlantUML/Kroki | Broad diagrams-as-code ecosystems | Many diagram families and server rendering | Server/runtime dependency and syntax-specific portability |
|
||||
| PNG | Compatibility fallback | Universal display | Raster, weak accessibility, poor scaling; never the only source |
|
||||
| PDF | Print and controlled distribution | Stable pagination and vector output | Weak as an editable or repository-native source |
|
||||
|
||||
## Default policy
|
||||
|
||||
1. Always preserve VizSpec JSON.
|
||||
2. Always publish SVG unless the target platform forbids it.
|
||||
3. Preserve one editable source selected by intent:
|
||||
- architecture/deployment/network → draw.io;
|
||||
- sequence/state/ERD/compact flow → Mermaid;
|
||||
- data-flow/auto-layout architecture → D2;
|
||||
- dense dependency → DOT;
|
||||
- conceptual workshop visual → Excalidraw.
|
||||
4. Generate PNG or PDF only as downstream delivery formats.
|
||||
5. Use official provider icon packs only for explicitly named services; keep the provider's product label visible.
|
||||
@@ -0,0 +1,46 @@
|
||||
# Research synthesis: enterprise technical-document diagrams
|
||||
|
||||
## Observed enterprise practice
|
||||
|
||||
- AWS publishes official architecture icons and explicitly supports common drawing tools including diagrams.net/draw.io and Figma. Its guidance frames diagrams as communication of design, deployment, and topology.
|
||||
- Microsoft Azure's Well-Architected guidance emphasizes selecting and layering diagram types by message, audience, and lifecycle; directional arrows; clear labels; consistency; legends; accessibility; progressive disclosure; and version-controlled source files. Azure also distributes official SVG architecture icons and asks authors to keep product names with icons and avoid distortion.
|
||||
- Google Cloud distributes official product icons in SVG and PNG for architecture diagrams and documentation.
|
||||
- IBM Cloud identifies draw.io as an approved design tool and also publishes SVG and presentation assets.
|
||||
- Oracle Cloud publishes architecture toolkits for draw.io, Visio, and PowerPoint and exposes editable DRAWIO plus SVG versions for reference architectures.
|
||||
- GitHub renders Mermaid in Markdown and supports additional structured visual formats. GitLab supports Mermaid, PlantUML, Kroki, and diagrams.net content in documentation/wiki workflows.
|
||||
|
||||
The shared pattern is not a single winning authoring format. It is a **source-preserving pipeline**: official semantics/iconography, editable source, and a stable publication artifact.
|
||||
|
||||
## Why the harness uses an intermediate representation
|
||||
|
||||
Direct generation into draw.io XML, Mermaid, or SVG couples semantic reasoning to tool syntax and makes factual review difficult. VizSpec creates a review boundary:
|
||||
|
||||
1. document context and evidence;
|
||||
2. semantic intent and relationships;
|
||||
3. deterministic layout/rendering;
|
||||
4. visual and accessibility quality gates.
|
||||
|
||||
This supports multiple agent hosts and multiple output ecosystems without allowing format-specific details to become undocumented facts.
|
||||
|
||||
## Relevant research principles
|
||||
|
||||
- The “Physics of Notations” framework argues that cognitively effective visual notations require semantic clarity, perceptual discriminability, semantic transparency, manageable visual complexity, cognitive integration, and related principles.
|
||||
- Multimedia-learning research supports coherence (remove irrelevant material), signaling (make organization and essentials visible), and spatial contiguity (place words near the graphics they explain).
|
||||
- Graph-drawing research repeatedly treats crossings, bends, edge length, and layout regularity as major readability variables.
|
||||
- W3C accessibility guidance requires text alternatives for non-text content and sufficient contrast for meaningful non-text visual information. Complex diagrams need structured descriptions beyond a short alt phrase.
|
||||
|
||||
## Source set used for the design
|
||||
|
||||
Primary vendor/documentation sources reviewed:
|
||||
|
||||
- AWS Architecture Icons and Architecture Center
|
||||
- Microsoft Azure Well-Architected Framework: Architecture design diagrams; Azure Architecture Icons
|
||||
- Google Cloud Architecture Center and Cloud icon library
|
||||
- IBM Cloud design resources
|
||||
- Oracle Cloud Infrastructure architecture diagram toolkits and reference architectures
|
||||
- GitHub Docs: Creating diagrams in Markdown
|
||||
- GitLab Docs: Mermaid, PlantUML, Kroki, and diagrams.net integrations
|
||||
- Mermaid, D2, Graphviz, Structurizr/C4, diagrams.net, and Excalidraw official documentation
|
||||
- W3C Web Content Accessibility Guidelines and WAI complex-images guidance
|
||||
|
||||
The executable policy in this repository is intentionally stricter than any single source: it combines evidence grounding, accessible output, source preservation, and agent-host portability.
|
||||
@@ -0,0 +1,68 @@
|
||||
# Source catalog
|
||||
|
||||
Reviewed on **2026-07-23**. This catalog favors first-party vendor documentation, official project documentation, standards, and primary research.
|
||||
|
||||
## Enterprise documentation and architecture-diagram practice
|
||||
|
||||
| Source | What was extracted for the harness |
|
||||
|---|---|
|
||||
| [Microsoft Azure Well-Architected Framework — Create architecture design diagrams](https://learn.microsoft.com/en-us/azure/well-architected/architect-role/design-diagrams) | Choose a diagram type for the message and audience; use progressive disclosure, explicit directional arrows, clear labels, consistent notation, accessibility, and version-controlled source. |
|
||||
| [AWS Architecture Icons](https://aws.amazon.com/architecture/icons/) | Architecture diagrams communicate design, deployment, and topology; use current official product icons and keep iconography simple. |
|
||||
| [AWS Reference Architecture Diagrams](https://aws.amazon.com/architecture/reference-architecture-diagrams/) | Reference diagrams pair the visual with numbered explanatory flow and, in many cases, an editable source package. |
|
||||
| [Google Cloud icon library](https://cloud.google.com/icons) | Official product and category icons are distributed as SVG and PNG assets. |
|
||||
| [IBM Cloud — Documenting your environment architecture](https://cloud.ibm.com/docs/openshift?topic=openshift-document-environment) | IBM explicitly lists multiple valid authoring tools, including IBM design tools, draw.io, Mural, Mermaid, presentation tools, and vector editors. |
|
||||
| [Oracle Cloud Infrastructure Architecture Diagram Toolkits](https://docs.oracle.com/en-us/iaas/Content/General/Reference/graphicsfordiagrams.htm) | OCI distributes toolkits in PowerPoint, draw.io, and Visio, with service icons, templates, examples, and guidance. |
|
||||
| [GitHub Docs — Creating diagrams](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams) | Mermaid can live directly in Markdown and is suitable for repository-adjacent, text-reviewed diagrams. |
|
||||
| [GitLab Flavored Markdown — Diagrams and flowcharts](https://docs.gitlab.com/user/markdown/#diagrams-and-flowcharts) | GitLab supports Mermaid, PlantUML, Kroki, and diagrams.net editing in wiki workflows, demonstrating a heterogeneous diagram toolchain. |
|
||||
| [Structurizr features](https://docs.structurizr.com/features) | A single architecture model can generate multiple consistent views; static SVG/PNG and code-oriented exports can coexist. |
|
||||
|
||||
## Diagram formats and rendering ecosystems
|
||||
|
||||
| Source | Relevant capability |
|
||||
|---|---|
|
||||
| [SVG 2 specification](https://www.w3.org/TR/SVG2/) | Vector publication format with text, structure, and accessibility hooks. |
|
||||
| [Mermaid documentation](https://mermaid.ai/open-source/intro/) | Text-based flow, sequence, state, ERD, and other diagram families. |
|
||||
| [D2 documentation](https://d2lang.com/) | Text-to-diagram workflow with automatic layout and SVG/PNG/PDF export. |
|
||||
| [Graphviz documentation](https://graphviz.org/documentation/) | Mature graph layout for dependency and dense relationship graphs. |
|
||||
| [diagrams.net documentation](https://www.drawio.com/doc/) | Broad stencil ecosystem and manual enterprise diagram editing. |
|
||||
| [Excalidraw developer documentation](https://docs.excalidraw.com/) | Editable JSON scene model and informal whiteboard-style visual language. |
|
||||
| [Structurizr — Why “as code”?](https://docs.structurizr.com/as-code) | Version-controlled C4 models, multiple abstraction levels, and renderer-independent architecture semantics. |
|
||||
|
||||
## Agent-host packaging
|
||||
|
||||
| Source | Harness implication |
|
||||
|---|---|
|
||||
| [OpenAI Codex — Build skills](https://developers.openai.com/codex/build-skills) | Repository skills live under `.agents/skills`; package the repeatable workflow as a focused `SKILL.md` bundle and keep deterministic implementation in scripts/CLI. |
|
||||
| [Claude Code — Extend Claude with skills](https://code.claude.com/docs/en/skills) | Claude Code follows the open Agent Skills standard and loads task-specific `SKILL.md` instructions. |
|
||||
| [Claude Code — Project memory](https://code.claude.com/docs/en/memory) | Keep durable repository rules in `CLAUDE.md`; keep procedural detail in a skill. |
|
||||
| [Google Antigravity — Agent Skills](https://antigravity.google/docs/skills) | Workspace skills live at `.agents/skills/<skill>/SKILL.md` and can bundle instructions, scripts, and references. |
|
||||
| [Google Antigravity CLI best practices](https://antigravity.google/docs/cli/best-practices) | Use `AGENTS.md` or `GEMINI.md` for repository-wide rules. |
|
||||
| [AGENTS.md](https://agents.md/) | A model-neutral repository instruction file reduces host-specific duplication. |
|
||||
|
||||
## Accessibility standards
|
||||
|
||||
| Source | Harness requirement |
|
||||
|---|---|
|
||||
| [WCAG 2.2 Quick Reference — 1.1.1 Non-text Content](https://www.w3.org/WAI/WCAG22/quickref/#non-text-content) | Every diagram needs an equivalent text alternative; complex diagrams need both a short description and a longer equivalent description. |
|
||||
| [W3C WAI — Designing for Web Accessibility](https://www.w3.org/WAI/tips/designing/) | Do not use color as the only information channel; provide sufficient contrast, grouping, and media alternatives. |
|
||||
| [WCAG 2.2 — 1.4.11 Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) | Meaningful graphical objects and states require adequate contrast against adjacent colors. |
|
||||
|
||||
## Cognitive and graph-readability foundations
|
||||
|
||||
| Source | Principle applied |
|
||||
|---|---|
|
||||
| Daniel L. Moody, [“The Physics of Notations”](https://doi.org/10.1109/TSE.2009.67), IEEE Transactions on Software Engineering, 2009 | Semantic clarity, perceptual discriminability, semantic transparency, complexity management, graphic economy, dual coding, and cognitive integration. |
|
||||
| Richard E. Mayer, [*Multimedia Learning*, 3rd ed.](https://www.cambridge.org/core/books/multimedia-learning/), Cambridge University Press, 2021 | Coherence, signaling, spatial contiguity, and segmenting/progressive disclosure. |
|
||||
| Helen C. Purchase, [“Which aesthetic has the greatest effect on human understanding?”](https://doi.org/10.1007/3-540-63938-1_67), Graph Drawing, 1997 | Edge crossings, bends, and related graph aesthetics materially affect comprehension. |
|
||||
|
||||
## Synthesis used by this repository
|
||||
|
||||
The reviewed organizations do **not** converge on one authoring extension. They converge on a workflow pattern:
|
||||
|
||||
1. choose a visual abstraction for a specific reader question;
|
||||
2. use a consistent notation and current official icons where exact vendor products matter;
|
||||
3. preserve an editable source;
|
||||
4. publish a stable, accessible artifact;
|
||||
5. keep the diagram synchronized with the text and architecture lifecycle.
|
||||
|
||||
TechViz adds a stricter semantic layer before those formats: grounded VizSpec JSON with line-level evidence, deterministic compilation, and automated quality gates.
|
||||
@@ -0,0 +1,50 @@
|
||||
# Technical visualization principles
|
||||
|
||||
## 1. One dominant question
|
||||
|
||||
A diagram is not a decorated inventory. It is an answer to one reader question. Put that question in VizSpec and make the title state the takeaway. When two questions require different abstraction levels or reading orders, generate two diagrams.
|
||||
|
||||
## 2. Semantic correctness before aesthetics
|
||||
|
||||
A visually polished but undocumented relationship is misinformation. Nodes and edges therefore carry source-line evidence. The harness blocks ungrounded elements unless they are explicitly marked as assumptions.
|
||||
|
||||
## 3. Progressive disclosure
|
||||
|
||||
Use a small context or overview diagram first, then separate component, deployment, sequence, or data-flow views. Avoid a single “everything diagram.” Twelve nodes and eighteen edges are review thresholds, not goals.
|
||||
|
||||
## 4. Visual grammar
|
||||
|
||||
- Nodes are noun phrases and represent things with stable identity or responsibility.
|
||||
- Edges are directional and labeled with verbs, protocols, events, or data.
|
||||
- Boundaries represent system scope, trust, network, ownership, region, or lifecycle—not arbitrary decoration.
|
||||
- Shape differences must correspond to meaningful categories.
|
||||
- Official vendor icons represent exact named services only; generic shapes represent implementation-independent concepts.
|
||||
- Do not encode unrelated meanings with the same visual variable.
|
||||
|
||||
These rules operationalize cognitive-effectiveness principles such as semiotic clarity, perceptual discriminability, semantic transparency, visual expressiveness, graphic economy, and cognitive integration.
|
||||
|
||||
## 5. Layout
|
||||
|
||||
- Prefer left-to-right for process and data flow.
|
||||
- Prefer top-to-bottom for hierarchy and deployment.
|
||||
- Keep the main path visually straight.
|
||||
- Minimize crossings, bends, long return edges, and edge-node overlap.
|
||||
- Place labels next to the element they describe.
|
||||
- Align related nodes and use whitespace to expose grouping.
|
||||
- Use explicit arrows; avoid bidirectional arrows unless both directions truly share one semantic label.
|
||||
|
||||
## 6. Signaling and coherence
|
||||
|
||||
Remove decorative content that does not improve comprehension. Highlight the main path through placement, hierarchy, and concise labels rather than excessive color. Put explanatory labels adjacent to the relevant component or edge.
|
||||
|
||||
## 7. Accessibility
|
||||
|
||||
- The SVG contains a `<title>` and `<desc>`.
|
||||
- Markdown includes concise alt text and a separate long description for complex structure.
|
||||
- Do not rely on color alone; pair category with shape, line style, labels, or grouping.
|
||||
- Maintain at least 3:1 contrast for meaningful non-text boundaries and indicators.
|
||||
- Avoid tiny labels; review at the actual documentation width.
|
||||
|
||||
## 8. Versioning and staleness
|
||||
|
||||
Store the canonical VizSpec, source-document hash, generated outputs, and manifest in version control. Regenerate when nearby prose changes. Review source and visualization in the same pull request.
|
||||
Reference in New Issue
Block a user