Spec-Driven Development con Claude Code: una feature de principio a fin

Hola, bienvenido. Con la lección anterior cerramos la sección de dynamic workflows, y en esta lección vamos a construir una feature de claude-tasks de principio a fin con Spec-Driven Development. Primero escribiremos qué tiene que hacer y cómo sabremos que funciona, después lo convertiremos en un plan y en una lista de tareas, y por último lo implementaremos por bloques y lo comprobaremos contra lo que dijimos. La feature es pequeña a propósito: una bandeja de feedback en la que los usuarios autenticados envían un error, una idea o una pregunta. Y plan mode va a hacer de puente entre la especificación y el código.

¿Por qué trabajar así con Claude Code? Porque un prompt largo vive en la conversación, y la conversación se compacta, se limpia con /clear y no pasa de una sesión a otra. Una especificación escrita en un archivo, en cambio, sigue ahí en la sesión siguiente, y Claude la puede releer, compararla con el código y usarla para retomar el trabajo sin que tengas que volver a explicarle nada. La propia documentación de Claude Code lo recomienda para las features grandes: que Claude te entreviste, que escriba una spec en un archivo y que la implementes en una sesión nueva, con el contexto limpio y centrado solo en la implementación. En la lección Cómo escribir buenos prompts para Claude Code te dije que veríamos esa entrevista con calma, y es lo primero que vamos a hacer.

Esta lección recorre el ciclo una vez, sobre una feature, para que veas cómo encaja con Claude Code. Spec-Driven Development da para mucho más, y si quieres verlo a fondo, con specs más grandes y todo el proceso en un proyecto Laravel, tienes en la plataforma el curso Spec-Driven Development en Laravel con IA↗ (se abre en una pestaña nueva).

Para seguir esta lección necesitas claude-tasks con el commit del workflow de la lección Guardar y reutilizar un workflow de Claude Code y sin cambios pendientes, los contenedores de Sail levantados y una sesión de Claude Code en la raíz del proyecto. Todo lo que veremos funciona en la 2.1.283, la versión del curso.

Spec-Driven Development, o desarrollo guiado por especificación, consiste en decidir qué hay que construir y cómo se sabrá que está bien antes de escribir código, y en dejar esa decisión por escrito para que guíe todo lo demás. Spec Kit, la herramienta de GitHub para trabajar así, lo resume en la secuencia Specify, Plan, Tasks, Implement y Converge, y explica que cada fase produce un archivo Markdown que el agente usa como contexto estructurado en la siguiente, en lugar de prompts sueltos. En esta lección usamos 4 fases, cada una con su archivo cuando lo necesita:

En la lección las encadenamos con una sesión limpia antes del plan y otra antes de implementar, y con un cierre que vuelve a la spec:

Fíjate en la separación entre la spec y el plan. La spec no decide clases ni archivos, porque para eso hay que mirar antes el código, y el plan sí, porque llega después de que Claude haya leído el proyecto. Así, si mañana cambias de enfoque técnico, la spec sigue siendo válida.

¿Y cuándo merece la pena? El criterio es el mismo que vimos en la lección Plan mode en Claude Code: revisar antes de ejecutar, llevado un paso más allá. Si puedes describir el diff en una frase, no necesitas ni plan. Si la feature tiene varias piezas, reglas de negocio, permisos, datos y tests, o si vas a trabajar en ella en más de una sesión, tener la spec y las tareas por escrito te ahorra repetir el contexto cada vez.