CommunityProgramación y desarrollogithub.com

ingeniería-de-arquitectura-de-software

Habilidad de codificación. Diseña, implementa, refactoriza y revisa software preservando continuamente la integridad arquitectónica. Úsala para codificación asistida por IA, cambios en repositorios, desarrollo de funcionalidades, cambios en API/bases de datos, límites de módulos, diseño de sistemas, migraciones, decisiones de despliegue, escalabilidad, fiabilidad y revisiones de arquitectura. Analiza la arquitectura existente antes de cambiar código; elige compensaciones ponderadas por contexto; verifica las restricciones arquitectónicas después de los cambios. Mantente ligero para ediciones aisladas de bajo riesgo.

¿Qué es ingeniería-de-arquitectura-de-software?

Esta habilidad está diseñada para mantener la coherencia arquitectónica durante cambios de software, incluyendo aquellos realizados por agentes de IA. Se basa en los principios de *Fundamentals of Software Architecture*, 2.ª ed. (Richards y Ford, 2025), pero es una síntesis original que no requiere un modelo, lenguaje de programación, repositorio, herramienta de CI o framework específico. Su núcleo son tres leyes: todo es una compensación, el porqué importa más que el cómo, y las decisiones se encuentran en un espectro (evitando falsos binarios). La habilidad clasifica el esfuerzo requerido en tres modos (Ligero, Estándar o Profundo) según el impacto del cambio, y define un bucle de agente de codificación obligatorio para trabajar en repositorios existentes: desde el descubrimiento del sistema actual hasta la verificación posterior a la implementación de que la arquitectura no se ha desviado. Además, establece salvaguardas no negociables contra invenciones, falsos universales, acoplamiento oculto y teatro de procesos, priorizando siempre la evidencia real de código y las comprobaciones verificables sobre listas de verificación o auto-evaluaciones. Para decisiones consecuentes, se fomenta la creación de Registros de Decisión Arquitectónica (ADR) concisos y se proporcionan referencias y plantillas opcionales para análisis y documentación adicional.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/iAmSerathion/Skills/tree/HEAD/software-architecture-engineering

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Ingeniería de Arquitectura de Software

Propósito

Mantener la arquitectura coherente mientras se modifica el software, incluidos los cambios escritos por agentes de IA. Esta es una habilidad operativa, no una orden para rediseñar cada proyecto. Sus principios reutilizables provienen de Fundamentals of Software Architecture, 2.ª ed. (Richards and Ford, 2025); los flujos de trabajo continuos de agentes y los artefactos son extensiones originales. No se requiere un modelo, lenguaje de programación, alojamiento de repositorio, herramienta de CI o framework específico.

Aplica tres leyes en todo momento:

  1. Todo es una compensación. Evalúa tanto los costes como los beneficios, ponderados por el contexto real; reevalúa cuando las condiciones cambien.
  2. El porqué importa más que el cómo. Conserva la justificación, las opciones rechazadas, los riesgos y los responsables de las decisiones, no solo diagramas y código.
  3. Las decisiones se encuentran en un espectro. Rechaza los falsos binarios, las reglas generales sobre microservicios y las modas de arquitectura.

Elige el esfuerzo según el impacto

ModoDesencadenante típicoAcción y resultado esperado
LigeroError aislado, formato, implementación local sin efecto en contratos/límitesInspeccionar el código y restricciones relevantes; hacer el cambio mínimo; ejecutar comprobaciones pertinentes; informar solo de problemas materiales. Sin ADR obligatorio.
EstándarFuncionalidad entre módulos, nueva integración, cambio de API/esquema, refactorización consecuenteEstablecer el contexto del proyecto; inspeccionar dependencias; comparar opciones realistas; implementar en incrementos; verificar límites y contratos; registrar decisiones significativas.
ProfundoNueva plataforma, división de servicios, migración importante, cambio de alto riesgo en datos/seguridad/fiabilidad, revisión de arquitecturaAnálisis completo de contexto y arquitectura, alternativas, modos explícitos de datos/fallos, migración y reversión, funciones de idoneidad medibles, ADR(s), riesgo y límites de aprobación.

Escalar cuando una edición supuestamente pequeña cruza límites de propiedad, cambia contratos públicos, altera la persistencia, introduce nuevos componentes de ejecución/despliegue, amplía el impacto de fallos o revela desviación arquitectónica. Desescalar si la investigación muestra que no hay un impacto arquitectónico significativo. Las instrucciones del usuario/proyecto/seguridad tienen prioridad. Nunca fuerces informes pesados para tareas triviales.

Bucle obligatorio del agente de codificación

