Marco de Trabajo: Backend Profesional con IA

Versión unificada y simplificada. Fusiona el enfoque documental (artefactos encadenados, roles, trazabilidad) con el enfoque iterativo (bucles, TDD, gates automatizados).

Ejemplos en Java/Spring Boot; el marco es agnóstico del stack.

Parte I — Principios

1. La IA propone. El desarrollador decide. Las herramientas verifican. Ningún “parece correcto” cuenta como evidencia.
2. La IA amplifica tu especificación, no tu intención. El cuello de botella es el contexto, no la generación de código.
3. La documentación es la memoria del proyecto. Lo que solo existe en un chat, no existe.
4. Nada se documenta antes de necesitarlo. Documento por milestone o por capacidad, nunca para el producto entero.
5. Cada artefacto se aprueba antes de alimentar al siguiente. Un requisito ambiguo se multiplica en cada fase posterior.
6. La IA nunca es juez de su propio código. La revisión ocurre en sesión limpia y con rol adversarial.
7. El default es desarrollo. Un proyecto recién clonado arranca sin configurar nada. Producción es lo que se parametriza, no al revés. Un host escrito a mano es un defecto de despliegue esperando su turno.
8. Una regla es verificable cuando lo prohibido no está disponible. Si decides no usar algo, sácalo del classpath. Una prohibición que depende de la disciplina no es una regla, es una intención.

Parte II — El ciclo real

El error de la mayoría de marcos es representar el proceso como una línea recta que termina en Release. Tests, seguridad, revisión, performance y CI/CD no son fases finales: o son continuas o son por slice.

LOOP 0 — UNA SOLA VEZ (1 día)
  [ ] Repositorio, formateador y quality gates enganchados al build.
  [ ] 00-agents.md escrito.
  [ ] Un comando de entrada única (Makefile o equivalente). Sin argumentos, lista
      lo que se puede hacer. Los comandos del 00-agents.md apuntan ahí.
  [ ] `doctor`: un target que responde "¿por qué no me funciona?" sin leer código.
  [ ] Toda la configuración con default de desarrollo.
  [ ] .env.example que documenta lo que producción sí debe definir.
  [ ] Migraciones de esquema, con la reconstrucción desde cero probada.
  [ ] Código generado (esquema, OpenAPI, protobuf) versionado y regenerable con un
      comando. Viaja en el mismo commit que su fuente de verdad.
  [ ] Empaquetado reproducible y healthcheck.
  [ ] Walking skeleton end-to-end desplegado.
  [ ] ARRANQUE VERIFICADO: el proceso levanta y responde su healthcheck.

LOOP 1 — POR MILESTONE (días, no semanas)
  Discovery → Requirements → Architecture + ADRs → Design (dominio/API/datos)
  → PLAN.md → Walking skeleton end-to-end

LOOP 2 — POR SLICE VERTICAL (1-3 días)
  Spec del slice → Tests (rojo) → Implementación (verde) → Refactor
  → Security + code review adversarial → Integración → Merge

CONTINUO
  Observabilidad · performance contra SLO · ADRs · documentación viva

POST-RELEASE
  Monitorizar → aprender → alimenta el siguiente LOOP 1

Por qué CI/CD va en LOOP 0: si llega al final, descubres problemas de empaquetado, migraciones y secretos cuando ya no hay margen. Un despliegue vacío el día uno cuesta horas; el mismo problema en la semana ocho cuesta días.

Por qué el último punto no es redundante: compilar no es arrancar. Un build en verde convive sin esfuerzo con una configuración que impide levantar el proceso, y ese fallo aparece cuando ya hay código encima. Levanta el proceso y pégale al healthcheck el primer día.

Por qué el walking skeleton importa: un flujo end-to-end mínimo (un endpoint que atraviesa API → caso de uso → dominio → BD → respuesta) desriesga la integración antes de invertir en features.

Parte III — Estructura documental

