Objetivo del tema: que la calidad la vigilen tests que genera la IA y que ningún issue llegue a develop sin pasar una revisión. Al acabar, cerrar un issue es /git-flow finalizar y todo lo demás ocurre solo, y un CRUD nuevo es una sola orden.

Las reglas de arquitectura (las de Programación y DWS: capas, nombres, sin ciclos, domain sin Spring) las hace cumplir ArchUnit con tests que fallan cuando una clase está donde no debe. Lo nuevo es que los escribe la IA a partir de las reglas en castellano:

/test-arquitectura
- Las clases de controller solo dependen de domain.
- Las de persistence solo dependen de domain.
- Nada en domain importa org.springframework ni jakarta.persistence.
- Los controladores acaban en Controller y están en ..controller..
- Los repositorios de persistence acaban en RepositoryImpl e implementan una interfaz de domain.
- Sin ciclos entre paquetes.

Cada test lleva en su @DisplayName y en un comentario qué comprueba, por qué y las excepciones:

@Test
@DisplayName("domain no depende de Spring: el dominio tiene que compilar y probarse sin el framework")
void domainSinSpring() {
    noClasses().that().resideInAPackage("..domain..")
        .should().dependOnClassesThat().resideInAPackage("org.springframework..")
        .check(clases);
}

No hay un documento aparte con la arquitectura. Mantener un Markdown sincronizado con los tests es un trabajo que nadie hace, así que la fuente de verdad son los tests con su descripción. Para cambiar una regla se le pide a la skill que cambie el test. Cuando se añade una regla que el código actual aún no cumple, FreezingArchRule.freeze(regla) congela las violaciones existentes y solo falla con las nuevas.

Los criterios de aceptación del plan son frases comprobables. /test-e2e las convierte en tests de Playwright en TypeScript, frontend/e2e/<entidad>.spec.ts, y los deja pasando:

/test-e2e planes/12-alta-clientes.md

Cómo trabaja: lee los criterios, abre la aplicación del worktree con el Playwright MCP para ver qué hay en pantalla, escribe el test y lo ejecuta; si falla por un selector o un texto, lo arregla y lo vuelve a pasar. La IA interviene al generar, no al ejecutar: lo que queda en el repositorio es un .spec.ts normal, determinista, que CI ejecuta sin ninguna IA.

Reglas que la skill tiene que respetar (están en convenciones-frontend):

• Selectores por data-testid y por rol (getByRole, getByLabel), nunca por clase CSS. Un test que depende del CSS se rompe al primer cambio de estilo.
• Un test por criterio de aceptación, con el criterio como nombre del test.
• Los tests cuentan con los datos de prueba del tema 3 y se pasan sobre la base de datos recién reseteada (docker compose down -v && docker compose up -d).

Sin pull request nadie mira el código antes de que llegue a develop. Lo mira la IA. /revisar compara el diff de la rama contra develop con dos cosas:

• El plan del issue: ¿hace lo que se pidió, y como se pidió? ¿Falta algún criterio de aceptación? ¿Ha hecho cosas que no estaban en el plan?
• Las skills de convenciones: ¿está en las capas correctas, con los nombres correctos, con migración y datos de prueba, con data-testid?

Y clasifica cada cosa que encuentra en grave (no cumple el plan, rompe una convención, falta un test) o mejorable. /git-flow finalizar lanza /revisar como primer paso y no fusiona si hay algo grave: enseña la revisión y se para. El alumno corrige (o le pide al agente que corrija) y vuelve a finalizar.

Los CRUD de este proyecto son siempre iguales: solo cambian la entidad y sus campos. Cuando el «cómo» no cambia, no hace falta un plan cada vez; hace falta una skill que tenga el «cómo» escrito:

/crud Pedido
Campos: numero (texto, único, obligatorio), fecha (fecha, obligatoria),
cliente (relación con Cliente, obligatoria), total (decimal, >= 0).

Y genera lo mismo que tiene el CRUD de referencia: migración V<n>__pedidos.sql, entidad, repositorio, servicio, controlador y DTO en sus capas, listado y formulario en Angular con sus rutas y validaciones, R__pedidos.sql con datos de prueba y los tests E2E del listado y del formulario.

La skill se construye a partir del CRUD del tema 4: se le pide al agente que lo lea y escriba /crud con el procedimiento (qué ficheros crea, en qué orden, cómo se nombran) y con ese CRUD como ejemplo de referencia dentro de la skill, en un fichero aparte que carga cuando la ejecuta.

La lección va más allá del CRUD: lo que se repite, se convierte en una skill. Si la tercera vez que se pide algo sale distinto de las dos anteriores, es que faltaba la skill.

• Crea un issue «Tests de arquitectura» e inícialo.
• Escribe la skill /test-arquitectura: recibe reglas en castellano y genera los tests ArchUnit en backend/src/test, cada uno con @DisplayName y comentario con qué comprueba, por qué y las excepciones.
• Lánzala con las seis reglas del tema. mvn test tiene que pasar.
• Mueve a mano el servicio del CRUD al paquete controller y comprueba que mvn test falla con el mensaje del test. Deshazlo.
• Finaliza el issue.

• Crea un issue «Tests E2E del CRUD» e inícialo.
• Instala Playwright en frontend/ (npm init playwright@latest) configurado contra http://localhost:$FRONTEND_PORT.
• Escribe la skill /test-e2e: recibe un fichero de plan, resetea la base de datos, abre la aplicación con el MCP de Playwright, escribe un .spec.ts por criterio de aceptación y lo ejecuta hasta que pase.
• Lánzala con el plan del CRUD del tema 4. npx playwright test tiene que pasar dos veces seguidas con la base de datos reseteada entre medias.
• Finaliza el issue.

• Crea un issue «Revisión por IA» e inícialo.
• Escribe la skill /revisar: diff de la rama contra develop, comparación con el plan del issue y con las skills de convenciones, salida clasificada en grave / mejorable.
• Amplía /git-flow finalizar para que lance /revisar primero y se pare si hay algo grave.
• Finaliza el issue.

• Crea un issue para la segunda entidad de tu proyecto e inícialo.
• Escribe la skill /crud a partir del CRUD del tema 4: procedimiento con los ficheros que crea y en qué orden, y el CRUD de referencia como ejemplo en un fichero aparte dentro de la skill.
• Lánzala: /crud <Entidad> con sus campos. Comprueba que genera migración, capas, frontend, datos de prueba y tests E2E, y que todo pasa.
• Quita a mano del plan un criterio de aceptación sin quitar su código y lanza /git-flow finalizar. /revisar tiene que marcarlo como grave y la fusión no debe hacerse. Restaura el plan y finaliza.