Para trabajo en un repositorio existente, realiza este bucle. Consulta gobernanza de implementación de agentes para conocer el procedimiento preciso, el manejo de fallos y las reglas para agentes paralelos.

0. Descubrir el sistema actual—no lo inventes

  • Inspeccionar el código relevante, pruebas, archivos de paquete/compilación, infraestructura, configuración, documentación, ADR, diseño de directorios y rutas de dependencia reales cuando sean accesibles.
  • Localizar cualquier contrato de arquitectura del proyecto, por ejemplo, docs/architecture/CONTRACT.md, y los ADR aceptados; tratarlos como restricciones del proyecto, no verdades inmutables.
  • Registrar observado / proporcionado / asumido / desconocido por separado. Si no hay acceso al código o herramienta, indicar que el resultado es una propuesta, no un análisis verificado del repositorio.
  • No reemplaces silenciosamente la arquitectura ya en uso con un estilo favorito.

1. Evaluar el impacto antes de editar

  • Definir el alcance del cambio, las capacidades de negocio afectadas, los módulos propietarios, las API/contratos, las responsabilidades de datos, las dependencias, los límites de seguridad, las unidades de despliegue y las rutas de fallo.
  • Clasificar la tarea como Ligera / Estándar / Profunda y elegir la revisión adecuada más pequeña.
  • Para decisiones relevantes, derivar algunas características arquitectónicas priorizadas (por ejemplo, seguridad, latencia, disponibilidad, escalabilidad, elasticidad, mantenibilidad, testabilidad, desplegabilidad, recuperabilidad, coste) con alcance, objetivo y medición. Separar los requisitos explícitos de los implícitos y no confirmados.
  • Elegir valores predeterminados mínimos y reversibles para incógnitas de bajo riesgo; no proceder con suposiciones de alto riesgo no respaldadas como si estuvieran confirmadas.

2. Preservar los límites y comparar alternativas cuando esté justificado

  • Favorecer la alta cohesión y el bajo acoplamiento. Mantener explícitas la responsabilidad empresarial, la dirección de las dependencias, el acoplamiento temporal y la propiedad de los datos. Distinguir los módulos lógicos de los servicios desplegados de forma independiente.
  • Comprobar las implicaciones para la arquitectura operativa y de datos, no solo la estructura de directorios. Una base de datos compartida, un límite de transacción o una llamada síncrona pueden deshacer la modularidad aparente.
  • Para cambios consecuentes, comparar al menos dos opciones factibles utilizando compensaciones ponderadas por contexto. Los candidatos pueden incluir monolito en capas, monolito modular, tubería, microkernel, basado en servicios, basado en eventos, basado en espacio, SOA orquestado, microservicios o híbridos. Ningún estilo de arquitectura es el predeterminado universal.
  • Los diseños distribuidos deben abordar el fallo/latencia de red, la disponibilidad, la consistencia, los límites de transacción, los reintentos, la idempotencia, la observabilidad, la seguridad y el coste operativo según corresponda.
  • Nombrar condiciones que revertirían la decisión. Usar estilos, diseño distribuido y fundamentos de forma selectiva.

3. Planificar la implementación en incrementos seguros

  • Identificar los cambios esperados en archivos/módulos, los contratos que deben permanecer estables, el orden de migración y la estrategia de reversión cuando sea necesario.
  • Indicar los invariantes de arquitectura (reglas que deben seguir siendo verdaderas): dirección de dependencia permitida, propiedad de API interna, autoridad de escritura de datos, límites de tenencia/autenticación, compatibilidad hacia atrás, gestión de errores, etc.
  • Elegir comprobaciones objetivas para esos invariantes antes de implementar. Cuando sea útil, copiar/adaptar el contrato de arquitectura del proyecto y la plantilla de impacto de cambio; no crear archivos de proyecto sin permiso o un alcance de tarea claro.
  • Solicitar o aplazar decisiones irreversibles/de alto impacto que requieran autorización humana/empresarial. No falsificar aprobaciones.

4. Implementar sin desviación arquitectónica

  • Realizar el cambio coherente más pequeño que sea consistente con la arquitectura actual. No dividir servicios, introducir intermediarios, abstracciones globales o nuevos frameworks sin una necesidad demostrada.
  • Mantener explícitas las interfaces y la propiedad de los datos. No crear atajos a través de las partes internas de otro módulo, eludir la autenticación/validación, cambiar esquemas de eventos silenciosamente o mezclar cambios no relacionados.
  • Si la implementación revela un fallo importante en el plan, detenerse y reevaluar la decisión afectada en lugar de ocultarlo con código de solución alternativa. Actualizar el ADR/contrato solo cuando esté justificado.
  • En trabajo multiagente, definir la propiedad de componentes/archivos, los contratos estables y un propietario de integración. Los cambios paralelos no anulan las restricciones arquitectónicas compartidas.

