Diagramas UML y C4 en el desarrollo con IA guiado por specs

El desarrollo guiado por especificaciones (spec-driven development) prometía frenar a los agentes de programación con IA lo suficiente para que una persona siguiera al mando: escribir los requisitos, acordar un diseño y luego dejar que el agente construya. Funciona. También produce mucho texto. Birgitta Böckeler probó Kiro, Spec Kit y Tessl para Thoughtworks y dijo de lo que generó Spec Kit: "I'd rather review code than all these markdown files" (prefiero revisar código que todos estos archivos markdown).

Así construyo mis proyectos personales, y coincido con ella sobre el markdown. Lo que hizo más rápidas mis revisiones no fue un prompt mejor. Fue un dibujo. Cada spec de mis proyectos lleva ahora un diagrama, y el diagrama es lo primero que reviso de la spec.

Busqué quién más hace esto. Los diagramas como entrada para los agentes son una práctica emergente. Los diagramas como forma de revisar lo que construyó un agente están casi sin explorar. Este artículo trata de ambos, y del skill de diagramas que tuve que rehacer porque el oficial de AWS no funcionaba fuera de un entorno.

TL;DR

1. Los agentes escriben más rápido de lo que la gente lee. Planes, recorridos y diffs son texto, y en el texto crece la deuda de comprensión.
2. Un diagrama de ingeniería de software comprime un diseño en algo que se revisa en un minuto: una flecha equivocada se ve; una línea equivocada entre 1,284, no.
3. Elige el diagrama por el error que detecta: arquitectura o C4 para límites equivocados, secuencia para un orden de llamadas equivocado, estados para estados imposibles, un diagrama entidad-relación para desvíos en el modelo de datos.
4. Trata el diagrama como un contrato: apruébalo en la spec antes de que exista código, regenéralo desde el código después y revisa la diferencia.
5. Kiro y Cursor ya ponen diagramas en sus planes. Usarlos para revisar lo que produce el agente todavía es raro. Las herramientas existen para casi todo; lo que falta es el hábito.

El problema de la revisión

Un agente que termina una funcionalidad te entrega un plan, un recorrido y un diff. Los tres son honestos, y los tres son prosa o código. Addy Osmani llama al resultado deuda de comprensión (comprehension debt): la brecha creciente entre cuánto código existe en tu sistema y cuánto de él entiende alguien. Todas las herramientas de IA mejoran en producir el lado del código de esa brecha. Pocas trabajan en el lado de la comprensión.

Los ingenieros resolvieron una versión de este problema hace décadas. Cuando un sistema era demasiado grande para tenerlo en la cabeza, se dibujaba. La disciplina los llama modelos de software, y los diagramas son su forma visual: UML, C4, diagramas entidad-relación, vistas de despliegue. En muchos equipos pasaron de moda porque mantenerlos al día a mano era caro. Ese costo es justo lo que los agentes eliminan. Un agente redibuja un diagrama de secuencia en segundos, tantas veces como se lo pidas.

Quién ya lo hace

Busqué en artículos académicos, documentación de proveedores, Hacker News, Reddit y X a cualquiera que use diagramas para guiar o revisar agentes de programación con IA. Esto es lo que existe, a octubre de 2026.

Diagramas como entrada, en herramientas de specs:

• Kiro es la única gran herramienta de specs que pone diagramas en su salida por defecto. Su design.md documenta "technical architecture, sequence diagrams, and implementation considerations" (arquitectura técnica, diagramas de secuencia y consideraciones de implementación).
• Cursor 2.2 (diciembre de 2025) agregó diagramas Mermaid en línea al Plan Mode, así que el agente transmite visuales dentro de sus planes.
• Spec Kit de GitHub no tiene diagramas en sus plantillas. Una discusión de la comunidad, Embedding Visual Diagrams (UML / Mermaid / PlantUML) Across Spec Kit Workflows, los pidió en octubre de 2025 y no tuvo respuesta de los mantenedores.

Diagramas como entrada, en la investigación:

• Architecture as Capability Equalizer for Coding Agents (agosto de 2026) ejecutó 90 pruebas de agentes en seis modelos, cada uno con la misma arquitectura en cinco formatos, entre ellos Mermaid y C4. El formato casi no importó en los modelos más fuertes y importó mucho en los más débiles, y los formatos cercanos al código (OpenAPI, contratos en TypeScript) fueron los que más ayudaron. Más sobre esa advertencia abajo.
• Collaborative LLM Agents for C4 Software Architecture Design Automation hace que unos agentes produzcan las vistas de contexto, contenedores y componentes de un modelo C4 a partir de los requisitos.