docs/
├── 00-agents.md              ← constitución de ingeniería (el más importante)
├── 01-discovery.md           ← qué problema, para quién
├── 02-requirements/          ← uno por capacidad, no un mega-documento
│   ├── CAP-01-ordering.md
│   └── CAP-02-catalog.md
├── 03-architecture.md        ← estructura del sistema
├── 04-design/                ← por capacidad
│   ├── domain-model.md
│   ├── openapi.yaml
│   └── data-model.md
├── adr/
│   ├── 0001-modular-monolith.md
│   └── 0002-outbox-pattern.md
└── operations/
    └── runbook.md

Cuatro documentos raíz. Si tu plantilla de arquitectura tiene 21 secciones obligatorias, nadie la mantiene y en dos meses miente. Un documento desactualizado es peor que ninguno, porque la IA lo lee y le cree.

Parte IV — Los artefactos

00-agents.md — la constitución

Documento de mayor apalancamiento. Corto, imperativo, específico. Si supera 200 líneas, divídelo.

# Contexto del Proyecto — <nombre>

## Qué es
API de <dominio>. Consumidores: <quiénes>. SLO: p99 < 200 ms, 99.9 %.

## Stack
Java 21 · Spring Boot 3.x · Maven · PostgreSQL 16 · JPA · Flyway
Spring Security + JWT · OpenAPI · JUnit 5 · Mockito · Testcontainers · Docker

## Arquitectura
Monolito modular con puertos y adaptadores, organizado por capacidad de negocio.

    com.example.app
    ├── ordering/{domain,application,infrastructure,api}
    ├── catalog/{domain,application,infrastructure,api}
    └── shared/

REGLA DE DEPENDENCIAS: api → application → domain
`domain` no conoce Spring, ni JPA, ni HTTP, ni PostgreSQL. Sin excepciones.

## Reglas no negociables
- Sin lógica de negocio en controllers ni en repositories.
- DTOs en el borde. Las entidades JPA no salen en respuestas.
- Transacciones en la frontera del caso de uso, no en el repositorio.
- Errores tipados en dominio; traducidos a HTTP solo en `api/`.
- Toda I/O con timeout explícito. Prohibido el timeout infinito.
- Logs estructurados con traceId. Prohibido loguear PII, tokens o secretos.
- Toda escritura pública es idempotente (header Idempotency-Key).
- UTC en almacenamiento y transporte. Dinero en enteros (centavos), nunca float.
- La base de datos solo se modifica por migración Flyway.
- Sin abstracciones especulativas, sin microservicios prematuros, sin features no pedidas.

## Testing
TDD obligatorio en `domain` y `application`. Cobertura de dominio ≥ 90 %.
Integración con Testcontainers contra Postgres real, sin mockear repositorios.
Nombres: `should_<comportamiento>_when_<condición>`.

## Comandos
build `mvn verify` · lint `mvn spotless:check` · migrar `mvn flyway:migrate`
No está terminado hasta que `mvn verify` pasa en verde.

01-discovery.md — qué problema y para quién

# 1. Problema actual        (qué duele hoy, en términos de negocio)
# 2. Impacto                (a quién y cuánto le cuesta)
# 3. Usuario objetivo
# 4. Solución propuesta     (una frase, no una arquitectura)
# 5. Actores
# 6. Capacidades de negocio (no operaciones CRUD)
# 7. Restricciones de dominio (horarios, regulación, límites externos)
# 8. Supuestos              → cada uno con: cómo lo valido / qué pasa si es falso
# 9. Preguntas abiertas
# 10. MVP
# 11. Fuera de alcance      → con la razón, no solo el qué
# 12. Criterios de éxito    (medibles)

Dos precisiones que suelen fallar:

• Capacidades, no CRUD. “Crear menú” es una pantalla; “el restaurante mantiene qué puede vender y cuándo” es una capacidad. La diferencia se nota al descomponer en slices.
• Supuesto sin plan de validación = decisión disfrazada. Cada entrada de la sección 8 necesita las dos columnas.

Las reglas de negocio no van aquí. En discovery aún no sabes si “un pedido no se cancela tras confirmarse” es regla real o suposición tuya. Van en requirements.

02-requirements/CAP-XX.md — qué debe hacer

