Gobernanza de arquitectura para la generación de código con IA

En resumen

• La generación de código con IA acelera la deriva arquitectónica porque los agentes pueden crear muchos cambios pequeños y aparentemente razonables que, en conjunto, violan las decisiones del sistema.
• La respuesta no es un documento de arquitectura más extenso. Es la gobernanza de arquitectura: un conjunto reducido de artefactos de diseño vivos, instrucciones para el repositorio, verificaciones ejecutables de límites y controles en los PRs.
• Comienza por hacer explícita la arquitectura: contexto del sistema, contenedores, componentes, responsables, dependencias permitidas y ADRs.
• Después hazla ejecutable: reglas de lint, pruebas de ArchUnit, reglas de límites entre módulos, pruebas de contratos de API, políticas de dependencias, verificaciones de seguridad y controles de CI.
• Entrega a los agentes de IA un «paquete de diseño» antes de generar código: intención del producto, límites donde debe operar el cambio, ADRs aceptados, imports prohibidos, atributos de calidad y comandos de validación.
• A los PMs debería importarles porque protege la predictibilidad de las entregas. A los ingenieros debería importarles porque evita que la productividad local se convierta en entropía a nivel del sistema.
• El objetivo práctico no es impedir que la IA cambie la arquitectura. Es hacer que los cambios de arquitectura sean intencionales, revisados, trazables y reversibles.

Los agentes de programación con IA son excelentes para avanzar en tareas locales. Pueden agregar una ruta, escribir una migración, actualizar pruebas, cambiar el nombre de un componente y conectar una dependencia antes de que una persona termine de abrir las pestañas necesarias.

Ese también es el riesgo.

La mayoría de las fallas de arquitectura no empiezan con una gran decisión dramática. Empiezan con pequeñas violaciones:

• una funcionalidad importa desde la capa equivocada
• una regla de dominio se traslada a un controlador
• una integración «temporal» pasa por alto la API de la plataforma
• un servicio escribe en la base de datos de otro servicio
• un agente agrega una abstracción duplicada porque no sabía que ya existía una
• un PR pasa las pruebas mientras debilita una decisión que nadie documentó

La IA acelera esos cambios. Si la arquitectura solo existe en la cabeza de las personas, el agente no puede respetarla. Si la gobernanza solo ocurre en una reunión, el agente avanzará más rápido que ella.

Este artículo se enfoca en los límites de arquitectura y la trazabilidad de las decisiones. Para conocer los controles de seguridad, la selección de modelos y los flujos de aprobación para la programación agéntica, consulta Generación segura de código con agentes: un proceso práctico. Para orquestar agentes dentro de un ciclo de entrega, consulta Agente de ingeniería sénior: orquestación de subagentes con Loop Engineering.

Por eso necesitamos otro enfoque:

Architecture intent
  |
  v
Decision records + boundary maps + repo instructions
  |
  v
AI generation inside known boundaries
  |
  v
Executable fitness functions in CI
  |
  v
Human review for exceptions and new decisions

Eso es la gobernanza de arquitectura para la generación de código con IA.

Qué aprenderás aquí

• Cómo diseñar una aplicación para que el código que la IA genere en el futuro tenga límites claros.
• Qué artefactos de arquitectura son útiles para las personas y los agentes de IA.
• Cómo funcionan juntos los ADRs, los diagramas C4, la responsabilidad sobre los módulos y las funciones de aptitud.
• Cómo crear un paquete de diseño para tareas de programación con IA.
• Cómo convertir las decisiones de arquitectura en verificaciones automatizadas.
• Cómo pueden participar los PMs sin convertir la arquitectura en burocracia.
• Qué limitaciones tiene todavía este enfoque y qué mejorar después.

Lo que indican la investigación y las herramientas

La investigación y las herramientas actuales apuntan en la misma dirección: la gobernanza de arquitectura debe ser más explícita y más ejecutable.

La guía original de Michael Nygard sobre ADRs proponía registros breves y versionados que capturaran las decisiones importantes, su contexto y sus consecuencias. Esto es aún más importante con agentes de IA, porque quienes escriban código en el futuro podrían no compartir la memoria del equipo.

La comunidad de ADR define una decisión de arquitectura como una elección de diseño justificada que afecta un requisito funcional o no funcional, y un ADR como el registro de esa elección y su justificación. Esto nos da una unidad de intención duradera.

