Estándares de Ingeniería de Software y Diseño de Sistemas

Una guía operativa rigurosa y probada para la excelencia en ingeniería de software, arquitectura de sistemas, diseño de bajo nivel y sistemas distribuidos.

1. Principios Operativos Centrales

Compensaciones sobre Dogmas: No existen "mejores prácticas" universales, solo compensaciones. Cada elección arquitectónica compra un conjunto de beneficios pagando un costo específico (latencia, consistencia, complejidad operativa o sobrecarga cognitiva). Siempre indique qué se está sacrificando.
Reversibilidad Primero: Priorice decisiones de dos vías (reversibles) sobre decisiones de una vía (irreversibles). Evite el acoplamiento prematuro a proveedores, marcos de trabajo o topologías distribuidas específicas.
Sin Astronáutica Arquitectónica: Toda abstracción, interfaz y capa debe justificar su peso frente a requisitos existentes concretos, no a necesidades futuras especulativas (YAGNI).
Diseño Basado en Evidencia: Fundamente las decisiones en perfiles, mediciones, planes de consulta (EXPLAIN ANALYZE) y límites de capacidad concretos, no en suposiciones.
Fallar Rápido y Límites Explícitos: Los límites entre subsistemas, dominios o saltos de red deben tener contratos explícitos y fuertemente tipados, validación, tiempos de espera, interruptores de circuito y garantías de idempotencia.

2. Diseño de Alto Nivel (HLD) y Flujo de Trabajo de Arquitectura

Cuando se le pida diseñar un sistema, evaluar una arquitectura o refactorizar un subsistema importante, ejecute este marco de 6 pasos:

flowchart TD
    Step1["1. Clarificar Requisitos y Alcance<br>(Funcionales, No Funcionales, Latencia, Disponibilidad, Consistencia)"]
    Step2["2. Estimación de Capacidad y Escala<br>(DAU, QPS, Rendimiento, Ancho de Banda de Red, Almacenamiento, RAM de Caché)"]
    Step3["3. Arquitectura de Alto Nivel (C4 L1/L2)<br>(Límites de Servicio, Selección de Almacenamiento, Entrada, Caché)"]
    Step4["4. Modelo de Datos y Contratos de Interfaz<br>(Entidades, Esquemas, Claves Primarias, Índices, APIs REST/gRPC)"]
    Step5["5. Inmersiones Profundas y Aislamiento de Cuellos de Botella<br>(Replicación, Fragmentación, Concurrencia, Patologías de Caché, Puntos Calientes)"]
    Step6["6. Estrategia de Resiliencia y SRE<br>(SLOs, Interruptores de Circuito, Reintentos con Jitter, Idempotencia, DLQs)"]

    Step1 --> Step2 --> Step3 --> Step4 --> Step5 --> Step6

Referencia Detallada de HLD

Para teoremas de sistemas distribuidos (CAP, PACELC), jerarquías de consistencia, consenso (Raft/Paxos), fragmentación, replicación, el patrón Saga y el patrón Transactional Outbox, consulte: 👉 Referencia de Diseño de Sistemas de Alto Nivel y Sistemas Distribuidos

3. Diseño de Bajo Nivel (LLD) y Estándares de Código Limpio

Al escribir, revisar o refactorizar código, adhiérase a estos estándares:

3.1 Las Reglas SOLID

SRP (Responsabilidad Única): Un módulo tiene un único actor/interesado al que responder. Extraiga la persistencia, la serialización HTTP y la lógica de negocio en preocupaciones separadas.
OCP (Abierto/Cerrado): Prefiera polimorfismo, patrones Strategy o Visitor sobre grandes sentencias switch / if-else para despacho por tipo.
LSP (Sustitución de Liskov): Los subtipos deben satisfacer todos los invariantes de comportamiento del padre. Sobrescribir métodos para lanzar NotImplementedException viola LSP.
ISP (Segregación de Interfaces): Favorezca interfaces de rol pequeñas y específicas del cliente sobre interfaces "God" amplias.
DIP (Inversión de Dependencias): Las reglas de negocio centrales dependen solo de abstracciones (Puertos), nunca directamente de bibliotecas de bases de datos externas, marcos de UI o controladores de red.

3.2 Encapsulación Modular (Parnas & Connascence)

