Antes de pedirle código a un agente de IA, escribe una página con tres cosas: qué debe hacer, cómo vas a comprobar que lo hace y qué queda fuera. A ese hábito se le llama desarrollo guiado por especificaciones (spec-driven development, SDD en inglés) y es lo que separa a quien dirige al agente de quien se limita a probar suerte con otro prompt. Aquí tienes los cinco pasos, una plantilla para copiar y un ejemplo pequeño cuyos tests se han ejecutado de verdad.
Por qué una página de especificación cambia el resultado
Un agente de programación trabaja con lo que le cuentas y con lo que lee en tu repositorio. Si le falta la definición de «terminado», da la tarea por cerrada cuando a él le parece. Una especificación escrita le da algo contra lo que comprobarse, y a ti algo contra lo que revisar.
La documentación de Claude Code lo plantea en sus buenas prácticas. Cuando el agente dice que ha terminado y no era cierto, suele ser porque no tenía forma de comprobar su propio trabajo. Y si todavía no sabes bien qué quieres, propone pedirle que te entreviste hasta poder escribir la especificación en un fichero y empezar la construcción en una sesión nueva, con el contexto limpio y una definición de «hecho» por escrito.
La idea se parece a lo que ya haces cuando dejas un encargo a una persona del equipo: no le dices «hazme algo de gastos», le das el caso, los límites y un ejemplo. Con un agente es igual, solo que lee todo literalmente.
Para seguir el tutorial te basta con leer algo de código (los ejemplos van en Python) y tener a mano el agente que uses, sea Claude Code, Cursor, Codex u otro. El método no depende de la herramienta.
Paso 1: cuenta el problema en dos frases y marca lo que queda fuera
La primera sección de la especificación es un objetivo de dos frases y una lista corta de lo que no vas a hacer. Es la parte que más trabajo ahorra: un agente con ganas añade pantallas, bases de datos y opciones que nadie pidió, y cada extra es código que luego revisas.
Nuestro ejemplo es una función para repartir los gastos de un viaje entre amigos. Así queda este paso:
Fíjate en que «fuera de alcance» no es una lista de prohibiciones tuyas, es información que el agente no puede adivinar. Con esas tres líneas ya se ha descartado media aplicación.
Paso 2: escribe criterios de aceptación que se puedan comprobar
Un criterio de aceptación es una frase que termina en un sí o un no. «Que reparta bien» no sirve; «con tres personas y 60 € pagados por una, las otras dos le deben 20 € cada una» sí. Si no puedes decidir con un test si se cumple, reescríbelo hasta que puedas.
Para el reparto de gastos, los criterios quedaron así:
Los importes son números enteros de céntimos; un importe negativo o con decimales lanza un error.
Si nadie debe nada a nadie, devuelve una lista vacía. Con una entrada vacía, también.
La salida es una lista de transferencias
(deudor, acreedor, céntimos).Tras las transferencias, todos han aportado lo mismo, con a lo sumo un céntimo de diferencia.
Si el total no se divide exacto, los céntimos sobrantes los asumen las primeras personas por orden alfabético, de uno en uno. Así el resultado es siempre el mismo.
No hay transferencias de una persona a sí misma ni de cantidad cero.
El criterio 5 es el que casi todo el mundo olvida. Sin él, el agente elige un redondeo por su cuenta, y la próxima ejecución puede elegir otro. Una regla de desempate escrita convierte un comportamiento ambiguo en algo comprobable.
Convierte este método en cinco proyectos
Mira el temario del Máster en Desarrollo Agéntico y los cinco proyectos de la ficha.
Paso 3: añade ejemplos con números reales
Un ejemplo con entrada y salida concretas vale más que un párrafo de descripción, porque el agente lo puede usar como prueba inmediata y tú como contraste. Con uno o dos basta, y conviene que uno sea el caso tonto y otro el que incluye el borde.
El ejemplo B recoge, además, el criterio 5 en acción. Es una buena costumbre: cada regla no obvia debería tener su ejemplo al lado.
Paso 4: convierte los criterios en tests antes de pedir el código
Pide al agente que escriba primero los tests a partir de tus criterios y revísalos tú antes de que toque la implementación. Revisar siete tests es rápido, y es la comprobación más barata de que el agente ha entendido lo que querías. Si un test dice otra cosa que tu criterio, lo corriges ahí, antes de que haya código.
Estos son tres de los siete tests del ejemplo, escritos con unittest, que ya viene con Python:
Con los tests escritos y la implementación hecha, el ejemplo se ejecutó con Python 3.13 y python3 -m unittest -v: los siete tests pasaron. La implementación son unas veinticinco líneas y no importa quién las escriba; lo que importa es que tengas una vara de medir antes de leerlas.
Paso 5: trocea en tareas y revisa contra la especificación
Divide el trabajo en tareas pequeñas, con su propio resultado comprobable, y pide al agente que las haga de una en una. Al terminar, no preguntes «¿está bien?»: pide una revisión que compare el cambio con la especificación, criterio por criterio.
Para el ejemplo, una lista razonable es esta:
Validar la entrada (criterios 1 y 2).
Calcular cuánto debe aportar cada persona, con el reparto de céntimos (criterio 5).
Generar las transferencias (criterios 3, 4 y 6).
Ejecutar todos los tests y listar cualquier criterio sin test.
La documentación de Claude Code da incluso un modelo de petición para la revisión: que un subagente compare el cambio con el fichero de especificación, compruebe que cada requisito está implementado y que los casos límite listados tienen test, y que informe solo de los fallos que afecten a la corrección, sin comentarios de estilo. Esa última cláusula importa, porque un revisor al que le pides defectos siempre encuentra alguno, y acabarías arreglando cosas que no hacían falta.
Practica la especificación con proyectos completos
Descarga el dossier y consulta el programa con calma.
La plantilla de especificación completa, para copiar
Copia este bloque en un fichero (por ejemplo SPEC.md) en la raíz de tu proyecto, rellena cada sección y pásaselo al agente antes de pedirle nada. Una página basta; si te pasas de dos, probablemente estás especificando varias funciones a la vez y conviene partirla.
Cómo usarla: rellena primero las secciones 1, 2 y 4, que son las que piensas tú. Pide al agente que proponga las demás y corrígelas. Si no sabes cómo empezar, dile que te entreviste con preguntas hasta poder redactar la especificación, tal como recomienda la documentación citada arriba. Y cuando cambie lo que quieres, cambia primero la especificación y después el código, para que el fichero siga siendo cierto.
Herramientas que ya montan este flujo
No necesitas ninguna para aplicar el método, pero conviene saber que existen. Spec Kit, el proyecto de GitHub, describe el mismo recorrido: definir qué construir y por qué, convertir la especificación en plan, tareas y código, y repetir. Su README propone comandos que se ejecutan en el chat del agente y de uno en uno, revisando cada resultado antes de seguir: principios del proyecto, especificación, plan, tareas, implementación y una comprobación final de convergencia.
Kiro sigue una idea parecida con tres ficheros por funcionalidad, según su documentación: requirements.md (historias de usuario y criterios de aceptación), design.md (arquitectura) y tasks.md (tareas con seguimiento). Si te fijas, es la misma plantilla de arriba con otros nombres.
No hemos ejecutado esas dos herramientas para este artículo: lo que cuentan de sí mismas está tomado de su documentación oficial de hoy, y los detalles de instalación pueden cambiar, así que mira siempre su página antes de empezar.
Del ejercicio al proyecto completo: así se trabaja en el máster
Con una función de veinticinco líneas el método parece sencillo, y lo es. Lo interesante aparece cuando el proyecto tiene varias pantallas, base de datos y despliegue: ahí la especificación decide si diriges al agente o si lo sigues.
La ficha del Máster en Desarrollo Agéntico de thePower Tech School lista «Spec-Driven Development» junto a Claude Code y la orquestación multi-agente. Entre lo que construyes anuncia «Software construido con SDD» y entre lo que consigues, «Dirigir el desarrollo, no improvisar». El programa se presenta como el aprendizaje para diseñar, construir y desplegar sistemas agénticos reales con Claude Code, MCPs y orquestación multi-agente, con cinco proyectos desplegados en producción: un asistente personal de productividad, un ecommerce, un SaaS de gestión de proyectos con colaboración en tiempo real, una API de gestión de ficheros y un agente de voz para gestión de calendario.
El formato son 20 sesiones en directo de 1,5 horas, con grabaciones si no puedes asistir, y la ficha anuncia el stack de los proyectos: Next.js, Prisma, Stripe, shadcn/ui, Docker y GitHub Actions, entre otros. Parte de conocimientos básicos de programación, familiaridad con Git y comprensión de APIs y bases de datos, justo lo que has usado en este tutorial. Esta información es la de la ficha, consultada el 29-10-2026, que indica próxima convocatoria en noviembre de 2026.
Si quieres ver los cinco proyectos y el temario completo, el dossier los reúne.
Dirige el desarrollo, no improvises
Descarga el dossier del Máster en Desarrollo Agéntico y mira los cinco proyectos.
Mientras tanto, un buen ejercicio para esta semana: elige una tarea pequeña que tengas en mente, rellena las secciones 1, 2 y 4 de la plantilla y compara el resultado con lo que habrías pedido en un solo prompt. Si quieres otro punto de partida con proyectos y prompts, tienes la guía de vibe coding, y para entender la diferencia de enfoque está usar IA para programar frente a programar con IA.
Preguntas frecuentes sobre la especificación para agentes de IA
¿Qué es el desarrollo guiado por especificaciones?
Es trabajar con un documento escrito (qué debe hacer el software, cómo se comprueba y qué queda fuera) y construir a partir de él, en lugar de ir pidiendo código a base de prompts sueltos. La especificación manda: si cambia lo que quieres, se cambia primero ella.
¿Necesito Spec Kit, Kiro o una herramienta concreta?
No. El método funciona con un fichero de texto y los tests de tu lenguaje. Las herramientas automatizan los pasos y ordenan los ficheros, pero la parte que pesa, decidir qué quieres y cómo lo comprobarás, la haces tú.
¿Hasta dónde debe llegar de larga la especificación?
Hasta una página por funcionalidad. Si necesitas más, divide el trabajo en varias especificaciones con su propio objetivo y sus propios criterios. Una especificación corta se lee entera, y un agente la sigue mejor.
¿Qué hago si el agente no cumple un criterio?
Comprueba primero si el criterio estaba escrito de forma que se pudiera verificar. Si lo estaba, pega el fallo del test en la conversación y pide la corrección de esa tarea. Si no, reescribe el criterio con un ejemplo y vuelve a empezar desde ahí.