Diagramas para entender código que ya existe:

• Code2UML (mayo de 2026) usa agentes construidos con el Claude Agent SDK para convertir repositorios en UML. Los diagramas son sintácticamente válidos en un 91.5%, pero recuperan solo el 31% de las entidades. Un diagrama que se renderiza no es un diagrama correcto.

Diagramas para revisar lo que produce el agente: aquí la lista se acorta. CodeRabbit incluye por defecto un diagrama de secuencia en el recorrido de cada pull request (su opción sequence_diagrams está activada salvo que la apagues). Antigravity de Google incluye diagramas de arquitectura entre los artefactos que producen sus agentes. En X hay consejos sueltos de pedirle a Claude un diagrama Mermaid del plan antes de dejarlo construir. Eso es casi todo. La discusión sobre la deuda de comprensión, que trata justo de entender lo que producen los agentes, no menciona los diagramas como remedio.

Así que lo que falta no son herramientas. Los agentes dibujan diagramas bastante bien, y todas las herramientas de arriba pueden mostrarlos. Lo que falta es el hábito de que el diagrama sea lo que apruebas y lo que verificas.

Qué diagrama detecta qué error

"Agrega un diagrama" es demasiado vago para ayudar. Cada tipo de diagrama de ingeniería de software responde una pregunta distinta, así que cada uno detecta una clase distinta de error del agente. Estos son los que uso.

Diagrama	Responde	El error del agente que detecta
Arquitectura (contexto y contenedores de C4, o un diagrama de nube)	Qué partes existen y quién habla con quién	Un servicio nuevo que nadie pidió, una llamada que cruza un límite, un secreto que llega al navegador
Secuencia	En qué orden pasan las cosas, incluidos los fallos	Falta de autorización, una capa de API que se salta, ningún camino de error, un bucle de reintentos
Máquina de estados	En qué estados puede estar algo y cómo pasa de uno a otro	Estados imposibles, un estado sin salida, una transición que se salta un paso
Entidad-relación (ERD)	Qué datos hay y cómo se relacionan los registros	Un campo duplicado, un dueño que falta, un uno-a-muchos que debía ser muchos-a-muchos
Despliegue	Dónde corre el código	Un binario en el paquete equivocado, una función en la región equivocada, una sorpresa de costo
Clases	Cómo está estructurado el código por dentro	Sobre todo ruido para el trabajo con agentes; casi nunca lo pido

La división académica sirve aquí: los diagramas estructurales (arquitectura, ERD, clases, despliegue) muestran lo que existe, y los de comportamiento (secuencia, estados, actividad) muestran lo que pasa. Los agentes aciertan con la estructura más a menudo que con el comportamiento, así que en los diagramas de comportamiento es donde mis revisiones encuentran más.

El diagrama como contrato

Este es el ciclo que uso, y la mitad que todavía estoy agregando.

1. Escribe la spec con el agente, incluidos los diagramas que importan para el cambio.
2. Revisa el dibujo en el PR de la spec, antes de que exista código. Una caja equivocada cuesta un comentario en lugar de una reescritura.
3. Entrega la spec aprobada al agente como sus instrucciones.
4. Déjalo implementar, código y pruebas.
5. Pídele que regenere el mismo diagrama desde el código que escribió. No desde la spec: desde el código.
6. Compara los dos. Un diagrama escrito como código (Mermaid, PlantUML, Structurizr) convierte esto en un diff literal.
7. El desvío que no fue intencional vuelve al agente.
8. Cuando coinciden, o el cambio fue intencional, haz commit del nuevo diagrama como parte de la spec, para que la spec siga describiendo el sistema tal como es.

Este es el paso 6 con un ejemplo ilustrativo. El diff del agente tiene 1,284 líneas. El diagrama de secuencia regenerado tiene una flecha que el aprobado no tiene: la interfaz escribiendo directo en la base de datos, saltándose la API. Revisar eso es trabajo de una línea; encontrarlo en el diff, no.

