pjt222 Revisar Arquitectura de Software
Evaluar la arquitectura de software a nivel de sistema en cuanto a atributos de calidad, adhesión a principios de diseño y mantenibilidad a largo plazo.
Cuándo Usar
- Evaluar una arquitectura propuesta antes de comenzar la implementación
- Valorar un sistema existente en cuanto a escalabilidad, mantenibilidad o seguridad
- Revisar Registros de Decisiones Arquitectónicas (ADR) de un proyecto
- Realizar una evaluación de deuda técnica
- Evaluar si un sistema está listo para un escalado significativo o una expansión de funcionalidades
- Diferenciar de la revisión de código a nivel de línea (que se enfoca en cambios a nivel de PR)
Entradas
- Obligatorio: Base de código del sistema o documentación arquitectónica (diagramas, ADRs, README)
- Obligatorio: Contexto sobre el propósito, la escala y las restricciones del sistema
- Opcional: Requisitos no funcionales (objetivos de latencia, rendimiento, disponibilidad)
- Opcional: Tamaño del equipo y composición de habilidades
- Opcional: Restricciones o preferencias tecnológicas
- Opcional: Puntos problemáticos conocidos o áreas de preocupación
Procedimiento
Paso 1: Comprender el Contexto del Sistema
Mapear los límites e interfaces del sistema:
## Contexto del Sistema
- **Nombre**: [Nombre del sistema]
- **Propósito**: [Descripción en una línea]
- **Usuarios**: [Quién lo usa y cómo]
- **Escala**: [Solicitudes/seg, volumen de datos, número de usuarios]
- **Antigüedad**: [Años en producción, versiones principales]
- **Equipo**: [Tamaño, composición]
## Dependencias Externas
| Dependencia | Tipo | Criticidad | Notas |
|------------|------|------------|-------|
| PostgreSQL | Base de datos | Crítica | Almacén de datos principal |
| Redis | Caché | Alta | Almacén de sesiones + caché |
| Stripe | API externa | Crítica | Procesamiento de pagos |
| S3 | Almacenamiento de objetos | Alta | Subida de archivos |
Esperado: Imagen clara de qué hace el sistema y de qué depende. En caso de fallo: Si falta documentación arquitectónica, derive el contexto de la estructura del código, configuraciones y archivos de despliegue.
Paso 2: Evaluar la Calidad Estructural
Evaluación del Acoplamiento
Examinar cómo dependen entre sí los módulos:
- Dirección de dependencias: ¿Fluyen las dependencias en una dirección (en capas) o son circulares?
- Límites de interfaz: ¿Los módulos están conectados a través de interfaces/contratos definidos o referencias directas a implementaciones?
- Estado compartido: ¿Se comparte estado mutable entre módulos?
- Acoplamiento de base de datos: ¿Múltiples servicios leen/escriben directamente en las mismas tablas?
- Acoplamiento temporal: ¿Las operaciones deben ocurrir en un orden específico sin orquestación explícita?
# Detect circular dependencies (JavaScript/TypeScript)
npx madge --circular src/
# Detect import patterns (Python)
# Look for deep cross-package imports
grep -r "from app\." --include="*.py" | sort | uniq -c | sort -rn | head -20
Evaluación de la Cohesión
Evaluar si cada módulo tiene una responsabilidad única y clara:
- Nomenclatura del módulo: ¿El nombre describe con precisión lo que hace el módulo?
- Tamaño de archivos: ¿Son los archivos o clases excesivamente grandes (>500 líneas sugiere múltiples responsabilidades)?
- Frecuencia de cambios: ¿Requieren características no relacionadas cambios en el mismo módulo?
- Objetos dios: ¿Hay clases/módulos de los que todo depende?
| Nivel de Acoplamiento | Descripción | Ejemplo |
|---|---|---|
| Bajo (bueno) | Los módulos se comunican a través de interfaces | El Servicio A llama a la API del Servicio B |
| Medio | Los módulos comparten estructuras de datos | Biblioteca compartida de DTO/modelos |
| Alto (preocupación) | Los módulos referencian los internos del otro | Acceso directo a base de datos entre módulos |
| Patológico | Los módulos modifican el estado interno del otro | Estado mutable global |
Esperado: Acoplamiento y cohesión evaluados con ejemplos específicos de la base de código. En caso de fallo: Si la base de código es demasiado grande para revisión manual, muestree 3-5 módulos clave y los archivos con más cambios.
Paso 3: Evaluar los Principios SOLID
| Principio | Pregunta | Señales de Alerta |
|---|---|---|
| Single Responsibility (Responsabilidad Única) | ¿Tiene cada clase/módulo una razón para cambiar? | Clases con >5 métodos públicos sobre preocupaciones no relacionadas |
| Open/Closed (Abierto/Cerrado) | ¿Puede extenderse el comportamiento sin modificar el código existente? | Modificaciones frecuentes a clases principales para cada nueva característica |
| Liskov Substitution (Sustitución de Liskov) | ¿Pueden los subtipos reemplazar a sus tipos base sin romper el comportamiento? | Comprobaciones de tipo (instanceof) dispersas en el código consumidor |
| Interface Segregation (Segregación de Interfaces) | ¿Son las interfaces enfocadas y mínimas? | Interfaces "gordas" donde los consumidores implementan métodos no utilizados |
| Dependency Inversion (Inversión de Dependencias) | ¿Dependen los módulos de alto nivel de abstracciones, no de detalles? | Instanciación directa de clases de infraestructura en la lógica empresarial |
## Evaluación SOLID
| Principio | Estado | Evidencia | Impacto |
|-----------|--------|----------|---------|
| SRP | Preocupación | UserService maneja autenticación, perfil, notificaciones y facturación | Alto — cambios en facturación pueden romper la autenticación |
| OCP | Bien | Sistema de plugins para proveedores de pago | Bajo |
| LSP | Bien | No se encontraron antipatrones de comprobación de tipos | Bajo |
| ISP | Preocupación | IRepository tiene 15 métodos, la mayoría de implementadores usa 3-4 | Medio |
| DIP | Preocupación | Los controladores instancian directamente repositorios de base de datos | Medio |
Esperado: Cada principio evaluado con al menos un ejemplo específico. En caso de fallo: No todos los principios aplican igualmente a cada estilo arquitectónico. Anote cuándo un principio es menos relevante (p. ej., ISP importa menos en bases de código funcionales).
Paso 4: Revisar el Diseño de API
Para sistemas que exponen APIs (REST, GraphQL, gRPC):
- Consistencia: Convenciones de nomenclatura, formatos de error, patrones de paginación uniformes
- Versionado: Existe una estrategia y se aplica (URL, encabezado, negociación de contenido)
- Manejo de errores: Las respuestas de error son estructuradas, consistentes y no filtran datos internos
- Autenticación/Autorización: Correctamente aplicada en la capa de API
- Limitación de velocidad: Protección contra abuso
- Documentación: OpenAPI/Swagger, esquema GraphQL o definiciones protobuf mantenidas
- Idempotencia: Las operaciones de mutación (POST/PUT) gestionan los reintentos de forma segura
## Revisión del Diseño de API
| Aspecto | Estado | Notas |
|---------|--------|-------|
| Consistencia de nomenclatura | Bien | Nomenclatura de recursos RESTful en todo |
| Versionado | Preocupación | Sin estrategia de versionado — los cambios disruptivos afectan a todos los clientes |
| Formato de error | Bien | RFC 7807 Problem Details usado consistentemente |
| Autenticación | Bien | JWT con ámbitos basados en roles |
| Limitación de velocidad | Ausente | Sin limitación de velocidad en ningún endpoint |
| Documentación | Preocupación | Existe especificación OpenAPI pero con 6 meses de desactualización |
Esperado: Diseño de API revisado con respecto a estándares comunes con hallazgos específicos. En caso de fallo: Si no se expone ninguna API, omita este paso y enfóquese en las interfaces internas de los módulos.
Paso 5: Evaluar Escalabilidad y Fiabilidad
- Sin estado: ¿Puede la aplicación escalar horizontalmente (sin estado local)?
- Escalabilidad de base de datos: ¿Están las consultas indexadas? ¿Es el esquema adecuado para el volumen de datos?
- Estrategia de caché: ¿Se aplica el caché en las capas apropiadas (base de datos, aplicación, CDN)?
- Gestión de fallos: ¿Qué ocurre cuando una dependencia no está disponible (interruptor de circuito, reintento, alternativa)?
- Observabilidad: ¿Están implementados registros, métricas y trazas?
- Consistencia de datos: ¿Es aceptable la consistencia eventual o se requiere consistencia fuerte?
Esperado: Escalabilidad y fiabilidad evaluadas en relación con los requisitos no funcionales declarados. En caso de fallo: Si los requisitos no funcionales no están documentados, recomiende definirlos como primer paso.
Paso 6: Evaluar la Deuda Técnica
## Inventario de Deuda Técnica
| Elemento | Gravedad | Impacto | Esfuerzo Estimado | Recomendación |
|---------|---------|---------|-----------------|---------------|
| Sin migraciones de base de datos | Alta | Los cambios de esquema son manuales y propensos a errores | 1 sprint | Adoptar Alembic/Flyway |
| Suite de pruebas monolítica | Media | Las pruebas toman 45 min, los desarrolladores las omiten | 2 sprints | Dividir en unit/integration/e2e |
| Valores de configuración hardcodeados | Media | Valores específicos del entorno en código fuente | 1 sprint | Extraer a variables de entorno/servicio de configuración |
| Sin canalización CI/CD | Alta | Despliegue manual propenso a errores | 1 sprint | Configurar GitHub Actions |
Esperado: Deuda técnica catalogada con gravedad, impacto y estimaciones de esfuerzo. En caso de fallo: Si el inventario de deuda es abrumador, priorice los 5 elementos principales por ratio impacto/esfuerzo.
Paso 7: Revisar los Registros de Decisiones Arquitectónicas (ADRs)
Si existen ADRs, evaluar:
- Las decisiones tienen contexto claro (qué problema se estaba resolviendo)
- Las alternativas fueron consideradas y documentadas
- Los compromisos son explícitos
- Las decisiones siguen siendo actuales (no superadas sin documentación)
- Las nuevas decisiones significativas tienen ADRs
Si no existen ADRs, recomiende establecerlos para las decisiones clave.
Paso 8: Redactar la Revisión Arquitectónica
## Informe de Revisión Arquitectónica
### Resumen Ejecutivo
[2-3 oraciones: salud general, preocupaciones clave, acciones recomendadas]
### Fortalezas
1. [Fortaleza arquitectónica específica con evidencia]
2. ...
### Preocupaciones (por gravedad)
#### Críticas
1. **[Título]**: [Descripción, impacto, recomendación]
#### Mayores
1. **[Título]**: [Descripción, impacto, recomendación]
#### Menores
1. **[Título]**: [Descripción, recomendación]
### Resumen de Deuda Técnica
[Los 5 elementos de deuda principales con recomendaciones priorizadas]
### Próximos Pasos Recomendados
1. [Recomendación accionable con alcance claro]
2. ...
Esperado: El informe de revisión es accionable con recomendaciones priorizadas. En caso de fallo: Si la revisión está limitada en tiempo, indique claramente qué se cubrió y qué queda sin evaluar.
Validación
- Contexto del sistema documentado (propósito, escala, dependencias, equipo)
- Acoplamiento y cohesión evaluados con ejemplos de código específicos
- Principios SOLID evaluados donde aplica
- Diseño de API revisado (si aplica)
- Escalabilidad y fiabilidad evaluadas frente a los requisitos
- Deuda técnica catalogada y priorizada
- ADRs revisados o su ausencia anotada
- Las recomendaciones son específicas, priorizadas y accionables
Errores Comunes
- Revisar código en lugar de arquitectura: Esta habilidad trata del diseño a nivel de sistema, no de la calidad del código a nivel de línea. Use
code-reviewerpara retroalimentación a nivel de PR. - Prescribir una tecnología específica: Las revisiones arquitectónicas deben identificar problemas, no imponer herramientas específicas salvo que haya una razón técnica clara.
- Ignorar el contexto del equipo: La arquitectura "mejor" para un equipo de 3 personas difiere de la de un equipo de 30. Considere las restricciones organizacionales.
- Perfeccionismo: Todo sistema tiene deuda técnica. Enfóquese en la deuda que está causando dolor activamente o bloqueando trabajo futuro.
- Asumir escala: No recomiende sistemas distribuidos para una aplicación que sirve a 100 usuarios. Adecue la arquitectura a los requisitos reales.
Habilidades Relacionadas
security-audit-codebase— revisión de código y configuración centrada en seguridadconfigure-git-repository— estructura del repositorio y convencionesdesign-serialization-schema— diseño y evolución del esquema de datosreview-data-analysis— revisión de corrección analítica (perspectiva complementaria)