Flujo de trabajo AGF — comandos y fases

Flujo día a día — implementación de features

La mayoría del trabajo cotidiano sigue este ciclo de cuatro comandos:

/spec:explore   → entender el problema
/spec:propose   → generar spec.md, design.md, tasks.md
/spec:apply     → implementar tarea por tarea
/spec:approve   → verificar completitud y archivar

/spec:explore

Inicia una sesión de análisis antes de comprometerse con una dirección. El agente hace preguntas sobre el cambio, examina el codebase, y puede señalar conflictos con ADRs existentes antes de que nadie haya escrito una sola línea de código.

El output no es código: es entendimiento compartido. El desarrollador y el agente alinean el problema, el alcance, y las restricciones.

Cuándo usarlo: siempre, antes de cualquier feature o cambio no trivial.

/spec:propose

Con el contexto de la exploración, el agente genera tres documentos en la raíz de specs/:

spec.md — qué se va a construir: contexto, objetivo, alcance explícito (qué entra y qué no), requisitos funcionales y no funcionales, e impacto en arquitectura.

design.md — cómo se va a construir: qué archivos nuevos se crean, qué archivos existentes cambian, qué estructuras de datos nuevas aparecen, con fragmentos de código para las partes más complejas.

tasks.md — la descomposición en pasos mecánicos y secuenciales para la fase de implementación.

El desarrollador revisa y aprueba (o itera sobre) estos documentos antes de que empiece cualquier implementación. Este es el punto de control más importante del proceso.

/spec:apply

En una sesión nueva (sin contexto residual de conversaciones anteriores), el agente lee la especificación aprobada y ejecuta las tareas una por una, marcando cada una como completada. No toma decisiones creativas en esta fase.

Si durante la implementación aparece una situación no cubierta por los ADRs ni por el design, el agente debe crear un AGDR y hacer una pausa — no improvisar.

/spec:approve

Verifica que la implementación está completa según tasks.md, actualiza el estado de la spec, y la mueve a specs/archive/<id>/. Cada feature completada queda con su historia documental intacta.

---

Flujo de decisiones arquitectónicas — ADRs

Cuando se necesita tomar una decisión de arquitectura que va a gobernar el proyecto en adelante (tecnología, patrón de diseño, convención de estructura):

/adr:explore   → explorar la decisión con el agente
/adr:draft     → generar el borrador en arch/drafts/
/adr:record    → registrar oficialmente en arch/adrs/

/adr:explore

Sesión conversacional donde el agente hace preguntas sobre la decisión que se quiere tomar, puede cuestionarla si contradice el foundation o ADRs existentes, y explora las alternativas. El resultado es la base para el borrador.

/adr:draft

Genera el borrador del ADR en arch/drafts/ con la estructura estándar: contexto, alternativas consideradas (con justificación de por qué se descartaron), decisión, y consecuencias positivas y negativas.

El desarrollador revisa e itera sobre el borrador. Un ADR que omite las alternativas consideradas no tiene valor como registro de decisión.

/adr:record

Mueve el ADR aprobado de arch/drafts/ a arch/adrs/ y actualiza el índice README.md. A partir de ese momento, el agente lo consulta antes de cualquier decisión de implementación.

Estructura de un ADR:

arch/
├── adrs/
│   ├── README.md                              ← índice con tabla de todos los ADRs
│   ├── ADR-000-arquitectura-en-cuatro-capas.md
│   ├── ADR-001-api-first-con-protocol-buffers.md
│   ├── ADR-002-modelo-multi-tenant.md
│   ├── ADR-003-comunicacion-orientada-a-eventos.md
│   └── ADR-004-cliente-rest-externo-con-resty.md
└── drafts/

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

ADRs base de la plataforma WL (ejemplos reales del servicio core-notifications):

ADR	Título	Descargar
ADR-000	Arquitectura en cuatro capas y organización de dominios	ver
ADR-001	API-first con Protocol Buffers y buf	ver
ADR-002	Modelo multi-tenant con FX	ver
ADR-003	Comunicación orientada a eventos con NATS JetStream	ver
ADR-004	Cliente REST externo con resty en la capa Platform	ver

---

Flujo de decisiones autónomas del agente — AGDRs

Durante la implementación, el agente puede encontrar situaciones que los ADRs no cubren. Cuando eso ocurre, el agente no debe improvisar: debe crear un AGDR, notificar al desarrollador, y esperar aprobación.

arch/agdrs/
└── <id>-<descripcion>.md

El desarrollador tiene tres opciones:

/agdr:approve

La decisión propuesta es correcta para este caso. El agente puede continuar la implementación.

/agdr:reject

La decisión propuesta no es la correcta. El agente debe replantearse el enfoque. El AGDR incluye la razón del rechazo para que el agente entienda la dirección correcta.

/agdr:promote

La decisión es suficientemente importante para que rija todo el proyecto. El AGDR se convierte en un ADR formal en arch/drafts/ para su revisión completa con /adr:draft y /adr:record.

---

Estructura de directorios de referencia

<servicio>/
├── foundation.md          ← qué se construye, por qué, qué se espera lograr
├── CLAUDE.md              ← contexto del agente: arquitectura, capas, convenciones
│
├── arch/
│   ├── adrs/
│   │   ├── README.md      ← índice consultado por el agente antes de implementar
│   │   └── ADR-XXX-*.md
│   ├── agdrs/
│   │   └── README.md      ← registro de decisiones autónomas del agente
│   └── drafts/            ← ADRs en proceso de revisión
│
└── specs/
    ├── README.md
    ├── spec.md            ← spec activa durante implementación
    ├── design.md
    ├── tasks.md
    └── archive/
        └── <feature-id>/
            ├── spec.md
            ├── design.md
            └── tasks.md

---

Cuándo no usar el flujo completo

El AGF tiene un costo por diseño. Para situaciones menores, el proceso puede adaptarse:

Situación	Enfoque recomendado
Bug menor con causa clara	Fix directo con descripción en el commit
Ajuste de configuración	Cambio directo, sin spec
Feature compleja de nuevos casos de uso	Flujo completo: explore → propose → apply → approve
Decisión de arquitectura nueva	ADR completo: explore → draft → record
Ambigüedad durante implementación	AGDR + pausa: no improvisar

La regla práctica: si el cambio afecta la estructura del dominio, introduce una dependencia nueva, o crea un patrón que otros van a replicar, usa el flujo completo. Si es un cambio local y reversible, el criterio del desarrollador es suficiente.

---

Sesiones y contexto

Claude Code carga el CLAUDE.md del repo automáticamente al iniciar cada sesión. Los ADRs del proyecto son el contexto que el agente consulta para respetar las convenciones.

Plantillas de referencia:

Archivo	Descripción	Descargar
CLAUDE-agf-template.md	Plantilla de CLAUDE.md basada en un servicio WL real, con workflow AGF integrado	ver

Para la fase /spec:apply, abrir siempre una sesión nueva con /clear antes de empezar. El agente ejecuta mejor cuando su contexto de entrada es solo la especificación aprobada, sin ruido acumulado de la sesión de diseño.

Para exploración y diseño (:explore, :propose), una misma sesión puede mantenerse mientras la conversación sea coherente. Usar /clear si las respuestas empiezan a desviarse o repetir errores.