Diferencias

Muestra las diferencias entre dos versiones de la página.

--- clase:daw:daw-proyecto:tema05 [2026/10/14 12:01] – Orden sustantivo-verbo en todos los subcomandos (/test unit run, /developer code review); los tests siempre por tipo, sin «todos» claude
+++ clase:daw:daw-proyecto:tema05 [2026/10/14 14:08] (actual) – Tema nuevo «2. IA y agentes»: los temas 2 a 7 pasan a ser 3 a 8, con sus referencias cruzadas renumeradas claude
@@ Línea 1: / Línea 1: @@
-====== 5. Automatizando el proyecto con IA ======
+====== 5. IA en el proyecto ======
-Objetivo del tema: que la calidad la vigilen **tests que genera la IA** en los cuatro niveles (arquitectura, unitarios, API y E2E) y **revisiones que hace la IA** antes de cerrar un issue. Al acabar, ''/git-flow finish'' no cierra nada que no tenga los tests en verde y la revisión limpia, y todo lo demás ocurre solo.
+Objetivo del tema: usar bien al agente para programar. No se enseña a programar; se enseña a **pedir** el trabajo como una especificación y a comprobar que ha salido bien. Al acabar, el proyecto tiene su primer CRUD completo hecho así y la arquitectura del proyecto escrita donde el agente la lee antes de diseñar nada.
-Dos skills nuevas, con la gramática del tema 1:
+Lo que ya está contado en el [[cursos:sdd:start|curso de programación con IA]] y aquí no se repite: qué es el [[cursos:sdd:10-spec-driven-development|Spec-driven development]] y por qué encaja con los agentes, [[cursos:sdd:11-kiro|cc-sdd (Kiro)]] con sus fases y su memoria del proyecto, y la [[cursos:sdd:04-ingenieria#ingenieria_de_contexto|ingeniería de contexto]].
-^ Skill ^ Sustantivos ^ Verbos ^
+===== Dos caminos: spec para los CRUD, plan para el resto =====
-| ''/test'' | ''unit'', ''arch'', ''api <Entidad>'', ''e2e'' | ''create'', ''run'', ''repair''. Siempre con el tipo delante: no hay un «todos» |
-| ''/developer'' | ''code'', ''test'', ''ci'' (el ''ci'' llega en el tema 6) | ''review'' |
-===== Los cuatro tipos de tests =====
+En este proyecto hay dos clases de issue y cada una tiene su camino:
-^ Tipo ^ Qué prueba ^ Con qué ^ Necesita ^ Lo ejecuta ^
+  * **Un CRUD** (una entidad con su listado, alta, edición y borrado) va por **especificación**: requisitos, diseño y tareas en ficheros, generados por cc-sdd y revisados por el alumno. Un CRUD tiene una forma conocida y la spec, con el steering, es lo que garantiza que sale igual que los demás.
-| ''arch'' | Que cada clase está en su capa y depende de lo que debe | ArchUnit | Nada | ''mvn test'', dentro del build |
+  * **Todo lo demás** (un filtro, un informe, una regla de negocio, un cambio en una pantalla) va por **plan**: en modo plan se le dice al agente lo que se quiere y él escribe un fichero ''plan_<algo>.md'' con las tareas; el alumno lo revisa y, en otra conversación, se implementa con ''/code impl''. Es trabajo pequeño y variado: una spec entera sería más papel que código.
-| ''unit'' | La lógica del dominio, servicio a servicio | JUnit 5 y Mockito, sin Spring | Nada | ''mvn test'', dentro del build |
-| ''api'' | Cada endpoint de verdad: HTTP, código de estado y JSON | Playwright (fixture ''request'') | La aplicación del worktree levantada y la base de datos reseteada | ''npm run test:api'', fuera del build |
-| ''e2e'' | La aplicación completa desde el navegador, criterio a criterio | Playwright con Chromium | Lo mismo | ''npm run test:e2e'', fuera del build |
-Los dos primeros forman parte del build de Maven: corren en cada compilación y no necesitan nada levantado. Los dos últimos **no forman parte del build**: son lentos, necesitan la aplicación y se lanzan cuando se quiere. Los comandos son los mismos para el alumno, para el agente y para CI (tema 6); lo que añade ''/test'' es no tener que recordarlos y, cuando algo sale en rojo, que el agente lo explique.
+En los dos, la regla es la misma: primero un fichero que el alumno lee y corrige, después la implementación con el contexto limpio.
-===== Crear los tests: /test <tipo> create =====
+La spec la genera **cc-sdd** (la versión libre del flujo de Kiro), pero el alumno no escribe sus comandos: los envuelve una skill del proyecto, ''/sdd'', con dos subcomandos. Así el vocabulario es el del tema 1 y no el de la herramienta. cc-sdd se instala una vez en la raíz del repositorio:
-==== arch: tests de arquitectura con ArchUnit ====
-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. Es el único ''create'' que se lanza una vez por proyecto, no por issue:
 <code>
-/test arch create
+npx cc-sdd@latest --claude-skills --lang es      (OpenCode: --opencode-skills)
-- 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.
 </code>
-Cada test lleva en su ''@DisplayName'' y en un comentario **qué comprueba, por qué y las excepciones**:
+Ese es el flujo de cada issue:
-<sxh java>
+<uml>
-@Test
+start
-@DisplayName("domain no depende de Spring: el dominio tiene que compilar y probarse sin el framework")
+:/git-flow start N
-void domainSinSpring() {
+y ./app.sh start;
-    noClasses().that().resideInAPackage("..domain..")
+if (¿es un CRUD?) then (sí)
-        .should().dependOnClassesThat().resideInAPackage("org.springframework..")
+  :/sdd spec create
-        .check(clases);
+  requisitos, diseño y tareas
-}
+  en .kiro/specs/N-slug/;
-</sxh>
+  :Leer y corregir los tres ficheros;
+  :/clear y /git-flow update;
+  :/sdd spec impl
+  una tarea tras otra;
+else (no)
+  :Modo plan: el agente lee el código
+  y escribe plan_<algo>.md;
+  :Leer y corregir el plan;
+  :/clear y /git-flow update;
+  :/code impl plan_<algo>.md
+  una tarea tras otra;
+endif
+:Tests unitarios y de arquitectura
+después de cada tarea;
+:Probar en el navegador;
+stop
+</uml>
-**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.
+==== /sdd spec create ====
-==== unit: tests unitarios con JUnit ====
+Se lanza en el worktree del issue, sin argumentos: el número del issue está en el nombre de la rama. Lo que hace, por dentro, son las cuatro fases de cc-sdd encadenadas:
-Los tests unitarios prueban la lógica del dominio **sin Spring y sin base de datos**: un servicio con sus repositorios sustituidos por mocks de Mockito. Son los más rápidos y los que mejor localizan un error.
+  - ''/kiro-spec-init'' con el título y el cuerpo del issue (''gh issue view N'').
+  - ''/kiro-spec-requirements'': los requisitos y los **criterios de aceptación**.
+  - ''/kiro-spec-design -y'': el diseño, leyendo antes el //steering// con la arquitectura del proyecto (abajo).
+  - ''/kiro-spec-tasks -y'': la lista de tareas, en orden y pequeñas.
-<code>
+Y se para. El resultado son tres ficheros en ''.kiro/specs/<N>-<slug>/'': ''requirements.md'', ''design.md'' y ''tasks.md''. Antes de generar nada, si el issue no deja claro algo (¿el NIF es único?), pregunta.
-/test unit create PedidoService
-</code>
-Lo que hace: lee la clase, identifica cada comportamiento (lo que devuelve, lo que valida, lo que lanza) y escribe un test por comportamiento en ''backend/src/test/java'', con el mismo paquete, ''@DisplayName'' en castellano que diga el caso y Mockito para las dependencias. Los ejecuta y se para si alguno falla por un error del código, en vez de retocar el test para que pase.
+**Revisar esos ficheros es el trabajo humano del flujo.** Es mucho más barato corregir una frase de la spec que corregir el código que sale de ella. Qué mirar en cada uno:
-Qué no prueban: controladores ni repositorios. Eso es de los tests de API.
+^ Fichero ^ Qué tiene que tener ^
+| ''requirements.md'' | Los criterios de aceptación en frases **comprobables** («al guardar un cliente sin NIF, el formulario muestra el error y no se crea»), y entre ellos **los casos de error**: campo vacío, valor repetido, id que no existe. En el tema 6 cada frase se convierte en un test |
+| ''design.md'' | Que es **igual** que el CRUD de referencia del proyecto: las mismas capas, los mismos nombres, migración y datos de prueba. Si no lo es, lo que falla no es el diseño sino el steering (abajo): se corrige el steering y se vuelve a generar |
+| ''tasks.md'' | Tareas pequeñas y en orden: migración y datos, backend, frontend. Cada una se puede hacer y probar sola |
-==== api: tests de API con Playwright ====
+Si se cambia algo en ''requirements.md'', se vuelve a lanzar ''/sdd spec create'': rehace el diseño y las tareas a partir de los requisitos corregidos. Se repite hasta que los tres ficheros digan lo que se quiere.
-Los tests de API prueban cada endpoint **de verdad**: peticiones HTTP contra el backend del worktree, comprobando el código de estado y el JSON. Se escriben con Playwright, igual que los E2E (mismo lenguaje, misma configuración, misma carpeta): Playwright trae para esto el fixture ''request'', que hace peticiones sin abrir ningún navegador.
+==== /sdd spec impl ====
+Conversación nueva (''/clear'') y una sola orden:
 <code>
-/test api create Pedido
+/sdd spec impl
 </code>
-Por cada endpoint del controlador, en ''frontend/tests/api/pedidos.spec.ts'', un test del caso bueno y uno por cada error que la spec o las validaciones prevén: ''400'' con un campo obligatorio vacío, ''404'' con un id que no existe, ''409'' con un valor único repetido. Los datos de partida son los del ''%%R__%%'' de la entidad; los tests que escriben se limpian a sí mismos (borran lo que crean) para que se puedan pasar dos veces seguidas.
+Por dentro es ''/kiro-impl'' sobre las tareas pendientes de la spec del worktree, una detrás de otra. Después de cada tarea pasa los tests unitarios y de arquitectura (''/test unit run'', tema 6) y la marca como hecha en ''tasks.md''. Si un test falla por un error del código, se para en esa tarea y lo dice, en vez de retocar el test para que pase. Cuando termina, el alumno prueba la aplicación en la URL del worktree y, si algo no está bien, se le pide en la misma conversación.
-<sxh typescript>
+Solo implementa la spec. Los planes (abajo) y las correcciones de una revisión (tema 6) se hacen con ''/code impl''.
-test('POST /api/pedidos sin número devuelve 400 y el nombre del campo', async ({ request }) => {
-  const res = await request.post('/api/pedidos', { data: { fecha: '2026-10-14', clienteId: 1 } });
-  expect(res.status()).toBe(400);
-  expect((await res.json()).errores.numero).toBeDefined();
-});
-</sxh>
-Los de API y los E2E son dos **proyectos** del mismo ''playwright.config.ts'', separados por carpeta; el de API no necesita navegador:
+Por qué el ''/clear'' entre los dos: la conversación de especificar arrastra todo lo que el agente ha leído y descartado mientras pensaba. Ese ruido empeora el resultado y encarece cada petición. Con la spec en ficheros, esa conversación es desechable.
-<sxh typescript;title:frontend/playwright.config.ts>
+==== El modo plan y /code impl: lo que no es un CRUD ====
-export default defineConfig({
-  use: { baseURL: process.env.BASE_URL ?? 'http://localhost:4200' },
-  projects: [
-    { name: 'api', testDir: 'tests/api' },
-    { name: 'e2e', testDir: 'tests/e2e', use: { browserName: 'chromium' } },
-  ],
-});
-</sxh>
-==== e2e: tests E2E con Playwright ====
+Claude Code y OpenCode tienen un **modo plan** en el que el agente solo lee: explora el código, piensa y propone, pero no toca nada. En Claude Code se entra con ''Shift+Tab'' hasta que la barra dice //plan mode//; en OpenCode, con la tecla ''Tab'' ([[cursos:sdd:03-opencode#plan_y_buildla_tecla_tab|Plan y Build]]). Es el camino de los issues que no son un CRUD:
-Los tests E2E prueban la aplicación completa desde el navegador, como lo haría el usuario. Los criterios de aceptación de ''requirements.md'' son frases comprobables; ''e2e'' las convierte en tests de Playwright en TypeScript, ''frontend/tests/e2e/<entidad>.spec.ts'', y los deja pasando. No necesita argumento: la spec es la del worktree.
+  - En el worktree del issue, modo plan, y se le dice lo que se quiere (lo que pone el issue) y que escriba el plan como **lista de tareas** (''- [ ] ...'') en ''plan_<algo>.md'', por ejemplo ''plan_filtro-provincia.md''. El agente lee el código, pregunta lo que le falte y escribe el fichero: es lo único que escribe en modo plan.
+  - Se sale del modo plan. El fichero queda en el worktree.
+  - Se lee y se corrige a mano, igual que una spec: tareas pequeñas, en orden, y que no falte ninguna pantalla ni ningún caso de error.
+  - **Conversación nueva** (''/clear'') y se implementa:
 <code>
-/test e2e create
+/code impl plan_filtro-provincia.md
 </code>
-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.
+Por qué en dos conversaciones y no seguidas: al planificar, el agente ha leído medio proyecto y ha descartado alternativas, y todo eso sigue en el contexto. Si implementa en la misma conversación, programa con ese ruido. Con el plan en un fichero, la conversación de planificar se tira y la de implementar empieza limpia, solo con el plan. Es la misma razón del ''/clear'' entre ''spec create'' y ''spec impl''.
-Reglas que la skill tiene que respetar (están en ''convenciones-frontend''):
+''/code impl <plan>'' hace las tareas pendientes del fichero, una detrás de otra, y las va marcando; después de cada una pasa los tests unitarios y de arquitectura y, si uno falla por el código, se para y lo dice. Es lo que hace ''/sdd spec impl'' con ''tasks.md'', pero para cualquier lista de tareas en markdown: en el tema 6 se usa también con la revisión.
-  * 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.
+La skill ''/code'' nace en este tema con el verbo ''impl''; en el tema 6 se le añade ''review''.
-  * 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**.
-===== Ejecutarlos: /test <tipo> run =====
+==== La carpeta de la spec ====
-Ejecuta los tests de un tipo y, si algo sale en rojo, lo explica: qué test, qué esperaba, qué ha pasado y dónde mirar. Por dentro son los comandos del tema 3, que es lo que ejecuta CI sin ninguna skill:
+''.kiro/specs/'' se sube a git: la spec viaja con la rama, entra en ''develop'' en el mismo commit que el código, y las skills del tema 6 la usan para generar los tests y para revisar que el código hace lo que se pidió.
-^ Verbo ^ Comando ^
+Es un **registro** de lo que se pidió, no documentación: cuando el código cambie después, la spec no se actualiza. Para que el agente no se confunda con specs viejas, ''AGENTS.md'' lleva esta línea:
-| ''/test arch run'' | ''mvn test -Dtest='*ArchTest''' desde ''backend/'' |
-| ''/test unit run'' | ''mvn test -Dtest='!*ArchTest''' desde ''backend/'' |
-| ''/test api run'' | ''npm run test:api'' desde ''frontend/'' (resetea la base de datos y levanta la aplicación antes) |
-| ''/test e2e run'' | ''npm run test:e2e'' desde ''frontend/'' (igual) |
-No hay un «todos» a propósito: los tipos se lanzan **uno a uno**, en ese orden, para saber en cada momento qué se está probando y contra qué. Para que ''arch'' y ''unit'' se puedan separar, los tests de ArchUnit acaban en ''ArchTest'' y los unitarios en ''Test''. En ''/sdd spec impl'' es ''/test unit run'' lo que pasa después de cada tarea.
+<code>
+.kiro/specs/ es histórico: la fuente de verdad es el código. No leas specs de otros issues salvo que te lo pidan.
+</code>
-===== Repararlos: /test <tipo> repair =====
+==== La skill /sdd ====
-Pasa mucho: se cambia algo del código, se refactoriza, y se rompen tests, sobre todo los E2E. ''repair'' pasa los tests de un tipo y, por cada uno que falla, decide **qué está mal, el test o el código**, y arregla lo que corresponda:
+Es corta, porque el trabajo lo hacen los comandos de cc-sdd. Recibe el subcomando en ''$ARGUMENTS'' y hace una cosa u otra:
-<code>
+<sxh yaml;title:.claude/skills/sdd/SKILL.md (cabecera)>
-/test e2e repair
+---
-</code>
+name: sdd
+description: Especificar e implementar el issue del worktree actual con cc-sdd. Subcomandos: "spec create" (requisitos, diseño y tareas en .kiro/specs/N-slug/) y "spec impl" (implementa las tareas pendientes).
+allowed-tools: Bash(gh issue view:*), Bash(git branch:*), Bash(mvn:*), Read, Write, Edit, Skill
+---
+</sxh>
-El criterio es la **intención**:
+Todas las skills de tarea del proyecto son así: ''/<familia> <sustantivo> <verbo>'', con el subcomando en los argumentos. Es lo que hace que ''/test e2e run'' y ''/test e2e create'' sean la misma skill con dos subcomandos.
-  * Un test está desactualizado solo si un cambio **intencionado** del código (un commit, o un cambio sin commitear que el alumno ha hecho a propósito) modificó o eliminó lo que el test comprueba: el texto de un mensaje, un campo, un flujo. Entonces se actualiza el test.
+===== El primer CRUD =====
-  * Sin un cambio intencionado que lo justifique, el fallo es una **regresión**: se arregla el código y el test no se toca.
-  * Si no se sabe, **no se toca nada** y se pregunta.
-Y tres reglas que no se negocian, porque sin ellas «reparar» acaba siendo «hacer que pase»:
+La práctica central del tema es el primer CRUD del proyecto, hecho con ''/sdd''. Pero hay un problema de huevo y gallina: el diseño tiene que salir como la arquitectura del proyecto, y la arquitectura todavía no está escrita en ningún sitio que el agente lea.
-  * Nunca quita, comenta ni relaja una aserción, salvo que el cambio intencionado lo obligue. Nunca crea tests nuevos: para eso está ''create''.
+Se resuelve con el primer CRUD y solo con él: se genera la spec, y en ''design.md'' el alumno **corrige a mano** todo lo que no sea la arquitectura que ya conocéis de Programación y DWS (capas ''controller'' / ''domain'' / ''persistence'', ''Repository'' definido en ''domain'' e implementado en ''persistence'', DTO ''XxxRequest'' / ''XxxResponse'', ''XxxJpaEntity'', MapStruct, ''ApiExceptionHandler''). Aquí no se inventa una arquitectura nueva. Después de implementarlo se lee **clase por clase** y se corrige hasta que esté como tiene que estar: es el código de referencia de todo lo que viene después, y de él sale el steering.
-  * Borra un test solo si lo que comprobaba ya no existe en la aplicación, y entero, no vaciado ni comentado.
-  * Un test cada vez, sin commits, y al final una tabla: test, diagnóstico (desactualizado / regresión / sin determinar) y qué se ha cambiado. El alumno la lee y decide si está de acuerdo.
-''repair'' deja un fichero de estado junto a la spec, ''repair.md'', con una línea ''- [x]'' / ''- [ ]'' por test; si se interrumpe, al relanzarlo sigue por donde iba.
+===== El steering: las dos arquitecturas =====
-===== Las revisiones: /developer <qué> review =====
+Para que el segundo CRUD salga igual que el primero **de verdad**, con las mismas capas, los mismos nombres y los mismos tests, no basta con pedirlo bien: el agente tiene que tener la arquitectura escrita y leerla antes de diseñar. Eso es el //steering// de cc-sdd, y ''/sdd spec create'' lo carga en la fase de diseño. Cómo funciona está en [[cursos:sdd:11-kiro#la_memoria_del_proyecto|la memoria del proyecto]]; aquí solo lo que es de este proyecto: que tiene **dos arquitecturas**, la del cliente y la del servidor, y cómo se le cuentan.
-Sin pull request nadie mira el código antes de que llegue a ''develop''. Lo mira la IA, con dos revisiones que **no tocan nada y no bloquean**: escriben lo que encuentran en ''review.md'', junto a la spec, y las correcciones las añaden como tareas nuevas a ''tasks.md''. Después, el alumno lee, decide y las correcciones se hacen con el comando de siempre, ''/sdd spec impl''. Se pueden relanzar las veces que haga falta: marcan como resueltos los hallazgos que ya no aparecen y añaden los nuevos.
+==== Cuándo se genera ====
-==== code review: el código contra la spec y las reglas ====
+''/kiro-steering'' describe lo que ve en el código. Por eso se lanza **después del primer CRUD**, ya revisado, y no antes: con el esqueleto vacío describiría nada, y con un CRUD mal hecho convertiría el error en norma. Se lanza una vez, a mano, en la raíz del repositorio:
 <code>
-/developer code review
+/kiro-steering
 </code>
-Compara el diff de la rama contra ''develop'' con tres cosas:
+Los tres ficheros que genera, ''product.md'', ''tech.md'' y ''structure.md'', entran en el contexto **siempre**, en todas las fases de todas las specs. Así que se revisan y se dejan cortos, con solo lo común: qué es el proyecto, que es Spring Boot más Angular más MariaDB, el reparto ''backend/'' y ''frontend/'', los comandos de arrancar y probar y las dos ramas.
-  * **La spec 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 la spec?
+==== Dos arquitecturas, dos ficheros ====
-  * **Las convenciones** (''convenciones-backend'', ''convenciones-frontend'', que remiten al steering): ¿está en las capas correctas, con los nombres correctos, con migración y datos de prueba, con ''data-testid''?
-  * **Las reglas de calidad** de ''calidad-codigo'' (abajo): ¿es código bueno, además de correcto?
-Cada hallazgo lleva la **regla** incumplida, el **sitio** (''fichero:línea'') y el **coste** del código tal como está (qué se duplica, qué no se puede probar, qué se rompe al cambiarlo). **Sin coste no hay hallazgo**: eso separa un defecto de una preferencia. Antes de proponer cambiar la **forma** de algo sin cambiar lo que hace (extraer, mover, renombrar), mira cómo lo resuelven tres clases hermanas; si lo hacen igual, es una convención del proyecto y no se reporta. Y clasifica en **grave** (no cumple la spec, rompe una convención, falta un test, o una regla con coste claro) y **mejorable**.
+Lo específico de cada parte no va en esos tres, sino en dos ficheros de steering **condicionales**, que solo entran en el contexto cuando la spec toca esa carpeta. Se crean con ''/kiro-steering-custom'' y llevan en la cabecera el patrón de ficheros que los activa:
-Un hallazgo bien hecho y dos mal hechos:
+<sxh plain;title:.kiro/steering/backend.md>
+---
+inclusion: fileMatch
+fileMatchPattern: "backend/**"
+---
+# Arquitectura del servidor
+...
+</sxh>
-<code>
+Y ''frontend.md'' igual, con ''%%frontend/**%%''. **Concretar las dos arquitecturas es trabajo del alumno**: ''/kiro-steering-custom'' pone la cabecera y un borrador; el contenido se escribe mirando el CRUD de referencia, y tiene que responder a esto:
-GRAVE  PedidoService.java:48  metodos.md «cálculo puro y efectos secundarios»
-       calcularTotal() lee los pedidos de la base de datos y los suma en el mismo método.
-       Coste: no se puede probar la suma sin base de datos; el test unitario actual la monta entera.
-MAL    "extraer las líneas 20-24 a un método privado para mejorar la legibilidad"
+^ ''backend.md'' ^ ''frontend.md'' ^
-       (no mira las clases hermanas: todos los servicios lo escriben así; y no dice qué cuesta)
+| Las capas ''controller'' / ''domain'' / ''persistence'' y qué va en cada paquete | Carpeta por entidad y qué componentes tiene (listado y formulario) |
-MAL    "el método es demasiado largo"
+| Nombres: ''XxxController'', ''XxxService'', ''Xxx'' (dominio), ''XxxRepository'' en ''domain'' y ''XxxRepositoryImpl'' en ''persistence'', ''XxxJpaEntity'', ''XxxRequest'' / ''XxxResponse'', el mapper de MapStruct | Nombres de ficheros, de componentes y de rutas (''/clientes'', ''/clientes/nuevo'', ''/clientes/:id'') |
-       (sin regla ni coste: es una opinión)
+| Dónde se valida (Bean Validation en el ''Request'') y cómo se devuelven los errores: ''ApiExceptionHandler'', códigos 400 / 404 / 409 y el formato del JSON de error | El servicio HTTP de cada entidad y cómo se llama a la API |
-</code>
+| Migraciones ''%%V<n>__%%'' y datos de prueba ''%%R__%%'', con un ejemplo | Formularios reactivos y cómo se muestran las validaciones |
+| Cómo se prueban los unitarios: JUnit 5 y Mockito, sin Spring | ''data-testid'' en todo lo que un test toca, nunca selectores por clase CSS |
-Los graves van a ''tasks.md'' como tareas. Los mejorables se quedan en ''review.md'' y el alumno decide: o los convierte en tarea o los cierra a mano con un «no se hace, es así a propósito». Un hallazgo cerrado así no bloquea nada.
+La lección: **lo que el steering no dice, el agente lo inventa distinto cada vez.** Si el segundo CRUD sale distinto del primero, falta una línea en el steering, no un prompt mejor.
-<note important>El alumno lee la revisión. El código lo ha escrito la IA, pero el commit lo firma él y es responsable de lo que hay en ''develop''. La revisión es una ayuda para leer, no una excusa para no leer.</note>
+==== Las skills de convenciones ====
-==== calidad-codigo: las reglas ====
+El steering solo lo leen los comandos de cc-sdd. Las demás skills del proyecto (''/test'', ''/code'') también necesitan saber cómo se escribe el código aquí. Para eso hay dos **skills de conocimiento** (no se invocan: el agente las carga solo cuando va a tocar backend o frontend) que no repiten nada: remiten al steering.
-''code review'' sabe si el código es **bueno** porque carga una skill de **conocimiento** con las reglas de calidad: métodos que hacen tres cosas, clases que se conocen demasiado, comentarios que repiten el código, tests que copian los valores que prueban. Se escribe una vez y se va completando cuando una revisión saca algo que no estaba. ''SKILL.md'' lleva la máxima y el índice; cada grupo de reglas, en su fichero:
+<sxh yaml;title:.claude/skills/convenciones-backend/SKILL.md>
+---
+name: convenciones-backend
+description: Cómo se escribe el código del backend en este proyecto (capas, nombres, DTO, migraciones, tests). Cargar siempre antes de crear, modificar o revisar cualquier clase Java, test de Java o fichero SQL.
+---
+Lee .kiro/steering/backend.md y aplícalo. Es la única fuente de la arquitectura del servidor.
+</sxh>
-<code>
+Y ''convenciones-frontend'' igual, hacia ''frontend.md''. Una sola fuente: cuando cambia una convención, cambia en un sitio.
-.claude/skills/calidad-codigo/
-├── SKILL.md          <- la máxima, el orden de prioridades y la tabla de ficheros
-├── metodos.md
-├── clases.md
-├── comentarios.md
-└── tests.md
-</code>
-**La máxima**: el código se escribe para que **una persona lo entienda al leerlo** y para que **un agente lo pueda modificar sin equivocarse**. Consecuencia que lo cambia todo: una repetición pequeña y visible es aceptable; una indirección para ahorrar dos líneas (un método que solo reenvía, un genérico) no lo es, porque el agente no olvida los dos sitios que hay que tocar y la persona sí pierde el hilo.
+===== El contexto del agente =====
-Cuando dos reglas chocan, gana la primera de esta lista: mantenibilidad, testabilidad, determinismo, separación de responsabilidades.
+El contexto es todo lo que el modelo tiene delante en una conversación: ''AGENTS.md'', las skills cargadas, el steering, los ficheros que ha leído, la salida de los comandos que ha ejecutado y todo lo que se ha hablado. Cada mensaje lo reenvía entero. Cuanto más lleno, peor trabaja y más cuesta. Reglas:
-^ Fichero ^ Reglas (las que entran; se amplía con lo que salga en las revisiones) ^
+  * **Una conversación por tarea.** ''/clear'' entre tareas. Lo que tenga que sobrevivir, a un fichero.
-| ''metodos.md'' | El método público cuenta la historia entera y se lee de arriba abajo. Se trocea por **cosa** que hace, no por fase. Con pocos casos (hasta 4), un método lineal por caso en vez de un genérico. El nombre dice qué hace, no cómo. Cabe en una pantalla y tiene como mucho tres parámetros. El cálculo puro se separa de la entrada/salida (base de datos, HTTP) para poder probarlo sin montar nada |
+  * **El modelo bueno para especificar, el barato para implementar** cosas claras. ''/model'' en Claude Code, ''/models'' en OpenCode.
-| ''clases.md'' | Una clase, una responsabilidad. Composición antes que herencia. Un DTO o record agrupa solo lo homogéneo y sus campos se nombran por lo que son, no por quién los usa. Nada estático con estado. La interfaz del ''Repository'' en ''domain'' dice lo que el dominio necesita, no lo que la base de datos ofrece |
+  * **No pegar logs enteros.** Solo el error y las líneas de alrededor.
-| ''comentarios.md'' | El código se explica solo: si hace falta un comentario para entender qué hace, el nombre está mal. El único comentario que se escribe es el **porqué** que leer el código no revela (una decisión, una restricción externa). Nada de comentarios que repiten la línea de debajo ni de código comentado |
+  * **Mirar el contador.** ''/context'' y ''/cost'' en Claude Code; OpenCode lo muestra junto a la caja de entrada. Cuando el contexto pasa de la mitad, o se cierra la tarea o se hace ''/compact''.
-| ''tests.md'' | Un test por comportamiento, con el caso en el nombre. El test **no copia los valores del código que prueba** (si el IVA es una constante, el test la lee de producción y comprueba la relación, no escribe 21 otra vez). Sin lógica en el test: ni ''if'' ni bucles. Lo que se prepara se ve en el propio test |
-Y en ''SKILL.md'', cuatro olores de **diseño** que vienen antes del código y que el agente tiene que buscar aunque no haya regla concreta: una decisión que se toma en dos sitios; un método que vive en una clase que no es la dueña del concepto; un ''if'' que no cubre todos los casos; un retorno defensivo (''return null'', lista vacía) que tapa un error en vez de fallar.
+===== MCP =====
-La ''description'' de la skill dice cuándo cargarla: «Reglas de calidad del código del proyecto. Cargar al escribir o revisar cualquier clase Java o TypeScript, y siempre desde ''/developer review''».
+Dos servidores MCP y ninguno más (qué es un MCP: [[cursos:sdd:02-skills-agentes-mcp#mcp|MCP]]):
-==== test review: los tests contra los criterios ====
+  * **Context7**: documentación actualizada de Spring Boot y Angular. Sin él, el agente escribe código de la versión que recuerda, que no es la que usáis.
+  * **Playwright MCP**: el agente abre la aplicación en un navegador y la ve. Sirve para que compruebe por sí mismo que una pantalla funciona, y en el tema 6 para generar los tests E2E.
-<code>
-/developer test review
-</code>
-Revisa los tests del issue, no el código: que **cada criterio de aceptación** de ''requirements.md'' tiene su test E2E y cada caso de error su test de API; que no hay tests que no comprueban nada (sin aserciones, o con aserciones que siempre pasan); que cumplen ''tests.md'' de ''calidad-codigo'' (no copian los valores del código, sin lógica dentro). Lo que falta va a ''tasks.md'' como tarea («test E2E del criterio 3»); lo que está mal, a ''review.md''.
+Se configuran con ''claude mcp add'' en Claude Code y en ''opencode.json'' en OpenCode, siguiendo la página de cada servidor.
-===== Lo que comprueba /git-flow finish =====
+===== Permisos del agente =====
-Con los tests y las revisiones, ''finish'' deja de ser solo git. Antes de fusionar comprueba, y si algo falla lo dice y **no hace nada**:
+En el tema 3 se permitió lo básico. Para programar, el agente tiene que poder compilar, pasar tests y levantar la aplicación sin preguntar en cada paso. La lista de ''.claude/settings.json'' queda así:
-  - ''tasks.md'' sin tareas pendientes.
+  * **Permitido**: ''mvn'', ''npm'', ''npx'' (incluido ''npx playwright''), ''docker compose'', ''./app.sh'', ''gh issue'', ''gh run'' y las lecturas de git (''status'', ''diff'', ''log'', ''worktree list'').
-  - ''review.md'' sin hallazgos abiertos (los graves corregidos; los mejorables, corregidos o cerrados por el alumno).
+  * **Pregunta**: escribir ficheros fuera del worktree, ''docker'' a secas, cualquier ''curl'' a un sitio que no sea ''localhost''.
-  - Los cuatro tipos de tests en verde: ''finish'' ejecuta por dentro los comandos de ''/test run'', uno a uno, y se para en el primero que falla.
+  * **Denegado**: ''git push --force'', ''rm -rf'', y cualquier ''git'' que cambie el repositorio (''commit'', ''merge'', ''push''), que solo puede ejecutar ''/git-flow'' por su ''allowed-tools''.
-Si está todo, hace lo del tema 2: ''update'', ''--squash'' en ''develop'' con ''Closes #N'', push, ''./app.sh stop -v'' y borrar el worktree. Es la regla del tema 1: ningún comando espera al alumno; los que generan trabajo lo dejan en ficheros, y el que hace algo irreversible solo comprueba que esos ficheros están como tienen que estar.
+En OpenCode, lo mismo en la clave ''permission'' de ''opencode.json''.
 ===== Ejercicios =====
 ==== Ejercicio 1 ====
-  * Crea un issue «Skill /test: create» e inícialo.
+  * Configura Context7 y el MCP de Playwright en Claude Code (''claude mcp add'') y en OpenCode (''opencode.json'').
-  * Instala Playwright en ''frontend/'' (''npm init playwright@latest'') con los proyectos ''api'' y ''e2e'' y los scripts ''test:api'' y ''test:e2e'' del tema 3.
+  * Comprueba que funcionan: pide al agente la forma actual de declarar una ruta en Angular y que abra la aplicación del worktree y te diga qué ve.
-  * Escribe la skill ''/test'' con los cuatro sustantivos y el verbo ''create'': ''arch'' (reglas en castellano → tests ArchUnit en ''backend/src/test'' acabados en ''ArchTest'', con ''@DisplayName'' y comentario), ''unit'' (clase o paquete → un test JUnit 5 por comportamiento, con Mockito y sin Spring), ''api'' (entidad → ''tests/api/<entidad>.spec.ts'' con un test por endpoint y por error previsto) y ''e2e'' (criterios de ''requirements.md'' de la spec del worktree → un ''.spec.ts'' por criterio, usando el MCP de Playwright).
+  * Completa ''.claude/settings.json'' con los permisos de este tema y súbelo.
-  * ''/test arch create'' con las seis reglas del tema. Mueve a mano el servicio del CRUD al paquete ''controller'' y comprueba que ''mvn test'' falla con el mensaje del test. Deshazlo.
-  * ''/test unit create'' con el servicio del CRUD del tema 4, ''/test api create'' con su entidad y ''/test e2e create''. Comprueba que ''mvn test'' no ejecuta los de Playwright y que ''npm run test:api'' y ''npm run test:e2e'' pasan dos veces seguidas.
-  * Finaliza el issue.
 ==== Ejercicio 2 ====
-  * Crea un issue «Skill /test: run y repair» e inícialo.
+  * Crea un issue «Skill /sdd» e inícialo con ''/git-flow start''.
-  * Añade el verbo ''run'' con la tabla de comandos del tema: en rojo, explica qué test, qué esperaba y qué ha pasado.
+  * Instala cc-sdd en la raíz del repositorio y comprueba que ''/kiro-spec-init'' aparece como skill.
-  * Introduce un error a mano en una validación del servicio, reconstruye el backend y lanza ''/test unit run'' y ''/test api run'': tiene que caer al menos un unitario y uno de API, y la explicación tiene que señalar la validación. Deshazlo.
+  * Escribe la skill ''/sdd'' con los dos subcomandos: ''spec create'' (lee el issue del nombre de la rama, pregunta lo que no esté claro y encadena las cuatro fases de cc-sdd, con ''-y'' en diseño y tareas) y ''spec impl'' (''/kiro-impl'' de las tareas pendientes, tests después de cada una, y parar si un test falla por el código).
-  * Añade el verbo ''repair'' con el criterio de la intención, las tres reglas y el fichero ''repair.md''.
+  * Añade a ''AGENTS.md'' la línea sobre ''.kiro/specs/''. Finaliza el issue.
-  * Cambia a propósito el texto de un mensaje de error del formulario y lanza ''/test e2e repair'': tiene que actualizar el test y decir que era un cambio intencionado. Después rompe una validación del servicio sin tocar ningún test y lanza ''/test api repair'': tiene que arreglar el código y dejar el test como estaba.
-  * Finaliza el issue.
 ==== Ejercicio 3 ====
-  * Crea un issue «Skill /developer review» e inícialo.
+  * Crea un issue para la primera entidad de tu proyecto con un CRUD completo (por ejemplo «CRUD de productos») e inícialo.
-  * Escribe la skill de conocimiento ''calidad-codigo'' con los cuatro ficheros de la tabla y los olores de diseño en ''SKILL.md''. Pide al agente un primer borrador a partir de la tabla y corrígelo: cada regla con una frase de ejemplo de código que la cumple y otra que no.
+  * ''/sdd spec create''. Lee ''requirements.md'': comprueba que los criterios de aceptación son comprobables y que están los casos de error. Corrige lo que falte y vuelve a generar.
-  * Escribe la skill ''/developer'' con los sustantivos ''code'' y ''test'' y el verbo ''review'': ''allowed-tools'' solo de lectura más escribir ''review.md'' y ''tasks.md'', el formato de hallazgo del ejemplo y la regla de las clases hermanas.
+  * Lee ''design.md'' y corrígelo a mano hasta que sea la arquitectura de Programación y DWS, clase por clase, con migración y datos de prueba. Lee ''tasks.md'' y comprueba que las tareas son pequeñas y van en orden.
-  * Pásala sobre el CRUD del tema 4. Lee ''review.md'': para cada hallazgo, decide si es un defecto o una preferencia y por qué. Cierra a mano uno mejorable y comprueba que ''tasks.md'' tiene los graves.
+  * ''/clear'' y ''/sdd spec impl''. Comprueba que marca las tareas hechas y que pasa los tests después de cada una.
-  * ''/sdd spec impl'' para los graves y vuelve a pasar ''code review'': no deben salir.
+  * Prueba la aplicación en la URL del worktree: listado, alta, edición, borrado y las validaciones. Lo que no esté bien se pide en la misma conversación.
-  * Finaliza el issue.
+  * Lee el código generado clase por clase y corrígelo: es la referencia de todos los CRUD que vienen después.
 ==== Ejercicio 4 ====
-  * Crea un issue «finish comprueba» e inícialo.
+  * En el mismo worktree, lanza ''/kiro-steering''. Lee los tres ficheros y déjalos cortos, con solo lo común.
-  * Amplía ''/git-flow finish'' con las tres comprobaciones del tema. Si alguna falla, tiene que decir cuál y no tocar nada.
+  * Con ''/kiro-steering-custom'' crea ''backend.md'' y ''frontend.md'' condicionales y rellénalos con la tabla del tema, mirando el CRUD que acabas de hacer.
-  * Deja una tarea sin marcar en ''tasks.md'' y lanza ''finish'': se tiene que parar. Márcala, deja un hallazgo grave abierto en ''review.md'' y vuelve a lanzar: se tiene que parar. Ciérralo y finaliza.
+  * Escribe ''convenciones-backend'' y ''convenciones-frontend'' apuntando a ellos. Comprueba que la ''description'' dice cuándo cargarlas.
+  * ''/clear'' y pide un cambio pequeño en el backend. Comprueba que el agente carga ''convenciones-backend'' sin que se lo digas.
+  * ''/git-flow commit'' y ''/git-flow finish''. Comprueba que la spec ha entrado en ''develop'' en el mismo commit que el código.
+  * Mira ''/context'' al final de la conversación de implementación y anota cuánto ha ocupado.
 ==== Ejercicio 5 ====
-  * Crea un issue para la segunda entidad de tu proyecto e inícialo. Es el primer issue que se hace con la fábrica entera.
+  * Crea un issue «Skill /code: impl» e inícialo. Escribe la skill ''/code'' con el verbo ''impl <plan>'': tareas pendientes del fichero, marcarlas, tests unitarios y de arquitectura tras cada una, y parar si un test falla por el código. Finaliza el issue.
-  * ''/sdd spec create''. En ''design.md'' compáralo con el CRUD del tema 4: cada diferencia es una línea que falta en el steering. Corrígela y vuelve a generar hasta que salga igual.
+  * Crea un issue que no sea un CRUD (un filtro en el listado, un campo calculado, un informe) e inícialo.
-  * ''/clear'', ''/sdd spec impl'', ''/test unit create'', ''/test api create'' y ''/test e2e create''. Los cuatro tipos en verde, uno a uno.
+  * En modo plan, dile lo que quieres y que escriba el plan en ''plan_<algo>.md''. Sal del modo plan y léelo: si falta una tarea o una está mal, corrígela a mano.
-  * ''/developer code review'' y ''/developer test review''. Quita a mano de ''requirements.md'' un caso de error sin quitar su código y vuelve a pasar ''code review'': tiene que marcarlo como grave. Restaura el fichero.
+  * ''/clear'' y ''/code impl'' con el plan. Comprueba que marca las tareas y pasa los tests tras cada una. Prueba el cambio en el navegador y finaliza el issue.
-  * ''/git-flow commit'' y ''/git-flow finish''.