El modelo C4 ofrece a los equipos una forma práctica de representar sistemas en diferentes niveles: contexto del sistema, contenedores, componentes y código. Esto importa porque los agentes de IA necesitan límites con el nivel de detalle adecuado. Una funcionalidad de producto suele necesitar el contexto de contenedores y componentes. Una refactorización puede necesitar reglas de dependencias a nivel de paquetes o módulos, aplicadas mediante análisis estático.

Las funciones de aptitud, popularizadas en Building Evolutionary Architectures (Ford, Parsons y Kua, 2017), convierten los objetivos de arquitectura en señales medibles. AWS las describe como valores medibles que ayudan a orientar la evolución de la arquitectura sin sacrificar la autonomía del equipo. Ese es exactamente el equilibrio que necesitamos para las entregas asistidas por IA: los agentes pueden avanzar rápido, pero el sistema sigue midiendo si las propiedades importantes se mantienen.

A junio de 2026, las principales herramientas de programación con IA admiten instrucciones persistentes en el repositorio, pero las cargan de manera diferente:

Las instrucciones de Copilot específicas por ruta en GitHub.com se aplican actualmente a Copilot cloud agent y Copilot code review, no a todas las interfaces de Copilot. Las instrucciones personalizadas de VS Code se aplican al chat y a los flujos de trabajo de agentes, no al autocompletado en línea.

La conclusión es clara:

La gobernanza de arquitectura para la generación de código con IA debe ser legible y ejecutable.

Los artefactos legibles ayudan a las personas y a los agentes a entender qué debe ocurrir. Los artefactos ejecutables detienen la deriva accidental antes del merge.

Gobernanza de arquitectura, no teatro de gobernanza

La gobernanza de arquitectura es el plano de control que rodea la generación de código con IA.

No significa que cada cambio necesite un comité de arquitectura. Significa que las decisiones importantes tienen un lugar donde vivir, una forma de encontrarlas y una forma de verificarlas.

              Architecture Governance

  +----------------+      +--------------------+
  | Design Intent  | ---> | Decision Records   |
  | goals, risks   |      | ADRs, tradeoffs    |
  +----------------+      +--------------------+
          |                         |
          v                         v
  +----------------+      +--------------------+
  | Boundary Map   | ---> | Agent Instructions |
  | ownership, deps|      | AGENTS.md, prompts |
  +----------------+      +--------------------+
          |                         |
          v                         v
  +----------------+      +--------------------+
  | Fitness Checks | ---> | Review Gates       |
  | CI, tests      |      | PRs, exceptions    |
  +----------------+      +--------------------+

Un buen sistema de gobernanza de arquitectura tiene cinco propiedades:

• Explícito: el límite está documentado.
• Local: la regla aparece cerca del código que protege.
• Ejecutable: las reglas importantes se verifican automáticamente.
• Auditable: las excepciones y decisiones son visibles en el historial de Git.
• Pequeño: el sistema protege unas pocas decisiones de alto valor en lugar de pretender controlarlo todo.

El último punto importa. Si cada preferencia se convierte en un control, los ingenieros buscarán formas de eludir el sistema. Si solo los riesgos importantes se convierten en controles, el sistema se gana la confianza del equipo.

Comienza con los límites de diseño de la aplicación

Antes de pedirle a la IA que genere código, decide qué tipo de aplicación estás construyendo. Esto no requiere una fase de diseño enorme. Puede ser un resumen de arquitectura de una página.

Para una aplicación SaaS típica, un punto de partida práctico se ve así:

Browser
  |
  v
Web/API Edge
  |
  v
Application Use Cases
  |
  v
Domain Model
  |
  v
Ports
  |
  v
Adapters: database, queue, email, payments, AI tools

Ese diagrama representa capas de arquitectura hexagonal (puertos y adaptadores). No es lo mismo que la responsabilidad sobre los dominios, que determina qué equipo o módulo puede llamar a cada adaptador. Por lo general necesitas ambas cosas: reglas de capas dentro de un módulo y reglas de responsabilidad entre módulos.

La primera regla de capas:

Las dependencias apuntan hacia adentro. La infraestructura se adapta al dominio. El dominio no conoce el framework, la base de datos, la cola ni el proveedor de LLM.

Para los PMs, este límite significa que el equipo puede cambiar de proveedor de pagos, proveedor de modelos o implementación de base de datos sin reescribir el concepto del producto.

Para los ingenieros, significa que el código generado tiene lugares evidentes donde ubicarse:

Cuando el agente proponga un cambio, revisa primero su ubicación. Una ubicación incorrecta suele ser la primera señal de deriva arquitectónica.