Secretos del Módulo: Un módulo debe ocultar completamente su secreto principal (algoritmos/estructuras de datos internos) y su secreto secundario (entornos externos/formatos de archivo).
Connascence: Minimice la connascence dinámica (orden de ejecución, tiempo, restricciones de valor) y reduzca el acoplamiento a acuerdos estáticos de nombre/tipo.

Referencia Detallada de LLD

Para guías de campo de patrones de diseño del Gang of Four (GoF), bloques de construcción tácticos de Diseño Guiado por el Dominio (DDD) (Entidades, Objetos de Valor, Agregados, Eventos de Dominio) y técnicas de refactorización, consulte: 👉 Referencia de Diseño de Bajo Nivel y Código Limpio

4. Estándares de API y Persistencia de Datos

APIs RESTful:
- Adhiérase estrictamente a la semántica de métodos HTTP (GET es seguro e idempotente; PUT/DELETE son idempotentes; POST crea).
- Use RFC 7807 (Problem Details) para respuestas de error estructuradas.
- Para colecciones de alto volumen, use paginación por conjunto de claves/cursor sobre paginación por desplazamiento/límite.
Indexación de Bases de Datos (La Regla E-R-S):
- Orden de columnas en índices compuestos: [Columnas de Igualdad] $ o$ [Columnas de Rango] $ o$ [Columnas de Orden].
- Use Índices Cobertores (escaneos solo de índice) e Índices Parciales para eliminar búsquedas en páginas de disco para consultas activas.
- Siempre verifique las consultas con EXPLAIN QUERY PLAN o EXPLAIN ANALYZE.
Mensajería y Eventos Asíncronos:
- Garantice procesamiento efectivamente único combinando entrega de broker al menos una vez con idempotencia del consumidor (IDs de mensaje únicos desduplicados en almacenamiento).
- Enrute mensajes no procesables (poison pills) a Colas de Mensajes Muertos (DLQs) para evitar el estancamiento de la partición.

Referencia Detallada de API y Datos

👉 Estándares de Diseño de API y Persistencia de Datos

5. Ingeniería de Rendimiento, Capacidad y Confiabilidad

Estimación Rápida:
- $1 ext{ día} imes 10^5 ext{ segundos}$ ($86,400 ext{ s}$). $1 ext{M solicitudes/día} imes 12 ext{ RPS}$.
- QPS pico = QPS promedio $ imes$ $3 imes$.
- RAM de caché = $20% imes ( ext{Volumen de Lectura Diaria} imes ext{Tamaño del Elemento})$ (regla 80/20 de Pareto).
- Ley de Little: $L = imes W$ (Concurrencia en vuelo = Tasa de llegada $ imes$ Latencia).
Disciplina de Caché:
- Nunca establezca TTLs arbitrarios no medidos en memoria que expiren durante ventanas operativas normales.
- Invalide basado en versión/huellas digitales de datos o marcas de tiempo de sesión.
- Defiéndase contra Estampida de Caché (use mutexes/cerraduras distribuidas), Penetración de Caché (filtros Bloom) y Avalancha de Caché (jitter de TTL).
Ingeniería de Confiabilidad del Sitio (SRE):
- Haga cumplir SLOs explícitos y presupuestos de latencia ($p50$, $p95$, $p99$).
- Implemente Interruptores de Circuito, Compartimentos Estancos y Retroceso Exponencial con Jitter Completo.

Referencia Detallada de Confiabilidad y Rendimiento

👉 Referencia de Confiabilidad, Rendimiento e Ingeniería de Capacidad

6. Registros de Decisiones de Arquitectura (ADRs)

Documente decisiones técnicas no triviales utilizando el formato ADR estándar:

Contexto e Impulsores: El problema, las restricciones operativas y los objetivos de latencia/escala.
Opciones Consideradas: Alternativas estructurales y sus compensaciones.
Decisión y Resultado: Justificación concreta que vincula los impulsores de la decisión.
Consecuencias: Beneficios positivos explícitos Y costos negativos aceptados.

Referencia y Plantilla Detallada de ADR

👉 Referencia de Registros de Decisiones de Arquitectura y Modelo C4

axewhyzed/agentic-skills

¿Qué es agentic-skills?

Preguntar en tu IA favorita

Documentación