Uno por capacidad, escrito justo antes de construirla. Cuarenta user stories escritas de golpe garantizan que treinta cambien antes de tocarlas.

Capacidad
   ↓
Glosario (lenguaje ubicuo)
   ↓
Business Rules (invariantes)     ← ANTES que los criterios
   ↓
User Stories
   ↓
Acceptance Criteria              ← incluye camino feliz, errores, bordes, concurrencia
   ↓
Máquina de estados
   ↓
NFR específicos (solo excepciones al SLO global)
   ↓
Dependencias e integraciones
   ↓
Requirements Review (adversarial)
   ↓
Approved for milestone N         ← versionado, no congelado

Dos correcciones al orden habitual:

• Business Rules antes que Acceptance Criteria. Los criterios operacionalizan reglas. Al revés, los derivas de tu intuición y luego encajas las reglas a la fuerza.
• Edge cases dentro de los AC, no en una sección aparte. Separarlos convierte el camino feliz en “los requisitos” y los bordes en un apéndice que se recorta cuando aprieta el tiempo.

Ejemplo de AC con bordes integrados:

# AC-012 [BR-007] — Confirmación de pedido
Escenario: Confirmación exitosa
  Dado un pedido BORRADOR con 2 ítems con stock
  Cuando el cliente confirma
  Entonces el pedido pasa a CONFIRMADO
  Y se reserva el stock de ambos ítems
  Y se emite OrderConfirmed exactamente una vez

Escenario: Stock insuficiente
  Dado un pedido BORRADOR con un ítem sin stock
  Cuando el cliente confirma
  Entonces falla con 409 INSUFFICIENT_STOCK
  Y el pedido permanece en BORRADOR
  Y no se reserva stock de ningún ítem

Escenario: Reintento con misma clave de idempotencia
  Dado un pedido confirmado con Idempotency-Key "abc-123"
  Cuando se repite la petición con la misma clave
  Entonces se devuelve la misma respuesta 200 sin efectos secundarios nuevos

Trazabilidad por ID

Numera todo y encadénalo. Convierte preguntas de calidad en consultas mecánicas.

CAP-01 → US-003 → AC-012 → BR-007 → ConfirmOrderUseCase → ConfirmOrderTest

Con esto puedes preguntar “¿qué AC no tiene test?” y obtener una respuesta verificable, no una opinión. Es también el mejor freno contra que la IA invente funcionalidad durante la implementación.

La priorización (Must/Should/Could) no es opcional. Sin ella, “aprobado” significa que todo entra en v1, que es como se muere un MVP.

03-architecture.md — cómo se estructura

Reducido a lo que realmente se consulta:

# 1. Restricciones y objetivos de calidad (con SLOs numéricos)
# 2. Estilo elegido y alternativas rechazadas (con razón)
# 3. Límites de módulos y bounded contexts
# 4. Regla de dependencias
# 5. Arquitectura de datos (¿quién es dueño de qué? ¿joins entre módulos?)
# 6. Arquitectura de errores (dominio → aplicación → HTTP)
# 7. Arquitectura de seguridad (authn, authz por recurso, aislamiento de tenant)
# 8. Observabilidad (qué necesito ver a las 3 a.m.)
# 9. Estrategia transaccional
# 10. Threat model resumido
# 11. Riesgos arquitectónicos
# 12. Índice de ADRs

Dos piezas que casi todos dejan para después y cuestan caro:

Arquitectura de errores — decide la semántica ahora, implementa el @ControllerAdvice después:

OrderNotFound          → 404 NOT_FOUND
UnauthorizedAccess     → 403 FORBIDDEN
InvalidOrderState      → 409 CONFLICT
InvalidRequest         → 400 BAD_REQUEST

Autorización como regla de negocio, antes que como código:

Cliente              → accede solo a sus propios pedidos
Empleado             → accede a pedidos de su restaurante
Dueño                → administra su restaurante
Administrador        → administra la plataforma

ADR — una decisión, un archivo

# ADR-0007: Patrón Outbox para eventos de pedido
Estado: Aceptado · Fecha: 2026-03-14