Los pasos 1 a 3 son como funciona hoy cada uno de mis proyectos, y el paso 8 ya es una regla: cuando cambia la arquitectura, se edita la misma fuente del diagrama en el mismo pull request. Los pasos 5 a 7 son la parte que estoy agregando ahora. Los números de recall de Code2UML son la advertencia: un diagrama regenerado puede omitir cosas, así que una coincidencia es evidencia, no prueba. Una diferencia, en cambio, siempre vale la pena leerla.

Cómo uso los diagramas en mis specs

Todos mis proyectos siguen el mismo flujo: un issue de GitHub se convierte en una spec de Kiro (requirements.md, design.md, tasks.md), la spec se fusiona con su propio pull request y solo entonces un agente la implementa. Una regla del flujo dice que el design.md de cada spec tiene una sección ## Architecture con un diagrama de los componentes que la funcionalidad agrega o cambia. El diagrama se revisa en el PR de la spec junto con los requisitos.

Uso dos formatos, para dos trabajos.

Los diagramas de arquitectura son archivos de draw.io con los íconos oficiales de AWS, hechos por un skill de agente, validados y exportados a PNG. Este es el diagrama de arquitectura de la spec de descubrimiento de un rastreador de búsqueda de empleo que estoy construyendo:

También es un ejemplo honesto del límite del formato. La spec creció a lo largo de nueve issues, y con catorce pasos las líneas se cruzan y algunas etiquetas chocan. Cuando un diagrama de arquitectura se vuelve así de denso, te está diciendo que la funcionalidad debería dividirse, o el diagrama. C4 tiene nombre para eso: acercarse un nivel.

Los diagramas de proceso son Mermaid, en línea en design.md. GitHub los muestra, se comparan línea por línea en el pull request y los agentes los escriben con soltura. Este es un diagrama de secuencia de una corrección en mi app para aprender idiomas. Cada creación y actualización en su administrador de cursos fallaba en el límite de los React Server Components, porque objetos del modelo de datos, que llevan funciones, pasaban del código del servidor al navegador. El diagrama hace imposible pasar por alto el límite del que depende la corrección:

sequenceDiagram
  participant P as courses/[courseId]/page.tsx
  participant R as reads.ts
  participant A as AppSync

  P->>R: getCourseDetail(courseId)
  R->>A: Practice.get({ id }, selectionSet)
  A-->>R: course
  R->>A: listPracticeLessonsByPractice({ practiceId })
  A-->>R: lessons (ordered, paginated)
  Note over R,A: lesson counts come from the join index,<br/>not from reading Content records
  R-->>P: CourseDetailDTO (plain object)

La última línea es toda la corrección: la página recibe un objeto plano, nunca un modelo. La nota del medio es una decisión de rendimiento que de otro modo viviría en la cabeza de un solo revisor. Ambas son cosas que en un diff solo revisaría si ya supiera que tengo que buscarlas.

Y este es el modelo de datos de un juego de estrategia, cinco líneas que un revisor lee en diez segundos:

