Arquitecto Sirena: Habilidad de Diagramas y Documentación

Mermaid Architect - Skill Integral de Diagramas y Documentación

Versión 2.0 - Arquitectura jerárquica con orquestación inteligente

Una potente habilidad de Claude Code para crear diagramas Mermaid y documentos de diseño utilizando carga de guías bajo demanda, generación de diagramas a partir de código y utilidades de Python.

Instalación

Instalación con un clic a través del Skilz Marketplace

Instala esta habilidad al instante desde el Skilz Marketplace:

skilz install SpillwaveSolutions_design-doc-mermaid/design-doc-mermaid

Instalación manual

Clona directamente en tu directorio de habilidades de Claude Code:

# Navigate to your skills directory
cd ~/.claude/skills

# Clone the repository
git clone https://github.com/SpillwaveSolutions/design-doc-mermaid.git

Verificar instalación

Después de la instalación, verifica que la habilidad esté disponible:

# List installed skills
ls ~/.claude/skills/design-doc-mermaid

# Or ask Claude Code
# "List my installed skills"

Qué hace esta habilidad

Generación inteligente de diagramas:

• Diagramas de actividad (flujos de trabajo, procesos, lógica de negocio)
• Diagramas de despliegue (infraestructura en la nube, K8s, serverless)
• Diagramas de arquitectura (componentes del sistema, microservicios)
• Diagramas de secuencia (flujos de API, interacciones de servicios)
• Documentos de diseño completos con diagramas integrados

Conversión de código a diagrama:

• Extraer arquitectura de aplicaciones Spring Boot
• Generar diagramas de despliegue a partir de archivos de configuración
• Crear diagramas de secuencia a partir de llamadas a métodos
• Documentar pipelines ETL y flujos de datos

Gestión de diagramas:

• Extraer diagramas Mermaid de archivos Markdown
• Validar la sintaxis de los diagramas con mermaid-cli
• Convertir diagramas a imágenes PNG/SVG
• Procesar directorios completos por lotes

Inicio rápido

Crear un diagrama de actividad

User: "Create an activity diagram for user registration with email verification"

La habilidad hará:

1. Carga references/guides/diagrams/activity-diagrams.md
2. Utiliza la plantilla del patrón de registro
3. Añade símbolos Unicode (🔐 para seguridad, 📧 para correo electrónico, ✅ para éxito)
4. Aplica estilo de alto contraste
5. Genera el diagrama Mermaid completo

Generar a partir de código

User: "Here's my Spring Boot application.yml - generate a deployment diagram"

La habilidad hará:

1. Analiza la configuración (datasource, cache, security)
2. Carga references/guides/diagrams/deployment-diagrams.md
3. Carga examples/spring-boot/README.md
4. Mapea la configuración a recursos en la nube
5. Genera el diagrama de despliegue con especificaciones de recursos

Crear documento de diseño

User: "Create an API design document for the contacts API"

La habilidad hará:

1. Carga assets/api-design-template.md
2. Carga las guías de diagramas relevantes (secuencia, ER, arquitectura)
3. Genera el documento completo con diagramas integrados
4. Guarda en docs/design/api-contacts-v1-2025-01-13.md

Estructura

Organización jerárquica

