Si usas un agente como Claude Code, Codex o Pi, probablemente le has pedido un diagrama de arquitectura. Y probablemente el resultado tenía algo raro: dos cajas encimadas, un texto que se sale de su recuadro o una flecha que atraviesa un nodo.

El problema: el agente dibuja a mano

Cuando un agente genera un diagrama en SVG, tiene que calcular él mismo la posición de cada caja, cada flecha y cada etiqueta. Los modelos de lenguaje son buenos describiendo sistemas, pero no calculando geometría.

Lo medí: en un benchmark con Codex (8 tareas, 3 ejecuciones cada una), 20 de 24 diagramas SVG escritos a mano tenían defectos de layout. Además fueron los más caros en tokens, porque el agente escribe todo el dibujo como tokens de salida.

La idea: separar el qué del dónde

Construí trazo con una regla simple: el agente dice qué hay en el sistema; trazo decide dónde va cada cosa.

El agente escribe un JSON semántico, sin coordenadas ni estilos:

{ "type": "architecture", "title": "Orders", "nodes": [{ "id": "web", "kind": "client" }, { "id": "api" }, { "id": "db", "kind": "database" }], "edges": ["web -> api: HTTPS", "api -> db: SQL"] }

Y trazo lo convierte en un HTML interactivo:

trazo make demo.json

Diagrama generado por trazo

El HTML funciona sin servidor y sin internet: puedes mover, hacer zoom, pasar el cursor sobre un nodo para ver sus conexiones y exportar a SVG o PNG.

Los números

Mismo benchmark, tres formas de hacer el diagrama:

Opción Diagramas con defectos de layout
SVG escrito a mano por el agente 20 de 24
Mermaid 7 de 24
trazo 0 de 46

Para ser justo: Mermaid gastó entre un 35 y un 40% menos tokens que trazo y GitHub lo muestra directamente en Markdown. Si eso es lo que más te importa, Mermaid es una buena opción. trazo gana en layout, en validación y en que el mismo JSON siempre da el mismo HTML, byte por byte.

Detalles y método: bench/README.md

Qué más hace

  • Cuatro tipos de diagrama: arquitectura, flujo (con carriles), ERD (con claves foráneas a nivel de columna) y secuencia (con fragmentos alt, opt y loop).
  • Errores útiles para el agente: cada error indica la ruta exacta en el JSON y trae una pista, así el agente se corrige solo.
  • Skill para agentes: le enseña al agente a leer el código antes de dibujar y a dibujar solo lo que encontró.

Lo que no hace: solo tiene cuatro tipos (Mermaid, PlantUML y D2 cubren muchos más) y no se renderiza dentro de Markdown.

Pruébalo en tres pasos

  1. Instálalo (necesita Node.js 22 o superior): 
 npm i -g @heidenber/trazo
  1. Opcional: pídele a tu agente que instale la skill siguiendo estas instrucciones.
  2. Pídele un diagrama: > Usa trazo para dibujar la arquitectura de este proyecto. Ejecuta trazo example architecture para ver el formato, escribe el JSON, ejecuta trazo make y dime dónde quedó el archivo HTML.

Feedback

trazo es open source (Apache-2.0): https://github.com/heidenber/trazo

Me interesa saber qué tipo de diagrama te falta y cómo le va con tu agente. Los comentarios y los issues son bienvenidos.