erDiagram
  MATCH ||--|{ SEAT : has
  SEAT }o--|| COUNTRY : plays
  COUNTRY ||--o{ FACT : has
  MATCH ||--o{ EVENTAPPLIED : records
  MATCH ||--o{ MATCHRESULT : produces

En siete proyectos eso suma unos 35 diagramas de draw.io y unos 100 diagramas Mermaid, sobre todo diagramas de flujo, de secuencia, máquinas de estados y diagramas entidad-relación. Los agentes los dibujaron todos; mi parte fue revisarlos.

Por qué rehíce el skill de diagramas de AWS

Mis diagramas de arquitectura salían al principio de aws-diagram-mcp-server de AWS, un servidor MCP que dibujaba diagramas con el paquete diagrams de Python y Graphviz. Desde entonces AWS lo declaró obsoleto en favor de un skill, aws-architecture-diagram, en el plugin deploy-on-aws de awslabs/agent-plugins. El skill es una mejora real: escribe XML de draw.io con los íconos oficiales AWS4, al estilo de las arquitecturas de referencia de AWS, con pasos numerados y una leyenda, y valida los nombres de las figuras y las conexiones.

El problema era que no se podía llevar a otro entorno. Lo uso desde Claude Code en mi máquina, Claude Code en la web, Kiro y Kiro Web, y el plugin solo funciona completo en el primero:

• La validación vive en un hook de Claude Code. Un skill copiado a cualquier otro sitio no lleva hooks, así que escribe diagramas que nadie valida.
• El convertidor para Kiro descarta el hook y los scripts que llama el skill, y deja al skill apuntando a archivos que no existen.
• Los plugins declarados en un repositorio no se instalan en las sesiones en la nube de Claude Code, que solo leen el repositorio.
• Los usuarios de Kiro CLI se quedaron sin camino. Un issue que lo reportaba se abrió en abril de 2026 y un bot de inactividad lo cerró como "not planned" en octubre, sin respuesta de los mantenedores.

Así que incorporé una copia adaptada como un skill de agente simple que Kiro y Claude Code cargan sin cambios:

• El hook se convirtió en scripts/check.sh, que ejecuta el mismo posprocesamiento y la misma validación.
• La exportación se convirtió en scripts/export.sh, que instala una versión fija de draw.io desktop (verificada por SHA-256, sin sudo) y renderiza sin pantalla cuando no hay una.
• Dos correcciones pequeñas de Python permiten que los validadores se importen en versiones anteriores a la 3.14.
• Quité los diagramas de ejemplo para respetar el límite de Kiro Web de 25 archivos por skill.
• Los íconos de marca de productos que no son de AWS (Claude, GitHub, Stripe) se incrustan desde archivos SVG del repositorio, así que el diagrama se ve bien en cualquier lugar.

Una copia canónica vive en mi repositorio del flujo de trabajo, y un script de instalación la instala para cada agente. Los dos diagramas de arriba que no son Mermaid se hicieron con él.

Dónde fallan los diagramas

Los diagramas no son una ganancia gratis. Los fallos que he encontrado, y los que reporta la investigación:

• Bonito y vacío. Un agente dibuja con gusto un diagrama que se renderiza, se ve profesional y no explica nada. Pide el diagrama que responde una pregunta concreta ("¿en qué orden se llaman estas funciones cuando el token expiró?"), no "un diagrama del sistema".
• Sintaxis desactualizada. Los modelos van detrás de las versiones de Mermaid, y también los visores de algunas herramientas. Valida antes de confiar en un render, y revisa qué tipos de diagrama soporta tu visor.
• Recall bajo. Un diagrama regenerado desde el código puede dejar cosas fuera, como midió Code2UML. Trata una coincidencia como evidencia, no como prueba.
• Los diagramas no son el mejor formato para guiar a todos los modelos. El estudio del ecualizador de capacidades encontró que los formatos con forma de código, como OpenAPI y los contratos en TypeScript, guiaron mejor a los modelos más débiles que los diagramas. Mi división sale de ahí: contratos y tipos para guiar al agente, diagramas para la persona que aprueba y revisa.
• Densidad. Pasada una docena de cajas, un diagrama de arquitectura deja de leerse. Divídelo.

Lo que haré después

El skill es lo bastante general para servir fuera de mis proyectos, y la mayoría de lo que cambié resuelve problemas que otras personas ya reportaron. Voy a publicar el skill adaptado en su propio repositorio público bajo su licencia Apache-2.0, y a proponer las correcciones de portabilidad a awslabs/agent-plugins: una validación que no dependa de un hook de Claude Code, y las correcciones de importación de Python. Actualizaré este artículo cuando cualquiera de las dos salga.

La otra mitad es el paso 5 del ciclo: convertir "regenera el diagrama desde el código y compáralo" en un paso estándar del pull request de implementación, en lugar de algo que me acuerdo de pedir.

Referencias

• Böckeler, B. Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl. martinfowler.com, 15 de octubre de 2025.
• Osmani, A. Comprehension Debt. 14 de marzo de 2026.
• Canedo, A. Architecture as Capability Equalizer for Coding Agents. arXiv:2608.21747, agosto de 2026.
• Văduva, A.-G., Andreescu, A.-I., Oprea, S.-V. y Bâra, A. Code2UML: Agentic LLMs with context engineering for scalable software visualization. arXiv:2605.24453, mayo de 2026.
• Szczepanik, K. y Chudziak, J. A. Collaborative LLM Agents for C4 Software Architecture Design Automation. arXiv:2510.22787, HICSS-59, 2026.
• Kiro. Specs. Documentación de Kiro.
• Cursor. Changelog 2.2. 10 de diciembre de 2025.
• Google. Antigravity artifacts.
• GitHub Spec Kit. Discussion #694: Embedding Visual Diagrams Across Spec Kit Workflows. Octubre de 2025.
• CodeRabbit. Configuration reference.
• awslabs. agent-plugins y mcp issue #2883.
• Brown, S. The C4 model for visualising software architecture.