mermaid-architect/
├── SKILL.md                          # Main orchestrator with decision tree
├── README.md                         # This file
├── CLAUDE.md                         # Claude Code instructions
│
├── references/                       # Reference materials
│   ├── mermaid-diagram-guide.md     # Legacy general guide
│   └── guides/                       # Specialized guides (load on-demand)
│       ├── diagrams/
│       │   ├── activity-diagrams.md      # ✅ Complete
│       │   ├── deployment-diagrams.md    # ✅ Complete
│       │   ├── architecture-diagrams.md  # ✅ Complete
│       │   └── sequence-diagrams.md      # ✅ Complete
│       ├── code-to-diagram/
│       │   └── README.md                 # ✅ Complete (master guide)
│       ├── unicode-symbols/
│       │   └── guide.md                  # ✅ Complete (100+ symbols)
│       └── troubleshooting.md        # ✅ Complete (28 common errors)
│
├── scripts/                          # Python utilities
│   ├── extract_mermaid.py           # ✅ Extract & validate diagrams
│   └── mermaid_to_image.py          # ✅ Convert to PNG/SVG
│
├── examples/                         # Language-specific patterns
│   ├── spring-boot/                 # ✅ Complete
│   ├── fastapi/                     # ✅ Complete
│   ├── react/                       # ✅ Complete
│   ├── python-etl/                  # ✅ Complete
│   ├── node-webapp/                 # ✅ Complete
│   └── java-webapp/                 # ✅ Complete
│
└── assets/                           # Design document templates
    ├── architecture-design-template.md
    ├── api-design-template.md
    ├── feature-design-template.md
    ├── database-design-template.md
    └── system-design-template.md

Características principales

1. Símbolos semánticos Unicode

Cada diagrama utiliza símbolos Unicode significativos:

graph TB
    User[👤 Client] --> Gateway[🌐 API Gateway]
    Gateway --> Auth[🔐 Auth Service]
    Gateway --> API[⚙️ API Service]
    API --> DB[(💾 Database)]
    API --> Cache[(⚡ Redis)]
    API --> Queue[📬 Message Queue]
    Queue --> Worker[⚙️ Background Worker]

Categorías de símbolos:

• Infraestructura: ☁️ 🌐 🔌 📡 🗄️
• Computación: ⚙️ ⚡ 🔄 🚀 💨
• Datos: 💾 📦 📊 📈 🗃️
• Mensajería: 📨 📬 📤 📥 🐰
• Seguridad: 🔐 🔑 🛡️ 🚪 👤
• Monitorización: 📝 📊 🚨 ⚠️ ✅ ❌

2. Estilo de alto contraste

Todos los diagramas utilizan colores accesibles de alto contraste - consulta SKILL.md para más detalles.

3. Utilidades de Python

Extraer diagramas

# List all diagrams in a file
python scripts/extract_mermaid.py document.md --list-only

# Extract to separate .mmd files
python scripts/extract_mermaid.py document.md --output-dir diagrams/

# Validate all diagrams
python scripts/extract_mermaid.py document.md --validate

# Replace diagrams with image references (for Confluence)
python scripts/extract_mermaid.py document.md --replace-with-images \
  --image-format png --output-markdown output.md

Convertir a imágenes

# Single file
python scripts/mermaid_to_image.py diagram.mmd output.png

# Custom theme and size
python scripts/mermaid_to_image.py diagram.mmd output.svg \
  --theme dark --background white --width 1200

# Batch convert directory
python scripts/mermaid_to_image.py diagrams/ output/ \
  --format png --recursive

# From stdin
echo "graph TD; A-->B" | python scripts/mermaid_to_image.py - output.png

Requisitos

Para la generación de diagramas

• Sistema de habilidades de Claude Code (automático)
• Guías y plantillas (incluidas en esta habilidad)

Para validación y conversión de imágenes

# Install mermaid-cli globally
npm install -g @mermaid-js/mermaid-cli

# Verify installation
mmdc --version

Para scripts de Python

• Python 3.7+
• No se requieren paquetes adicionales (solo usa la biblioteca estándar)

Ruta de aprendizaje

¿Nuevo en diagramas Mermaid?

1. Comienza con diagramas de actividad - Lee references/guides/diagrams/activity-diagrams.md
2. Aprende los símbolos Unicode - Lee references/guides/unicode-symbols/guide.md
3. Prueba un ejemplo - Usa patrones de examples/spring-boot/
4. Valida tu trabajo - Ejecuta python scripts/extract_mermaid.py --validate

¿Necesitas documentar código existente?

1. Identifica el framework - Spring Boot, FastAPI, React, etc.
2. Carga la guía de ejemplo - Lee examples/{your-framework}/README.md
3. Encuentra patrones - Busca patrones de código similares en los ejemplos
4. Genera diagramas - Usa plantillas de las guías
5. Valida - Usa scripts de validación