5. Verificar la arquitectura, no solo la función

  • Ejecutar las pruebas unitarias/de integración/de contrato y comprobaciones de compilación relevantes existentes cuando estén disponibles y autorizadas.
  • Verificar funciones de idoneidad específicas de la arquitectura: dependencias prohibidas, ciclos, propiedad de módulos, compatibilidad de API, migración de esquemas, idempotencia, presupuestos de rendimiento, observabilidad, resiliencia, seguridad, despliegue/reversión, según corresponda.
  • Comparar la estructura de dependencias antes/después y los invariantes afectados. Un comprobador de límites de importación opcional de la stdlib con ejemplo de configuración puede hacer cumplir reglas de importación seleccionadas de Python/JS/TS; es intencionalmente limitado y no demuestra la corrección arquitectónica completa.
  • Etiquetar la evidencia como PASA / FALLA / NO EJECUTADO / NO APLICA. No afirmar que se verificaron pruebas, escalabilidad, preparación para producción, seguridad o despliegues sin una ejecución/evidencia real.
  • Si alguna comprobación obligatoria falla, corregir/revertir, o identificar explícitamente el problema no resuelto y el responsable de la decisión. Nunca presentar una comprobación fallida como trabajo completado.

6. Registrar y comunicar decisiones consecuentes

  • Crear o actualizar un ADR conciso solo para cambios con relevancia arquitectónica: título, estado, contexto, solución elegida, porqué, alternativas, compensaciones, consecuencias, aplicación y desencadenante de revisión. Usar la plantilla ADR.
  • Conservar las decisiones históricas cuando sean reemplazadas. Tratar los diagramas como ayudas de comunicación, no como evidencia de implementación o validación.
  • En el informe final, indicar: qué cambió; impacto arquitectónico; comprobaciones pasadas, fallidas o no ejecutadas; riesgos pendientes; y cualquier decisión humana requerida. Para cambios Ligeros, un párrafo conciso suele bastar.

Tareas solo de diseño y auditoría

Cuando no se edita un repositorio, aplicar los pasos 0–3 y 6 de manera proporcional; producir un diseño, un análisis de compensaciones, un informe de arquitectura o una revisión sin pretender que se implementó o probó nada. Para una auditoría de arquitectura completa, inventariar componentes, propiedad de datos, límites, despliegue y restricciones de equipo/infraestructura; clasificar los riesgos concretos con evidencia; proponer remediaciones incrementales y funciones de idoneidad antes de recomendar reescrituras completas.

Salvaguardas no negociables

  • Sin hechos no verificables: No se permiten inspecciones inventadas de repositorios, resultados de pruebas, niveles de carga, estado de cumplimiento, costes, aprobaciones de partes interesadas o mediciones.
  • Sin falsos universales: Ni los microservicios, ni los monolitos, ni los sistemas basados en eventos son inherentemente mejores. No dividir servicios solo por tabla/entidad.
  • Sin confusión de alcance: Los módulos lógicos, las unidades desplegadas, la propiedad de los datos y el alcance de las características arquitectónicas son conceptos diferentes.
  • Sin acoplamiento oculto: Examinar esquemas compartidos, librerías compartidas, acoplamiento temporal, llamadas entre servicios y contratos de eventos; la reutilización de lógica de dominio volátil puede aumentar el acoplamiento.
  • Sin eliminación de riesgos: La consistencia distribuida, el manejo de transacciones, los cambios de esquema, la recuperación de fallos y la reversión requieren reflexión explícita cuando sean relevantes.
  • Sin teatro de procesos: Una lista de verificación completada o una autoevaluación no es una prueba. Priorizar las comprobaciones reales y la evidencia de código.
  • Sin cambios silenciosos de arquitectura: Señalar las desviaciones importantes, documentar las razones y mantener la responsabilidad en el responsable humano/de proyecto.
  • Sin distribución de libros con derechos de autor: Esta habilidad es una síntesis original. No copiar el libro ni sus diagramas en repositorios downstream.

Archivos de referencia bajo demanda

Lee solo los archivos necesarios para la tarea (rutas relativas a este directorio de habilidad):

Artefactos: informe de arquitectura, contrato de arquitectura, impacto de cambio, ADR, matriz de compensaciones, registro de riesgos, revisión de arquitectura, ejemplo de política de límites. Escenario práctico: Codificación de IA sin desviación de límites. Otras instrucciones de modelo/ejecución son opcionales; consulta portabilidad.

Skills relacionados