## Contexto
Confirmar un pedido exige persistirlo y publicar OrderConfirmed. Hacerlo en operaciones
separadas produce escrituras duales: si el broker falla tras el commit, el evento se pierde.

## Decisión
Escribimos el evento en la tabla `outbox` dentro de la MISMA transacción.
Un relay lee la outbox y publica con reintentos.

## Consecuencias
+ Atomicidad real entre estado y evento.
− Latencia adicional (~100-500 ms) y un relay que operar (lag como métrica de alerta).
− Garantía at-least-once: los consumidores deben ser idempotentes.

## Alternativas descartadas
2PC/XA (complejidad operativa desproporcionada) · CDC con Debezium (infraestructura no justificada hoy).

Seis meses después preguntas “¿por qué este proyecto no usa microservicios?” y la respuesta no depende de que nadie recuerde la conversación.

PLAN.md — el plan de slices

Vive en la rama y se marca conforme avanzas. Es el mecanismo más eficaz para que un agente largo no pierda el hilo ni invente alcance.

Cada slice: ≤ 5 archivos, revisable en 15 minutos, deja el sistema compilando y en verde. Orden dentro del slice: tipos de dominio → puertos → caso de uso con tests → persistencia → API → observabilidad.

Parte V — Los seis roles

No uses el mismo prompt para todo. Cada rol abre en sesión nueva: un modelo que acaba de escribir código tiende a defenderlo.

Parte VI — Reglas permanentes de interacción

Incluye este bloque en 00-agents.md. Corrige los dos comportamientos más costosos de la IA programando: expandir el alcance e inventar en vez de preguntar.

ALCANCE
1. Modifica solo los archivos necesarios para el cambio pedido.
2. No refactorices código no relacionado.
3. No actualices dependencias ni añadas librerías sin aprobación explícita.
4. No cambies el contrato público de la API sin actualizar openapi.yaml.
5. No cambies el esquema sin una migración nueva. Nunca edites una ya aplicada.
6. Si el cambio pedido entra en conflicto con la arquitectura: PARA y explica.

INCERTIDUMBRE
7. Si falta información, no inventes. Declara explícitamente:
   UNKNOWN / MISSING INFORMATION / ASSUMPTION / DECISION REQUIRED
8. No tomes decisiones de negocio o arquitectura en silencio.

ENTREGA
9. Con cada cambio entrega: supuestos, decisiones, trade-offs, riesgos y
   cómo verificarlo. No hace falta el razonamiento interno; sí lo auditable.
10. Muestra salida real de comandos ejecutados, no descripciones de lo que debería pasar.

CONFIGURACIÓN
11. Una sola fuente por decisión. Si un valor ya vive en la configuración del
    build, los scripts la invocan, no la repiten.

Parte VII — Prompts esenciales

1. Entrevista de discovery

Adjunto 01-discovery.md (borrador). Actúa como arquitecto senior.
NO propongas solución, NO escribas código, NO diseñes todavía.

Hazme entre 8 y 12 preguntas cuyas respuestas cambiarían la arquitectura.
Priorízalas: primero las caras de revertir si me equivoco.
Para cada una, explica en una línea qué decisión depende de ella.
Hazlas DE UNA EN UNA y espera mi respuesta antes de la siguiente.

El “de una en una” importa: doce preguntas juntas se responden mal y en bloque.

2. Requisitos de una capacidad

Contexto: 00-agents.md + 01-discovery.md. Capacidad: <CAP-XX>.
NO escribas código.

Produce, en este orden:
1. Glosario del dominio.
2. Business rules (invariantes) con ID BR-XXX.
3. User stories con ID US-XXX.
4. Acceptance criteria en Gherkin con ID AC-XXX, citando el BR que verifican.
   Cada US necesita escenarios de: camino feliz, error de negocio, entrada inválida,
   concurrencia y límites.
5. Máquina de estados si la entidad tiene ciclo de vida.
6. Dependencias externas y qué pasa si cada una falla.

Para toda ambigüedad, marca ASSUMPTION / OPEN QUESTION / DECISION REQUIRED
en lugar de elegir en silencio. No inventes requisitos.