¿Creando documentos de diseño?

1. Elige el tipo de plantilla - Arquitectura, API, Funcionalidad, Base de datos o Sistema
2. Carga la plantilla - Lee desde assets/{type}-design-template.md
3. Rellena las secciones - Sustituye los marcadores de posición con contenido real
4. Añade diagramas - Carga las guías de diagramas según sea necesario para cada sección
5. Usa símbolos - Mejora con símbolos Unicode en todo el documento
6. Guarda - Coloca en docs/design/ con marca de tiempo

Cómo funciona el sistema jerárquico

Enfoque tradicional (ineficiente)

• Carga toda la documentación de la habilidad (~50KB)
• La IA procesa todas las plantillas y ejemplos
• Alto uso de tokens
• Tiempo de respuesta lento

Enfoque jerárquico (eficiente)

1. El usuario hace una solicitud → La IA analiza la intención
2. Se activa el árbol de decisión → Determina las guías necesarias
3. Carga solo lo necesario → Lee la guía específica (~2-5KB)
4. Genera la salida → Utiliza plantillas específicas
5. Eficiente en tokens → Se necesita 10 veces menos contexto

Flujo de ejemplo

Usuario: "Crea un diagrama de despliegue para mi configuración de Docker Compose"

Árbol de decisión:

1. Analyze: "deployment diagram" + "Docker Compose"
2. Determine: deployment-diagrams.md needed
3. Load: references/guides/diagrams/deployment-diagrams.md (2KB)
4. Find pattern: Docker Compose template exists
5. Generate: Using template + Unicode symbols
6. Output: Complete diagram in <30 seconds

Tokens utilizados: ~2.000 (frente a ~10.000 con el enfoque tradicional)

Estado de finalización

✅ Completado:

• Orquestador de árbol de decisión jerárquico
• Guía de diagramas de actividad con plantillas
• Guía de diagramas de despliegue (AWS, GCP, K8s, serverless, Docker)
• Guía de símbolos Unicode (más de 100 símbolos)
• Script de extracción Mermaid con validación
• Script de conversión de Mermaid a imagen
• Ejemplos de código a diagrama para Spring Boot
• Plantillas de documentos de diseño (5 tipos)
• Sistema de estilo de alto contraste

🚧 En progreso:

• Ejemplos de FastAPI
• Ejemplos de arquitectura de componentes React
• Ejemplos de pipelines ETL en Python

📋 Planificado:

• Guía de diagramas de arquitectura
• Guía de diagramas de secuencia
• Guía maestra de código a diagrama
• Ejemplos de Node.js/Express
• Ejemplos de aplicaciones web Java

Contribuir

Para añadir una nueva guía de tipo de diagrama:

1. Crea la guía en references/guides/diagrams/{type}-diagrams.md
2. Incluye:
   • Cuándo usar
   • Sintaxis básica
   • Patrones comunes (3-5 plantillas)
   • Ejemplos de símbolos Unicode
   • Mejores prácticas
3. Actualiza el árbol de decisión en SKILL.md
4. Añade ejemplos con mapeos de código

Para añadir un nuevo ejemplo de lenguaje:

1. Crea un directorio en examples/{framework}/
2. Añade un README.md con:
   • Visión general del framework
   • Diagrama de arquitectura a partir de la estructura
   • Diagrama de despliegue a partir de la configuración
   • Diagrama de secuencia a partir del código
   • Diagrama de actividad a partir de la lógica
3. Actualiza la tabla de código a diagrama en SKILL.md

Licencia

Parte de Claude Code Skills - Licencia MIT

Habilidades relacionadas

• confluence - Subir diagramas a Confluence
• plantuml - Formato de diagrama alternativo

Enlaces

• GitHub Repository
• Skilz Marketplace Listing
• Mermaid Official Documentation

Versión: 2.0.0 Actualizado: 2025-01-13 Mantenido por: SpillwaveSolutions