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.

Lo que ya está contado en el curso de programación con IA y aquí no se repite: qué es el Spec-driven development y por qué encaja con los agentes, cc-sdd (Kiro) con sus fases y su memoria del proyecto, y la ingeniería de contexto.

En este proyecto hay dos clases de issue y cada una tiene su camino:

• 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.
• 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.

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.

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:

npx cc-sdd@latest --claude-skills --lang es      (OpenCode: --opencode-skills)

Ese es el flujo de cada issue:

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:

1. /kiro-spec-init con el título y el cuerpo del issue (gh issue view N).
2. /kiro-spec-requirements: los requisitos y los criterios de aceptación.
3. /kiro-spec-design -y: el diseño, leyendo antes el steering con la arquitectura del proyecto (abajo).
4. /kiro-spec-tasks -y: la lista de tareas, en orden y pequeñas.

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.

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:

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.

Conversación nueva (/clear) y una sola orden:

/sdd spec impl

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.

Solo implementa la spec. Los planes (abajo) y las correcciones de una revisión (tema 6) se hacen con /code impl.

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.

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 (Plan y Build). Es el camino de los issues que no son un CRUD:

1. 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.
2. Se sale del modo plan. El fichero queda en el worktree.
3. 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.
4. Conversación nueva (/clear) y se implementa:

/code impl plan_filtro-provincia.md

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.

/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.

La skill /code nace en este tema con el verbo impl; en el tema 6 se le añade review.

.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ó.

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:

.kiro/specs/ es histórico: la fuente de verdad es el código. No leas specs de otros issues salvo que te lo pidan.

Es corta, porque el trabajo lo hacen los comandos de cc-sdd. Recibe el subcomando en $ARGUMENTS y hace una cosa u otra:

---
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
---

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.

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.

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.

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 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.

/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:

/kiro-steering

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.

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:

---
inclusion: fileMatch
fileMatchPattern: "backend/**"
---
# Arquitectura del servidor
...

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:

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.

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.

---
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.

Y convenciones-frontend igual, hacia frontend.md. Una sola fuente: cuando cambia una convención, cambia en un sitio.

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:

• Una conversación por tarea. /clear entre tareas. Lo que tenga que sobrevivir, a un fichero.
• El modelo bueno para especificar, el barato para implementar cosas claras. /model en Claude Code, /models en OpenCode.
• No pegar logs enteros. Solo el error y las líneas de alrededor.
• 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.

Dos servidores MCP y ninguno más (qué es un MCP: MCP):

• 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.

Se configuran con claude mcp add en Claude Code y en opencode.json en OpenCode, siguiendo la página de cada servidor.

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í:

• 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).
• Pregunta: escribir ficheros fuera del worktree, docker a secas, cualquier curl a un sitio que no sea localhost.
• 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.

En OpenCode, lo mismo en la clave permission de opencode.json.

• Configura Context7 y el MCP de Playwright en Claude Code (claude mcp add) y en OpenCode (opencode.json).
• 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.
• Completa .claude/settings.json con los permisos de este tema y súbelo.

• Crea un issue «Skill /sdd» e inícialo con /git-flow start.
• Instala cc-sdd en la raíz del repositorio y comprueba que /kiro-spec-init aparece como skill.
• 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 a AGENTS.md la línea sobre .kiro/specs/. Finaliza el issue.

• Crea un issue para la primera entidad de tu proyecto con un CRUD completo (por ejemplo «CRUD de productos») e inícialo.
• /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.
• 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.
• /clear y /sdd spec impl. Comprueba que marca las tareas hechas y que pasa los tests después de cada una.
• 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.
• Lee el código generado clase por clase y corrígelo: es la referencia de todos los CRUD que vienen después.

• En el mismo worktree, lanza /kiro-steering. Lee los tres ficheros y déjalos cortos, con solo lo común.
• 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.
• 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.

• 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.
• Crea un issue que no sea un CRUD (un filtro en el listado, un campo calculado, un informe) e inícialo.
• 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.
• /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.