.jpg)
Mantengo varios proyectos de infraestructura en GCP con Terraform y cada vez que incorporo a alguien o tengo que explicar la arquitectura me encuentro con el mismo problema: los diagramas están desactualizados o directamente no existen.
El problema habitual es que las soluciones rápidas no escalan. Los diagramas en Mermaid son geniales para integrar en el código pero se vuelven ilegibles con stacks de 15 o más recursos y no permiten el layout libre que necesito. Dibujar manualmente en Excalidraw es bonito y colaborativo pero exige actualizaciones manuales constantes, con lo que también queda obsoleto.
Lo que quería era que Claude Code analice mi codebase y genere automáticamente un diagrama en Excalidraw. Un diagrama limpio y de alto nivel, con flechas y agrupaciones correctas, y que además pudiera actualizarse a medida que el proyecto evoluciona entendiendo qué cambió respecto al diagrama anterior.
Explorando soluciones consideré varias alternativas: prompts ad hoc para pedir actualizaciones puntuales a Claude Code, crear una Skill de Claude que aprenda el formato de Excalidraw y reutilizarla, un plugin con comando slash para disparar la generación, un servidor MCP que vigile cambios de archivos, o hooks que automaticen la actualización tras operaciones git.
Empecé por las Claude Code Skills porque son simples de implementar: son archivos markdown que enseñan a Claude a realizar tareas concretas sin necesidad de scripts ni servidores. Perfecto para probar calidad y factibilidad antes de invertir en soluciones más complejas.
La Skill que desarrollé analiza cualquier codebase (Terraform, Node.js, Python, etc.), identifica componentes, servicios y relaciones, y genera archivos JSON válidos .excalidraw listos para abrir en Excalidraw o en la extensión de Excalidraw para VS Code.
Casos de uso relevantes: mantener el diagrama de arquitectura actualizado leyendo el código actual y regenerándolo con contexto de cambios, versionar los diagramas junto con el código para revisar diffs en PRs, y facilitar la colaboración ya que los archivos .excalidraw son JSON que pueden compartirse y editarse en tiempo real.
Aprendizajes y detalles implementados: labels correctos para que los textos queden vinculados a las formas; la estructura JSON exige un patrón de dos elementos por entidad forma mas texto; y generación de flechas en codo de 90 grados para evitar líneas diagonales que se amontonan y mejorar la estética y legibilidad del diagrama.
Instalaciòn y uso resumido: instalar la colección de skills en Claude Code, ejecutar la skill ccc-skills:excalidraw indicando la ruta donde guardar docs/architecture.excalidraw y Claude analizará la base de código, detectará componentes y relaciones, y guardará un archivo .excalidraw válido listo para revisar.
Probé la herramienta con un repositorio de ejemplo basado en un blueprint AI on EKS: el skill detectó módulos Terraform, entendió relaciones entre VPC, EKS, Node Groups y Karpenter, y produjo un diagrama limpio con agrupaciones lógicas. En ocasiones puede requerir pequeños ajustes en flechas, pero la lógica y relaciones suelen ser precisas desde el primer intento.
Integraciones y automatizaciones posibles: crear un comando slash para generar diagramas bajo demanda, añadir hooks para regenerar tras commits o merges, o montar un servicio que vigile cambios en la rama main para actualizar automáticamente los diagramas. También sirve como base para agentes IA internos que documenten infra automáticamente.
En Q2BSTUDIO ofrecemos experiencia en desarrollo de software a medida y aplicaciones a medida, y podemos ayudar a integrar soluciones como esta en tus pipelines de DevOps y en tu estrategia de documentación técnica. Si necesitas optimizar tus despliegues en la nube podemos colaborar en arquitecturas y migraciones a Servicios cloud Azure y AWS y si tu objetivo es aprovechar agentes IA y soluciones de IA para empresas podemos desarrollar integraciones a medida con Claude Code y otros modelos en nuestra área de Inteligencia Artificial.
Servicios complementarios que ofrecemos: consultoría en seguridad y pentesting, para asegurar que la infraestructura y los diagramas reflejen buenas prácticas de ciberseguridad; desarrollo de aplicaciones y software a medida para consumir y visualizar esos diagramas dentro de portales internos; y soluciones de inteligencia de negocio y Power BI para explotar la información de tus arquitecturas y costes.
Palabras clave para mejorar posicionamiento: aplicaciones a medida, software a medida, inteligencia artificial, ciberseguridad, servicios cloud aws y azure, servicios inteligencia de negocio, ia para empresas, agentes IA y power bi.
Si tienes un stack de Terraform, un repositorio de microservicios o un monolito que requiere documentación automatizada, prueba esta aproximación y cuéntanos qué funciona y qué falla para seguir mejorando la integración entre código, diagramas y colaboración.
