Escribe una especificación antes de darle instrucciones a un agente de código de IA

Escribir la petición directamente en un agente de código parece más rápido que anotar algo antes, y en una tarea realmente trivial suele serlo. El problema empieza con cualquier cosa que admita más de una interpretación razonable: el agente elige una, construye en esa dirección y tú no descubres que eligió mal hasta que estás leyendo el código terminado. Cada vuelta desde ahí cuesta más que los pocos minutos que habría llevado una especificación.

Una especificación cambia el orden de las cosas. Antes de escribir una sola línea de código, anotas tres cosas en lenguaje llano: qué debe hacer lo que quieres construir, para quién es y los criterios de terminado que demuestran que funciona. No es un documento técnico. Se parece más a la nota que le dejarías a un asistente competente que no te conoce: con suficiente detalle para que no tenga que adivinar lo que importa.

Funciona por una razón sencilla. El agente deja de rellenar los huecos de tu petición con sus propias suposiciones, porque quedan menos huecos que rellenar. Y tú dejas de descubrir lo que querías al leer el resultado del agente a posteriori, porque ya lo dejaste escrito antes de pedir nada.

Nada de esto es específico de una herramienta. Claude Code, Codex, Copilot, Cursor y cualquier otro agente de código funcionan básicamente igual: entran instrucciones en lenguaje llano y salen código y comandos. Una especificación cambia lo que entra, lo que a su vez cambia lo que vuelve, sea cual sea el agente con el que hables.

Spec Kit de GitHub es un conjunto de herramientas de código abierto, mantenido en el repositorio del propio GitHub bajo licencia MIT, pensado para dar a los agentes de código de IA procesos estructurados, plantillas reutilizables y resultados documentados en lugar de conversaciones sueltas. Se instala con su propia herramienta de línea de comandos, y su README lo describe como un conjunto de herramientas para empezar con el desarrollo guiado por especificaciones, o con cualquier otro proceso estructurado que quieras que siga un agente.

El flujo principal de desarrollo guiado por especificaciones, según la documentación del proyecto, recorre una secuencia con nombre de seis comandos: uno fija los principios rectores del proyecto, otro escribe la especificación, otro convierte esa especificación en un plan técnico, otro divide el plan en una lista ordenada de tareas, otro ejecuta las tareas y escribe el código, y un último comprueba cuánto ha convergido el resultado con la especificación. La propia guía del proyecto recomienda ejecutarlos uno a uno, revisando cada resultado antes de seguir, y repetir los pasos de implementar y converger hasta que la convergencia indique que el trabajo ha convergido, en lugar de entregarle todo el trabajo al agente de una sola vez.

El conjunto de herramientas incluye además extensiones independientes que se añaden al flujo principal, de nuevo según su documentación: un grupo de comandos centrado en evaluar y corregir un error concreto, y otro centrado en llevar una idea aproximada por la investigación y la definición antes de decidir si se construye o no.

En cuanto a los agentes con los que se conecta, la documentación de instalación de Spec Kit nombra varios mediante una clave de integración que se indica al instalar, entre ellos Claude Code y GitHub Copilot, y remite a su propia documentación aparte para conectar otros agentes además de los que nombra directamente. Trata cualquier lista de agentes, incluida esta, como una instantánea: consulta la documentación actual de Spec Kit antes de dar por hecho que una herramienta concreta es compatible o no lo es hoy.

Para alguien que no es desarrollador y construye una sola cosa pequeña, ejecutar el flujo completo de Spec Kit puede ser más ceremonia de la que la tarea necesita. La especificación de tres partes por sí sola, escrita como tu primer mensaje al agente que ya uses, hace por sí misma la mayor parte del trabajo, sin nada que instalar.

Pega la especificación y deja que el agente te haga preguntas aclaratorias antes de escribir nada. Un agente competente preguntará cuando algo no quede claro, y una especificación le da algo concreto sobre lo que preguntar en lugar de adivinar en silencio y construir con seguridad lo equivocado.

Esta versión sencilla del hábito se traslada a cualquier herramienta. El mismo documento de tres partes funciona tanto si hablas con Claude Code como con Codex, Copilot, Cursor o cualquier otro agente de código, porque nada de ello depende de una función propia de una herramienta. Es un hábito que construyes, no un complemento que instalas.

Para una construcción pequeña y puntual, basta una especificación sencilla de tres partes escrita directamente en el chat, y es más rápido que instalar nada. La mayoría de los ejemplos de esta guía están pensados para ese caso.

Spec Kit empieza a compensar su coste de instalación cuando repites esto en el mismo proyecto, quieres que sus principios se apliquen automáticamente en cada función nueva, o prefieres la estructura propia de las extensiones de corrección de errores o de evaluación de ideas en lugar de inventar tu propia versión cada vez.

En cualquier caso, la habilidad de fondo es la misma: indicar qué hace, para quién es y cómo sabrás que está terminado antes de que se escriba una sola línea de código. El conjunto de herramientas solo automatiza dejar eso por escrito de forma coherente, cuando el hábito es uno al que recurres con la frecuencia suficiente como para que valga la pena automatizarlo.