Crea una jerarquía de decisiones

Los agentes de IA necesitan contexto, pero ese contexto debe estar estructurado. Un montón de documentos se convierte en ruido. Una jerarquía de decisiones les da al agente y a quienes revisan un orden claro de autoridad.

1. Product goal
2. Quality attributes
3. Architecture principles
4. Accepted ADRs
5. Boundary map
6. Local code conventions
7. Current task

Cada nivel responde una pregunta diferente:

Esto es útil porque los agentes suelen optimizar para la instrucción más reciente. La jerarquía de decisiones le da un marco a la tarea más reciente, en lugar de permitir que pase por encima de todo lo demás.

Una plantilla mínima de ADR

Mantén los ADRs lo suficientemente breves como para que la gente realmente los escriba.

# ADR-004: Keep payment orchestration in the billing domain

Status: Accepted
Date: 2026-06-11

## Context

Checkout, subscription renewal, refunds, and invoice retries all need the same
payment-state rules. Recent features have started duplicating payment workflow
logic in API handlers and background jobs.

## Decision

Payment orchestration will live in the billing domain application layer.
API handlers and jobs may call billing use cases, but they must not call the
payment provider adapter directly.

## Consequences

- Billing owns retry, idempotency, and payment-state transitions.
- Feature teams can still add payment-triggering flows through billing use cases.
- Direct imports from `adapters/payments` outside billing are architectural violations.

## Enforcement

- Boundary test: only `billing/**` may import `adapters/payments/**`.
- PR checklist: payment changes must link this ADR.

Observa la última sección: aplicación de la decisión. Los ADRs tradicionales suelen terminar en las consecuencias. Los ADRs de la era de la IA también deberían indicar cómo se protege la decisión, y el mismo PR que acepta un ADR debería actualizar la regla de ArchUnit, la restricción de etiquetas de Nx o la herramienta de verificación personalizada correspondiente. Un ADR sin una regla automatizada que lo respalde es documentación, no gobernanza.

Dale a la IA un paquete de diseño

No empieces con «construye esto». Empieza con un paquete de diseño.

Design packet
-------------
Goal: Add invoice retry settings for account admins.

Target boundary:
- UI: account settings
- API: billing routes
- Use case: billing/updateRetryPolicy
- Domain: billing retry policy

Accepted decisions:
- ADR-004: payment orchestration stays in billing
- ADR-007: authorization is checked through policy service

Forbidden moves:
- Do not call payment provider adapters from routes.
- Do not duplicate retry state in account profile tables.
- Do not add a new role model.

Validation:
- npm run lint
- npm test
- npm run test:architecture   # example script name; wire to your checker

Este paquete es accesible para ingenieros y PMs. Los PMs pueden validar el objetivo y el riesgo. Los ingenieros pueden validar los límites. Los agentes de IA pueden convertir el paquete en código sin tener que adivinar la arquitectura.

Para los equipos que ya usan flujos de trabajo guiados por especificaciones, el paquete de diseño puede coexistir con los artefactos de spec-kit. Consulta Cómo aplicar ingeniería inversa a funcionalidades existentes para crear artefactos de Spec-Kit.

Pon las instrucciones para agentes en el repositorio

Las instrucciones del repositorio son el puente entre la arquitectura y las herramientas de IA. Deben ser breves, específicas y verificables.

Ejemplo de AGENTS.md:

# AGENTS.md

## Architecture

- Keep domain code independent from frameworks, databases, queues, and LLM SDKs.
- Application use cases may depend on domain code and ports.
- Adapters implement ports. Domain and use cases must not import adapters directly.
- New cross-boundary dependency rules require an ADR.

## AI Coding Workflow

- Before editing files, identify the target boundary and relevant ADRs.
- If a task requires crossing a forbidden dependency, stop and propose an ADR.
- Prefer small PRs that preserve existing module ownership.
- Run `npm run lint`, `npm test`, and `npm run test:architecture` when relevant.

## Forbidden Patterns

- Do not bypass the authorization policy layer.
- Do not write directly to another domain's tables.
- Do not introduce a second implementation of an existing domain service.

Esto no es magia. Las instrucciones pueden pasarse por alto, malinterpretarse, truncarse o quedar anuladas por contexto contradictorio. Codex deja de cargar instrucciones después de 32 KiB por defecto; Copilot elige el AGENTS.md más cercano; VS Code puede combinar varias fuentes de instrucciones sin garantizar un orden de prioridad. Por eso las mismas reglas necesitan verificaciones ejecutables.

