architecture-docs

Documentar arquitectura del sistema

Resumen

Este skill genera documentación arquitectónica que permite a cualquier desarrollador nuevo entender cómo funciona el sistema sin necesidad de leer todo el código. Cubre la visión general, los componentes principales, los flujos de datos, las dependencias externas y los enlaces a las decisiones arquitectónicas (ADRs) que explican el por qué de cada elección.

La documentación arquitectónica es un mapa del sistema: no necesita cubrir cada detalle, pero debe permitir orientarse y saber dónde buscar.

Proceso

1. Redactar la visión general. En 2-3 párrafos, explicar:

   • Qué es el sistema y qué problema resuelve.
   • A quién va dirigido (usuarios, otros servicios, el equipo interno).
   • Qué principios de diseño guían la arquitectura.

2. Documentar los componentes principales. Para cada componente significativo:

   • Nombre y propósito.
   • Responsabilidades (qué hace y qué no hace).
   • Tecnologías que usa.
   • Interfaces públicas (cómo se comunica con otros componentes).
   • Ubicación en el código (directorio o módulo).

3. Generar diagrama de componentes con Mermaid. Un diagrama vale más que mil palabras, pero solo si es claro:

   graph TD
     subgraph Frontend
       A[SPA React]
     end
     subgraph Backend
       B[API REST]
       C[Worker Jobs]
     end
     subgraph Datos
       D[(PostgreSQL)]
       E[(Redis Cache)]
     end
     A -->|HTTP/JSON| B
     B --> D
     B --> E
     B -->|Encola| C
     C --> D
   

   Mantener el diagrama simple. Si es demasiado complejo, dividir en múltiples diagramas por dominio.

4. Documentar los flujos de datos principales. Para los 2-3 flujos más importantes del sistema, generar diagramas de secuencia que muestren cómo se mueven los datos entre componentes:

   sequenceDiagram
     participant U as Usuario
     participant F as Frontend
     participant A as API
     participant D as DB
     U->>F: Acción del usuario
     F->>A: Request HTTP
     A->>D: Query
     D-->>A: Resultado
     A-->>F: Response JSON
     F-->>U: Actualiza interfaz
   

5. Listar dependencias externas. Servicios de terceros de los que depende el sistema:

   • Nombre del servicio.
   • Para qué se usa.
   • Qué pasa si no está disponible (fallback, degradación, fallo total).
   • Enlace a su documentación.

6. Enlazar decisiones arquitectónicas. Referenciar los ADRs relevantes que explican por qué se tomaron las decisiones de diseño. Si no hay ADRs, considerar crearlos con el skill write-adr.

7. Incluir instrucciones de desarrollo. Cómo levantar el entorno de desarrollo:

   • Requisitos previos (versiones de lenguaje, herramientas).
   • Pasos para arrancar el proyecto desde cero.
   • Cómo ejecutar tests.
   • Variables de entorno necesarias.

Criterios de éxito

• La visión general explica qué es el sistema y para qué sirve en 2-3 párrafos.
• Cada componente principal está documentado con propósito, responsabilidades e interfaces.
• Hay al menos un diagrama de componentes y un diagrama de secuencia en Mermaid.
• Las dependencias externas están listadas con su impacto en caso de fallo.
• Las decisiones arquitectónicas están referenciadas o documentadas.
• Las instrucciones de desarrollo permiten a un nuevo miembro del equipo arrancar el proyecto.