Desarrollo con IA en White Label — AGF

El problema que resuelve

El “vibe coding” —pedirle al agente “implementa esta feature” y confiar en que el resultado sea coherente— produce código inconsistente. El agente toma decisiones arbitrarias que quedan enterradas sin documentación, y la próxima sesión puede tomar decisiones contradictorias. A mayor complejidad del sistema y tiempo de vida del proyecto, mayor el daño.

El Agentic Governance Framework (AGF) no es una herramienta sino una metodología de proceso. Define quién toma cada decisión, en qué momento, con qué información, y cómo queda registrada antes de que se escriba una sola línea de código.

La premisa central

Humanos gobiernan, IA desarrolla.

El desarrollador deja de ser quien construye el sistema y pasa a ser quien gobierna el agente que lo construye. Ese cambio no es cosmético: tiene implicaciones concretas en cómo se organiza el trabajo y cómo se distribuye la responsabilidad.

Lo que exige el rol de gobernador no es saber escribir prompts. Exige criterio arquitectónico, capacidad de evaluar trade-offs, y suficiente entendimiento del sistema para firmar cada decisión significativa y asumir responsabilidad cuando algo falla.

Los cuatro pilares

1. Foundation

Un documento que responde tres preguntas: qué se va a construir, por qué, y qué se espera que logre. El agente conduce una conversación, hace preguntas, cuestiona la coherencia, y genera el documento. El desarrollador revisa y aprueba.

foundation.md vive en la raíz del repositorio y es el ancla de todo lo que viene después. Cada decisión futura debe ser coherente con él.

2. Architecture Decision Records (ADRs)

Documentan las decisiones de arquitectura: qué tecnología, qué patrón, qué estructura, y —lo más importante— por qué se eligió eso en lugar de las alternativas consideradas.

El flujo es conversacional: /adr:explore inicia una sesión donde el agente hace preguntas y puede cuestionar si la decisión tiene sentido dado el foundation. /adr:draft genera el borrador para revisión. /adr:record registra el ADR aprobado formalmente en el repositorio.

arch/
├── adrs/
│   ├── ADR-000-arquitectura-en-cuatro-capas.md
│   ├── ADR-001-api-first-con-protocol-buffers.md
│   └── README.md    ← índice que el agente consulta antes de implementar
└── drafts/          ← borradores en revisión

Los ADR-000 a ADR-004 son decisiones base de la plataforma WL y aplican a todos los microservicios. Los ADRs específicos de cada servicio comienzan en ADR-005.

3. Agent Decision Records (AGDRs)

Durante la implementación, el agente encuentra situaciones que los ADRs no cubren. En vibe coding, resuelve eso tomando una decisión arbitraria y siguiendo. Con el AGF, el agente hace una pausa, genera un documento (el AGDR) explicando qué quiere hacer y por qué, y espera.

El desarrollador toma una de tres decisiones:

Decisión	Comando	Efecto
Aprobar	/agdr:approve	El agente continúa con la implementación
Rechazar	/agdr:reject	El agente debe replantearse la decisión
Promover	/agdr:promote	El AGDR se convierte en ADR formal

arch/
├── adrs/      ← decisiones aprobadas por humanos
├── agdrs/     ← decisiones generadas por el agente, pendientes de revisión
└── drafts/

Este mecanismo garantiza que hay un responsable humano identificable para cada decisión significativa. El trail de decisiones existe, es legible, y tiene un nombre asociado.

4. Especificaciones (SDD)

Por cada feature o cambio, el flujo pasa por tres momentos:

Exploración (/spec:explore): el agente analiza el cambio desde múltiples ángulos, hace preguntas, y señala conflictos con decisiones de arquitectura existentes antes de que nadie haya escrito una sola línea de código.

Propuesta (/spec:propose): el agente genera tres documentos. spec.md describe qué se va a construir y qué comportamiento se espera. design.md describe exactamente cómo: qué archivos cambian, qué estructuras nuevas aparecen, con fragmentos de código para las partes complejas. tasks.md descompone todo en pasos secuenciales.

Implementación (/spec:apply): en una sesión nueva, el agente lee la especificación aprobada y ejecuta. No toma decisiones creativas en esta fase, solo sigue instrucciones.

specs/
├── README.md
├── spec.md      ← activa durante implementación
├── design.md
├── tasks.md
└── archive/
    └── sqs-cms-consumer/
        ├── spec.md
        ├── design.md
        └── tasks.md

El desarrollador no revisa código — revisa el design.md antes de que se escriba una sola línea. Ese documento dice exactamente qué archivos van a cambiar y por qué. Si el diseño está alineado con los ADRs, el código resultante va a ser correcto.

El repositorio como memoria institucional

Cada feature completada deja su historia documental completa. Cuando un desarrollador nuevo se incorpora, puede leer los ADRs y entender en una tarde por qué el sistema está construido como está. Cuando algo falla en producción, el trail de decisiones existe y es legible.

Esta documentación no se escribe por separado del trabajo: se produce como parte del proceso mismo.

Los trade-offs honestos

No es más rápido inicialmente. Lo que un desarrollador con experiencia resuelve en cinco minutos, este flujo puede tardar treinta. Para bugs menores o cambios triviales, el AGF es pesado. Su valor crece con la complejidad del sistema y la longevidad del proyecto.

El proceso no tiene atajos. Para que el historial de decisiones sea consistente, no puede haber trabajo manual directo sobre el código fuera del proceso. Todo debe pasar por exploración, diseño e implementación estructurada.

Consume tokens de forma significativa. Las fases de exploración y diseño gastan recursos. Es un costo operativo real que hay que presupuestar.

Lo que da a cambio: un historial de decisiones auditado, documentación que se construye sola con cada iteración, y código cuya calidad mejora progresivamente porque el agente acumula contexto sobre el proyecto. Las primeras especificaciones generan código correcto. Las de la décima iteración generan código correcto y consistente con todas las convenciones que el propio proyecto fue definiendo. Eso no ocurre en el vibe coding.