Mismo prompt, mismo diagrama

Prateek Rai lanzó tldraw-canvas-kit, una colección de 19 “Agent Skills” que permiten que asistentes de IA locales, como Claude Code o Cursor, controlen la aplicación de escritorio tldraw de forma offline y produzcan diagramas de ingeniería idénticos en cada ocasión. El kit funciona sin conexión a la nube ni telemetría, lo que significa que los equipos pueden mantener sus activos visuales completamente on-premises.

Por qué es importante una herramienta de diagramación local y determinista

Los equipos de ingeniería pasan horas moviendo diagramas de flujo, diagramas de clases y mapas de arquitectura entre presentaciones, sitios de documentación y herramientas de diseño. Cada paso de copiar y pegar introduce cambios sutiles: los estilos de línea cambian, los IDs se regeneran y los diseños se desajustan. Cuando un LLM regenera un diagrama, el resultado suele ser una disposición diferente, incluso si el prompt de texto no ha cambiado. Para las organizaciones que necesitan documentación lista para auditorías o artefactos de diseño reproducibles, esa variabilidad es un riesgo.

Prateek creó tldraw-canvas-kit para abordar dos puntos críticos: (1) una herramienta que se ejecuta enteramente en la máquina del usuario, y (2) la garantía de que el mismo prompt produzca el mismo diagrama. Al exponer una API HTTP local que el agente de IA puede llamar, el kit elimina la latencia de red, el riesgo de filtración de datos y la necesidad de una suscripción SaaS.

Cómo funciona el kit

  • Núcleo offline – La aplicación de escritorio tldraw ejecuta un servidor local que acepta comandos codificados en JSON. No se realizan llamadas externas y ningún dato de uso sale de la máquina.
  • Agent Skills – Cada habilidad codifica una especificación de estructura fija: cálculos de diseño, elección de plantillas (stencils) e IDs estables. Cuando un agente invoca una habilidad, recibe un conjunto determinista de instrucciones de dibujo.
  • Actualizaciones idempotentes – Si una habilidad se ejecuta sobre un diagrama existente, actualiza las formas en su lugar, elimina los elementos obsoletos y vuelve a anclar los bordes. El resultado es un lienzo que puede refrescarse sin acumular objetos duplicados.
  • Formato de archivo – Los diagramas se almacenan como archivos .tldraw simples. Debido a que la lógica de diseño reside dentro del archivo, compartir una presentación incluye automáticamente las reglas de navegación necesarias para reproducir la vista.

El kit admite trece categorías de diagramas, que van desde diagramas de secuencia y de flujo hasta diagramas ER, máquinas de estado, carriles (swimlanes), casos de uso, componentes, paquetes, despliegue, arquitectura, mapas mentales y mapas de la base de código. Los usuarios simplemente describen el diagrama deseado; la habilidad se encarga de la estructura subyacente.

Lecciones aprendidas durante el desarrollo

  1. El estilo de las flechas por defecto tiene un aspecto dibujado a mano – Incluso cuando se solicita una línea limpia, la API crea inicialmente una flecha de estilo boceto (sketch). La habilidad debe emitir un comando de seguimiento para cambiar el estilo.
  2. Las flechas pueden intersecar formas silenciosamente – La API no genera errores si un conector pasa a través de un nodo. Se requiere una inspección visual de las capturas de pantalla generadas para detectar tales colisiones.
  3. El ajuste de texto de las etiquetas de los bordes falla en flechas cortas – Las etiquetas pueden ajustarse mal si el conector es demasiado corto, por lo que la habilidad debe imponer una longitud mínima o ajustar la ubicación de la etiqueta.

Estas peculiaridades ilustran por qué las habilidades se construyeron basándose en el comportamiento real de la API en lugar de en suposiciones sobre ella.

Instalación y uso del kit

npx skills add prateek11rai/tldraw-canvas-kit

El comando funciona en macOS y Linux. Después de la instalación, un agente de IA en la misma estación de trabajo puede consultar documentos locales, generar código y enviar comandos de dibujo al servidor tldraw en ejecución. El resultado es un diagrama reproducible que se puede editar más a fondo o exportar a presentaciones sin salir nunca del host.

Quién se beneficia y cuáles son las contrapartidas

  • Equipos centrados en la seguridad – Las empresas con políticas estrictas de manejo de datos pueden mantener todos los artefactos de diseño detrás de sus firewalls.
  • Ingenieros de documentación – Aquellos que necesitan incrustar diagramas en repositorios con control de versiones obtienen una fuente de verdad determinista.
  • Colaboradores individuales – Los desarrolladores cansados de ajustar manualmente los diseños después de cada ejecución de un LLM pueden automatizar el proceso.

La principal limitación es la dependencia de una instancia de tldraw ejecutándose localmente. Las organizaciones que ya dependen de servicios de diagramación basados en la nube deberán adoptar la aplicación de escritorio y ajustar sus flujos de trabajo. Además, el conjunto de habilidades actual no cubre librerías de plantillas (stencils) personalizadas; los usuarios deben trabajar con las formas predefinidas.

Qué sigue

Prateek planea expandir la biblioteca de habilidades basándose en los comentarios de la comunidad y añadir soporte para Windows, ampliando así la base potencial de usuarios. También espera ver a agentes de terceros integrando el kit, creando un mercado de generadores de diagramas especializados que compartan todos el mismo núcleo determinista.

Conclusión

tldraw-canvas-kit demuestra que la creación de diagramas impulsada por IA no tiene por qué ser un proceso probabilístico y exclusivo de la nube. Al anclar la lógica de dibujo en una API local y aplicar identificadores estables, permite a los ingenieros generar visuales repetibles y listos para auditorías sin sacrificar la privacidad ni el control.