3. Evaluación de arquitectura

Actúa como arquitecto principal. Contexto: requisitos aprobados + restricciones.

Evalúa al menos: monolito por capas, monolito modular con puertos y adaptadores,
y microservicios. Para cada uno: complejidad, testabilidad, complejidad operativa,
acoplamiento, propiedad del dato, aislamiento de fallos, velocidad de desarrollo
y coste de revertir la decisión.

No elijas una arquitectura por ser "buena práctica". Elige la adecuada a ESTOS
requisitos y a UN equipo de <N> personas. Optimiza por reversibilidad.

Entrega: recomendación, riesgos, trade-offs, alternativas rechazadas con su razón.
No escribas código.

4. Implementación TDD por slice

Slice: <tarea N de PLAN.md>. Contexto: 00-agents.md, AC-XXX, ADR-000X.

Tres pasos. DETENTE tras cada uno para que yo revise.

PASO 1 — ROJO
Escribe solo los tests derivados de los AC citados (incluidos bordes y errores).
Ejecuta la suite y muéstrame que fallan por la razón correcta, no por error de compilación.

PASO 2 — VERDE
Implementación mínima que los hace pasar. Sin generalizar, sin extras.

PASO 3 — REFACTOR
Mejora nombres y estructura sin cambiar comportamiento. Tests siguen en verde.

No modifiques tests existentes para que pasen. Si un test es incorrecto, dímelo y para.

El paso rojo no es opcional. Un test generado que nunca se vio fallar puede estar verificando nada.

5. Revisión adversarial (sesión limpia)

Actúa como revisor senior escéptico. Tu objetivo NO es aprobar este cambio:
es encontrar por qué fallará en producción.
Adjunto: diff completo, AC relevantes, 00-agents.md.

Revisa y sé específico (archivo:línea):
1. CORRECCIÓN — ¿cumple cada AC? ¿qué caso de borde rompe?
2. CONCURRENCIA — carreras, escrituras perdidas, bloqueos.
3. FALLOS — si la BD o un servicio externo cae a mitad de operación, ¿queda estado
   inconsistente? ¿es reintentable con seguridad?
4. SEGURIDAD — authz por recurso (IDOR), inyección, validación en el borde,
   asignación masiva, secretos, PII en logs, límites de payload.
5. RENDIMIENTO — N+1, índices ausentes, cargas ilimitadas.
6. TESTS — ¿qué comportamiento no está cubierto? ¿hay tests tautológicos o sobre-mockeados?
7. ARQUITECTURA — violaciones de la regla de dependencias.
8. OPERACIÓN — si falla a las 3 a.m., ¿los logs bastan para diagnosticar?

Severidad, impacto concreto y corrección propuesta por hallazgo.
No inventes problemas para rellenar.

6. Auditoría de la suite de tests

Analiza esta suite:
1. ¿Qué AC no está verificado por ningún test?
2. ¿Qué tests pasarían aunque yo rompiera la lógica de negocio?
3. ¿Qué aserciones no podrían fallar nunca en este arnés, porque el dato que
   comprueban no lo produce el doble que sustituye al entorno real?
4. ¿Dónde se verifican llamadas a mocks en lugar de resultados observables?
5. Propón 5 mutaciones al código de producción que la suite NO detectaría.

Las mutaciones son un mutation test manual. Si la suite las sobrevive, la cobertura es ilusoria.

Parte VIII — Estrategia de pruebas

Una aserción vale lo que vale el arnés que la evalúa. Un arnés que sustituye al entorno real —un servidor web simulado, un reloj fijo, un sistema de ficheros en memoria— no produce todo lo que produciría el entorno de verdad. Una aserción sobre algo que ese doble no genera está en verde por ausencia de dato, no por corrección: no comprueba nada y no puede fallar. Cuando la propiedad que verificas la produce la infraestructura y no tu código, compruébala también contra la infraestructura real.

Fakes en memoria, no mocks. Un InMemoryOrderRepository que respeta el contrato del puerto produce tests que sobreviven a refactors; un mock que verifica save() fue llamado una vez, no. El sobre-mocking es la causa número uno de suites verdes sobre código roto.

