convez.ai
SkillDados & AnalyticsIntermediário
LoShinYen

Agent ER Spec — Bundles de Diagrama E-R Persistentes

LoShinYen/agent_er_spec

Converta SQL/Markdown em diagramas ER persistentes com semântica de design

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill para Claude Code que converte SQL DDL ou Markdown de design em bundles ER interativos (.erd.json), preservando camadas coloridas, diagramas multi-view, fluxos de dados e logs de decisão de design. Oferece renderização interativa com drag-and-drop e zoom, superando limitações do Mermaid erDiagram para documentação de sistemas complexos.

Instalação

$npx convez-ai LoShinYen/agent_er_spec

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Documentar arquitetura de banco de dados com contexto de decisão
  • Gerar diagramas ER interativos a partir de DDL existente
  • Manter múltiplas visualizações e camadas de um mesmo modelo
  • Rastrear narrativas de fluxo de dados em sistemas complexos

Veredito

Ferramenta sólida e bem-documentada para quem precisa de diagramas ER com semântica além do Mermaid. Excelente integração com Claude Code e clara separação entre spec (JSON Schema) e implementação (Skill); adota boas práticas (CI, exemplos, validação). Recomendado para arquitetos e times que valorizam design docs estruturados.

README

A tradução para o português deste README ainda está na fila.

Agent ER spec (agent_er_spec)

English · 繁體中文

ci

A Claude Code Skill plus the spec it implements: turn SQL DDL or design Markdown into a long-lived ER design bundle (.erd.json), rendered into a draggable, zoomable interactive page.

Different from Mermaid erDiagram: this spec preserves color-coded layers, multi-view diagrams, data-flow narratives, and design-decision logs — the design semantics teams need for system docs, that Mermaid can't express.

Two ways to use it

A. As a spec / example library (raw)

Read the root files directly and produce bundles by hand or via an agent:

PathPurpose
erd-bundle.schema.jsonJSON Schema — authoritative structure for a bundle
CLAUDE.mdAuto-loaded by Claude Code in this repo: invariants + JSON→host mapping
examples/minimal.erd.jsonSmallest bundle (two tables, one edge)
examples/ecommerce.erd.json7 tables, 2 views, dataFlows + designDecisions
examples/team.erd.json0:1 / 0:N showcase for optional relationships
examples/demo.htmlSelf-contained interactive page — opens offline
sources/ecommerce.sql · sources/team.sqlDDL inputs that derive the bundles above

B. As a Claude Code Skill (recommended)

plugins/er-bundle/skills/er-bundle/ is a self-contained Skill: trigger description, schema, examples, validate + render scripts. Claude Code fires it when a user wants to produce or update an .erd.json.

By default the skill produces both the .erd.json and an interactive HTML preview (opens automatically). Tell it "JSON only" if you want to skip the preview. The Quick start CLI commands below are only needed when working with bundles outside Claude Code, or re-rendering after a manual edit.

Interactive page UX:

  • Arrow tips point at PK / referenced side (dbdiagram / UML convention) — read arrow tail → tip as "this column references that column".
  • Self-references draw as a same-side loop on the right edge of the card.
  • Multiple FKs landing on the same edge are spread out so the arrowheads don't overlap.
  • Card positions you drag are saved to localStorage scoped per bundle (no cross-bundle collisions), expire after 30 days. ↺ 重設版面 restores the current diagram; 🗑 清全部 wipes every bundle's saved positions.

Install (pick one):

  • Plugin marketplace — add .claude-plugin/marketplace.json to your Claude Code plugin marketplace.
  • User-wide — copy plugins/er-bundle/skills/er-bundle/ to ~/.claude/skills/. Fires in any project.
  • Project-local (best while hacking on the Skill itself):
    mkdir -p .claude/skills && ln -sfn ../../plugins/er-bundle/skills/er-bundle .claude/skills/er-bundle
    
    .claude/ is gitignored, so the symlink stays local; edits in plugins/er-bundle/skills/er-bundle/ reflect instantly.

Skill layout:

plugins/er-bundle/skills/er-bundle/
├── SKILL.md                  # trigger description + workflow + anti-patterns
├── references/
│   ├── schema.json           # copy of root erd-bundle.schema.json (CI diffs to catch drift)
│   └── layout-heuristics.md  # rules for picking table coordinates
├── examples/                 # minimal, ecommerce, team (JSON + SQL), demo.html
├── scripts/
│   ├── validate.py           # JSON Schema + cross-checks
│   └── render_html.py        # bundle → standalone interactive HTML
└── tests/                    # 32 unit tests covering all of the above

Spec highlights

A bundle requires meta / layers / tables / diagrams. Full surface in the schema; the commonly-missed optional fields:

  • Column-level: nullable, default, onDelete / onUpdate, enumValues
  • Table-level: tableConstraints[] — composite PK/UQ, INDEX, CHECK (use cols[*].tag for single-column constraints)
  • Connection: cardinality (1:1 / 1:N / N:N / 0:1 / 0:N), dashed (logical relation, non-physical FK). 0:* corresponds to nullable FK.
  • Optional sections: dataFlows (write paths), designDecisions (old vs new)

Quick start

# Validate (schema + cross-checks: FK endpoints, layer refs, positions coverage)
python3 plugins/er-bundle/skills/er-bundle/scripts/validate.py examples/ecommerce.erd.json

# Render to an interactive HTML page
python3 plugins/er-bundle/skills/er-bundle/scripts/render_html.py examples/ecommerce.erd.json -o /tmp/out.html
open /tmp/out.html

Both scripts need jsonschema: pip install --user jsonschema.

Tests

python3 -m unittest discover -s plugins/er-bundle/skills/er-bundle/tests

CI runs on every push / PR (Python 3.11 + 3.12) — see .github/workflows/ci.yml.

Relationship to a "full product page"

This repo only defines the data shape and a minimal interactive UI. A real product can layer additional pages on top (architecture notes, diff views) in the host project; dataFlows and designDecisions are reserved in the schema for that extension.

License

MIT

Ver o original no GitHub

Bom para

Relacionados