Convierte los límites en código

Las decisiones de arquitectura se vuelven duraderas cuando pueden hacer fallar un build. Los equipos suelen necesitar dos tipos de verificaciones: reglas de capas dentro de un módulo y reglas de responsabilidad entre módulos.

Para equipos de Java, ArchUnit puede aplicar reglas de capas, slices, arquitectura onion y dependencias. La API onionArchitecture() valida la dirección de las dependencias dentro del paquete analizado. Por sí sola, no aplica reglas de responsabilidad entre paquetes como ADR-004.

Capas dentro de billing:

import static com.tngtech.archunit.library.Architectures.onionArchitecture;

import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.junit.AnalyzeClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;

@AnalyzeClasses(
    packages = "com.acme.billing",
    importOptions = ImportOption.DoNotIncludeTests.class
)
class BillingLayeringTest {

    @ArchTest
    static final ArchRule billing_keeps_domain_independent =
        onionArchitecture()
            .domainModels("com.acme.billing.domain.model..")
            .domainServices("com.acme.billing.domain.service..")
            .applicationServices("com.acme.billing.application..")
            .adapter("persistence", "com.acme.billing.adapter.persistence..")
            .adapter("payments", "com.acme.billing.adapter.payments..")
            .adapter("api", "com.acme.billing.adapter.api..");
}

La responsabilidad definida en ADR-004 necesita una regla personalizada independiente:

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;

// ...

@ArchTest
static final ArchRule only_billing_may_use_payment_adapter =
    noClasses()
        .that().resideOutsideOf("..billing..")
        .should().dependOnClassesThat()
        .resideInAnyPackage("..adapter.payments..");

Para monorepos de TypeScript, Nx aplica límites del grafo de proyectos mediante etiquetas y restricciones de dependencias. La regla es una verificación de ESLint, y cada proyecto de Nx debe declarar etiquetas en project.json o package.json antes de que las restricciones surtan efecto.

// eslint.config.mjs (or .eslintrc.json) — excerpt
{
  "rules": {
    "@nx/enforce-module-boundaries": [
      "error",
      {
        "allow": [],
        "depConstraints": [
          {
            "sourceTag": "type:ui",
            "onlyDependOnLibsWithTags": ["type:ui", "type:api-client", "type:shared"]
          },
          {
            "sourceTag": "type:domain",
            "onlyDependOnLibsWithTags": ["type:domain", "type:shared"]
          },
          {
            "sourceTag": "scope:billing",
            "onlyDependOnLibsWithTags": ["scope:billing", "scope:shared"]
          }
        ]
      }
    ]
  }
}

Para cualquier stack, puedes empezar con un manifiesto de arquitectura definido por el equipo y una herramienta de verificación personalizada. El YAML de abajo es ilustrativo, no es un formato estándar que alguna herramienta lea directamente:

# architecture-boundaries.yaml — team-defined schema
domains:
  billing:
    owns:
      - src/billing/**
      - db/migrations/*billing*
    may_depend_on:
      - shared
      - identity
    forbidden_imports:
      - src/adapters/payments/** from outside src/billing/**
      - src/admin/** from src/billing/domain/**

quality_gates:
  require_adr_when:
    - adding a new database
    - adding a new service
    - crossing domain ownership
    - bypassing a platform API

Tu equipo implementa tools/architecture/check-boundaries.ts (o su equivalente) para leer ese manifiesto. Después conecta la herramienta de verificación a CI:

name: Architecture

on:
  pull_request:

jobs:
  architecture:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npm run lint
      - run: npm test
      - run: npm run test:architecture   # maps to your ArchUnit/Nx/custom checker
      - run: npm run check:boundaries    # optional: custom manifest checker

Los repositorios políglotas suelen necesitar varias herramientas de verificación: ArchUnit para servicios de JVM, Nx para aplicaciones de TypeScript y una herramienta de grafos personalizada para todo lo demás.

La primera versión no necesita detectar todo. Necesita detectar las dos o tres violaciones más importantes que empeorarían la arquitectura de manera significativa.

Usa funciones de aptitud como salvaguardas

Una función de aptitud es una verificación objetiva que te indica si una característica de arquitectura sigue en buen estado. En la práctica, los equipos comienzan con verificaciones automatizadas en CI y, con el tiempo, incorporan métricas de observabilidad, dashboards y señales de revisión manual.

Fase 1: automatiza primero en CI

Fase 2+: semiautomatizada o a medida

La clave de la gobernanza es empezar con poco:

Week 1: protect dependency direction
Week 2: protect authorization path
Week 3: protect API contracts
Week 4: add dashboard and exception workflow

Tres verificaciones significativas son mejores que treinta verificaciones decorativas.

Define un proceso para excepciones

A veces el agente tiene razón al cuestionar la arquitectura. Tal vez el límite anterior es incorrecto. Tal vez el producto ha cambiado. Tal vez la abstracción existente está asumiendo demasiada responsabilidad.

La gobernanza no debería bloquear esos descubrimientos. Debería exigir el artefacto adecuado.

AI or engineer finds boundary pressure
  |
  v
Does current ADR allow it?
  | yes
  v
Implement within boundary

  | no
  v
Write proposal ADR
  |
  v
Review tradeoff with owner + PM
  |
  v
Accept, reject, or timebox exception
  |
  v
Update ADR, checks, and repo instructions in the same PR

Cuando se acepta una excepción, actualiza las reglas de ArchUnit, las restricciones de etiquetas de Nx o las herramientas de verificación personalizadas en el mismo conjunto de cambios que el ADR. De lo contrario, la excepción se convierte en deuda técnica invisible.

La regla clave:

Un límite puede cambiar, pero debe cambiar como resultado de una decisión, no como efecto secundario.

Esa frase es el corazón de todo el artículo.

Un control práctico para la revisión de PRs

Cada PR generado por IA debería responder algunas preguntas de arquitectura.

## Architecture Review

- Target boundary:
- Relevant ADRs:
- New dependencies:
- Cross-domain calls:
- Data ownership touched:
- Authorization path:
- Fitness checks run:
- Exceptions requested:

Para cambios pequeños que solo afectan la interfaz, esto toma un minuto. Para cambios riesgosos, obliga a tener la conversación adecuada antes del merge.

Un PM no necesita inspeccionar cada import. Pero sí puede leer los límites donde debe operar el cambio, los ADRs relevantes y las excepciones solicitadas. Eso genera una comprensión compartida de por qué una funcionalidad es sencilla, riesgosa o está bloqueada.

Dónde debería permitirse que la IA avance rápido

No todos los cambios necesitan el mismo nivel de gobernanza.

Low risk
-------
- UI copy
- isolated component styling
- test fixtures
- small bug fixes inside one module

Medium risk
-----------
- new API route
- new database query
- new background job
- shared component behavior

High risk
---------
- new service or database
- auth or authorization change
- payment, billing, identity, privacy, or security logic
- cross-domain dependency
- event schema or public API change
- migration that changes ownership of data

Adapta el flujo de trabajo al riesgo:

Esto evita que la gobernanza ralentice el trabajo inocuo, al tiempo que protege las decisiones importantes.

El acuerdo entre producto e ingeniería

La gobernanza de arquitectura funciona mejor cuando los PMs participan desde el principio.

Los PMs no deberían tener que aprobar imports de paquetes. Pero sí deberían entender:

• qué capacidades de producto son fáciles de implementar porque encajan en la arquitectura actual
• qué capacidades son costosas porque cruzan límites de responsabilidad
• qué decisiones son temporales
• qué atributos de calidad no son negociables
• qué excepciones generan trabajo de limpieza en el futuro

Una traducción útil para los PMs:

Así es como la gobernanza aporta claridad a las entregas en lugar de generar fricción de ingeniería oculta.

Estructura sugerida del repositorio

Una estructura práctica:

repo/
  AGENTS.md
  docs/
    architecture/
      context.md
      containers.md
      boundaries.md
      fitness-functions.md
      adr/
        0001-use-modular-monolith.md
        0002-authorization-policy-layer.md
        0003-domain-ownership.md
  .github/
    copilot-instructions.md
    pull_request_template.md
    instructions/
      architecture.instructions.md
  tools/
    architecture/
      check-boundaries.ts
  src/
    billing/
    identity/
    shared/

Las instrucciones de Copilot específicas por ruta necesitan frontmatter para que GitHub sepa a qué archivos se aplican:

---
applyTo: "src/billing/**,src/identity/**"
---

# Architecture instructions for domain modules

- Read ADR-004 before touching payment adapters.
- Run `npm run test:architecture` before opening a PR.

La estructura tiene tres públicos:

• Las personas leen docs/architecture.
• Los agentes de IA leen AGENTS.md, .github/copilot-instructions.md y .github/instructions.
• CI ejecuta tools/architecture y tu script test:architecture.

La misma decisión aparece de tres formas: explicación, instrucción y aplicación.

Un plan de implementación de 30 días

No necesitas rediseñar toda la organización de ingeniería. Empieza con un repositorio y un área de producto.

Days 1-3
Map the current architecture in one page.
Name the main domains, owners, data stores, and external systems.

Days 4-7
Write the first five ADRs.
Capture decisions that already exist but are only remembered by senior engineers.

Days 8-14
Create AGENTS.md and a PR architecture checklist.
Make AI agents state the target boundary before implementation.

Days 15-21
Add two executable checks.
Start with dependency direction and authorization path.

Days 22-30
Review exceptions.
Update docs, instructions, and checks based on real PR friction.

El primer hito no es una gobernanza perfecta. Es tener un repositorio donde las decisiones de arquitectura ya no sean invisibles.

Limitaciones actuales

Este enfoque es útil, pero tiene límites.

• Los archivos de instrucciones son orientativos. Las herramientas de IA pueden pasar por alto o aplicar mal las instrucciones, especialmente cuando el contexto es largo o contradictorio. Codex trunca las instrucciones en 32 KiB por defecto; Copilot da prioridad al archivo más cercano; los AGENTS.md anidados de VS Code son experimentales.
• Las verificaciones cubren riesgos conocidos. Las funciones de aptitud son excelentes para límites conocidos, pero débiles para descubrir problemas de diseño completamente nuevos.
• Los sistemas heredados necesitan mapearse primero. Si las responsabilidades y dependencias ya son poco claras, la gobernanza de IA comienza con arqueología de código. Consulta Integra GitHub Spec-Kit en repositorios existentes para conocer una forma de reconstruir la estructura mediante ingeniería inversa.
• Los falsos positivos pueden perjudicar la adopción. Un control de arquitectura que genera demasiado ruido se convierte en una carga. Mantén pocas reglas, claras y cuyos problemas se puedan corregir.
• Los PMs a menudo carecen de visibilidad. Si los ADRs son demasiado técnicos, los líderes de producto no entenderán las consecuencias para las entregas.
• Las excepciones de arquitectura necesitan una fecha de vencimiento. Sin responsables ni fechas, las excepciones se convierten en la nueva arquitectura.
• La cobertura entre stacks es desigual. ArchUnit solo funciona con JVM; los límites de Nx se aplican a las dependencias del grafo de proyectos, no a todas las rutas del sistema de archivos; los sistemas políglotas necesitan varias herramientas de verificación.

La mayor limitación es el criterio semántico. Una herramienta puede detectar una violación de imports. No siempre puede determinar si una nueva capacidad de negocio merece un nuevo límite. Eso sigue siendo trabajo de arquitectura para las personas.

Lecturas relacionadas

• Generación segura de código con agentes: un proceso práctico — controles de seguridad y flujos de aprobación para la programación agéntica.
• Agente de ingeniería sénior: orquestación de subagentes con Loop Engineering — arquitectura de referencia para planificación, ejecución, verificación y controles de PR.
• Cómo aplicar ingeniería inversa a funcionalidades existentes para crear artefactos de Spec-Kit — mapeo de código heredado a artefactos de diseño estructurados.
• Integra GitHub Spec-Kit en repositorios existentes — flujos de trabajo guiados por especificaciones en polyrepos.

Modelo final

El modelo mental más sencillo es este:

AI can generate code.
Architecture governance tells it where code belongs.
Fitness functions prove whether the rules still hold.
ADRs decide when the rules should change.

Ese es el equilibrio. Deja que la IA acelere el trabajo local. Haz que la arquitectura sea lo suficientemente sólida para que la velocidad local no se convierta silenciosamente en una falla del sistema.

Fuentes

• Documentación de decisiones de arquitectura, Michael Nygard
• Registros de decisiones de arquitectura
• Modelo C4 para visualizar la arquitectura de software
• Introducción al modelo C4
• Building Evolutionary Architectures, Ford, Parsons y Kua (O’Reilly, 2017)
• Uso de funciones de aptitud en la nube para orientar la arquitectura evolutiva, AWS Architecture Blog
• Guía de usuario de ArchUnit
• Nx: aplicación de límites entre módulos
• OpenAI Codex: instrucciones personalizadas con AGENTS.md
• Documentación de GitHub: agregar instrucciones personalizadas de repositorio para GitHub Copilot
• Documentación de VS Code: usar instrucciones personalizadas