Parte IX — Quality gates automatizados

Todo lo verificable se automatiza: es lo único que no depende de tu atención en una revisión larga.

gates:
  build:      sin warnings nuevos sin justificación
  lint:       formato y estilo
  tests:      unitarios + integración con Testcontainers
  coverage:   dominio ≥ 90 %  (no cobertura global como objetivo)
  mutation:   score ≥ 70 % en dominio (nocturno)
  arch-test:  la regla de dependencias como test ejecutable (ArchUnit)
  openapi:    esquema válido + detección de cambios incompatibles
  migrations: up y down probados sobre un dump de referencia
  sast:       Semgrep / CodeQL
  deps:       CVEs y licencias
  secrets:    gitleaks sobre el diff

El arch-test merece énfasis: convierte tu regla de dependencias en algo que rompe el build. Es la protección más eficaz contra la deriva arquitectónica cuando el código se genera rápido.

Parte X — Definition of Done

Un checklist que quepa en pantalla se usa; uno de setenta ítems se ignora.

[ ] Cada AC del slice verificado por un test que cita su ID.
[ ] Vi los tests fallar antes de pasar.
[ ] Casos de error, borde y concurrencia cubiertos.
[ ] `mvn verify` en verde: incluye lint, arch-test, SAST, escaneo de dependencias.
[ ] OpenAPI actualizado si cambió el contrato público.
[ ] Migración reversible, probada hacia adelante y hacia atrás.
[ ] Logs, métricas y trazas en los puntos de decisión. Sin PII ni secretos.
[ ] Revisión adversarial pasada en sesión limpia.
[ ] ADR escrito si hubo decisión estructural.
[ ] La documentación que describe esta configuración se actualizó en el mismo commit.
[ ] Revisé el diff completo línea por línea y entiendo cada cambio.

Si no podrías defender este código en una incidencia de producción a las 3 a.m., todavía no es tuyo. Y en producción, será tuyo.

Parte XI — Higiene de trabajo

• Una sesión, una tarea. El contexto acumulado degrada más de lo que ayuda.
• Sesión nueva para revisar. El autor no es buen crítico de sí mismo.
• Documentos vivos, no historial de chat. Lo que debe persistir va a 00-agents.md o a un ADR.
• Referencia archivos, no pegues código. Deja que el agente lea lo que necesite del repositorio.
• Un slice = un commit. Facilita revertir cuando la IA se desvía.
• Verifica, no creas. Exige salida de comandos, no promesas.

Parte XII — Dónde no delegar

Zonas donde el coste de un error supera el ahorro de tiempo. La IA sigue siendo útil aquí como revisora y generadora de casos adversariales; no como autora sin supervisión.

• Límites de agregados y bounded contexts — definen el acoplamiento de todo el sistema.
• Modelado de dinero, impuestos y redondeo.
• Criptografía y manejo de secretos. Usa primitivas estándar; nunca aceptes esquemas propios.
• El modelo de autorización — es una decisión de producto.
• Migraciones destructivas sobre datos de producción.
• Concurrencia fina (locks, memoria compartida).

Anexo — Antipatrones

De arquitectura Modelo anémico con toda la lógica en “services” · interfaces de una sola implementación que no son puertos · repositorios que devuelven entidades JPA hacia arriba · lógica de negocio en controllers o triggers · microservicios prematuros.

De configuración y entorno Configuración sin defaults: solo arranca en la máquina de quien la escribió · host escrito a mano en algo que se despliega en contenedor · endpoints de administración con capacidad de escritura expuestos por defecto · la misma decisión configurada en dos sitios · código generado commiteado aparte de su fuente de verdad.

De proceso con IA Pedir implementación sin contrato ni criterios de aceptación · aceptar tests sin verlos fallar · aserciones que el arnés de test no puede evaluar y por tanto nunca fallan · dejar que la IA elija las abstracciones · revisar con la misma sesión que escribió el código · plantillas documentales tan grandes que nadie las mantiene · escribir todos los requisitos del producto antes de construir el primero.