Escribir la spec con la IA

Dale la vuelta al encargo

En el capítulo 1 pedimos «hazme un acortador de URLs» a once agentes y los once se pusieron a programar. Cada uno decidió por su cuenta qué pasa con una URL repetida, qué alias valen o si un enlace caduca. Ninguno preguntó, porque nadie se lo pidió.

La especificación del capítulo 2 es la solución, pero deja una objeción razonable: para escribirla hay que saber qué preguntas hacerse, y eso es justo lo que no sabes cuando empiezas.

No hace falta saberlo. El mismo modelo que rellena los huecos en silencio sabe muy bien cuáles son. Solo hay que cambiar una frase del encargo.

Si se lo pides, pregunta

Repetimos el experimento con tres modelos, uno por proveedor. La misma idea de una línea, y una instrucción más: que pregunten antes de escribir nada.

Ábrelas. Las tres preguntan por cosas que en el capítulo 1 se decidieron sin decir nada: si acortar dos veces la misma URL da el mismo enlace, qué tipo de redirección usar, cómo son los alias, si los enlaces caducan. El conocimiento estaba ahí. Faltaba pedirlo.

Setenta preguntas no son una entrevista

Fíjate ahora en las cifras: 23, 30 y 70. Nadie contesta setenta preguntas antes de empezar un proyecto pequeño, y si lo intenta contestará las últimas de cualquier manera.

Además, no todas pesan lo mismo. En la lista larga, junto a preguntas excelentes (qué debe ocurrir si un alias ya existe, cómo tratar las peticiones HEAD), aparecen los planes de pago, la autenticación de dos factores y los correos transaccionales. Para una herramienta de uso local son ruido, y el modelo no puede saberlo: tampoco le hemos dicho para qué es.

Pedir «todas las preguntas» cambia un problema por otro. Antes el modelo decidía todo sin consultarte. Ahora te consulta todo sin decidir nada.

Cuatro preguntas

acorta, el proyecto de este tutorial, empezó con una línea parecida. El agente no preguntó setenta cosas. Preguntó cuatro: las que no podía decidir él porque cambiaban el producto. Esta es la tabla, copiada de la bitácora del proyecto:

#	Pregunta	Opciones	Respuesta de Xavi
1	¿Cómo se llama y dónde vive el código?	acorta, repo propio (recomendada: historial limpio para repetirlo commit a commit) · acorta dentro del repo de la web	acorta, repo propio
2	Además del núcleo (crear, redirigir, listar), ¿qué entra en la v1?	Contador de visitas · Borrar enlaces · Alias personalizado · Caducidad (se podían marcar varias)	Las cuatro
3	¿Dónde se guardan los enlaces?	SQLite sin CGO (recomendada) · Fichero JSON · Solo en memoria	SQLite sin CGO
4	¿Quién puede crear y borrar enlaces en la v1?	Sin autenticación (recomendada: llegará después como spec nueva) · Token de API desde la v1 · Usuario y contraseña	Sin autenticación

Tres detalles hacen que se conteste en un minuto:

• Son pocas. Solo las que cambian qué se construye. Lo demás no se pregunta.
• Traen opciones. Elegir entre tres cosas es más rápido que redactar una respuesta, y obliga al modelo a enseñar qué alternativas ve.
• Traen una recomendación con su porqué. Si no tienes opinión, aceptas la suya. Si la tienes, ya sabes contra qué discutir.

Lo que no se pregunta, se enseña

¿Y todo lo demás? Se decide igualmente. La diferencia con el capítulo 1 es que no se quedan escondidas en el código.

Al redactar la spec de acorta, el agente apuntó aparte cada decisión que había tomado por su cuenta. Salieron veintiuna, en una tabla: la pregunta que nadie había hecho, lo que dice la spec y dónde. Cosas como que los códigos tengan seis caracteres, que la redirección sea un 302 o que Oferta sea un alias inválido en vez de convertirse a oferta.

Esa lista cambia el trabajo de revisar. No hay que leer la spec entera buscando qué se ha dado por hecho: está enumerado. Xavi revisó la lista y cuestionó una, la de guardar en Git la interfaz compilada. Era la número veinte, se cambió en minutos y es el caso que cuenta el capítulo anterior.

De la respuesta al criterio

Una respuesta todavía no es una spec. «Los alias entran en la v1» es una decisión; falta convertirla en frases que se puedan comprobar. El formato que usa acorta, y medio mundo, tiene tres partes:

• Dado: la situación de partida.
• Cuando: lo que ocurre.
• Entonces: lo que se puede comprobar después.

Pruébalo. El primer ejemplo es lo que sale a la primera; los otros tres son criterios reales de la spec de acorta.

Las comprobaciones son de forma, no de sentido: que estén las tres partes, que no haya palabras que escondan una decisión y que el Entonces diga algo que se vea desde fuera. «Funciona correctamente» no se puede comprobar. «El código del enlace es oferta-otono» sí.

Mira el tercer ejemplo real, BOR-01. Pasa, pero con un aviso: su Dado es «un código que existe», sin ejemplo. Es un criterio válido, y aun así quien escriba su test tiene que inventarse el código. Un ejemplo concreto en el Dado es medio test escrito.

Tampoco tienes que redactar tú los cien criterios. Los redacta el modelo, que para eso es rápido. Lo que haces tú es leerlos con estas tres preguntas en la cabeza.

El encargo completo

Junto, queda un encargo que cabe en un párrafo y sustituye al de una línea:

Quiero <la idea, en una frase, y para quién es>.

No escribas código todavía.

1. Hazme solo las preguntas cuya respuesta cambie qué se construye.
   Como mucho cinco, con opciones y con tu recomendación razonada.
2. Con mis respuestas, escribe la especificación en specs/: qué hace,
   qué queda fuera, y criterios numerados Dado / Cuando / Entonces
   con los mensajes de error exactos.
3. Aparte, enumera todo lo que hayas decidido tú sin preguntarme:
   la pregunta, lo que has decidido y dónde está en la spec.

El tercer punto es el que casi nadie pide y el que más vale. Sin él vuelves al capítulo 1, solo que con las decisiones escondidas en un documento en vez de en el código.

¿Quién le dice que pregunte?

Hasta aquí parece que basta con acordarse de pedirlo. No basta, y conviene ser claro con el caso de acorta: nadie escribió esa instrucción. El encargo fue una línea y no decía «pregúntame».

Que el agente preguntara, y que fueran justo cuatro preguntas con opciones y una recomendada, salió de tres sitios que no estaban en el proyecto. De la metodología que Xavi tenía escrita en otro lado. Del criterio del agente para elegir cuáles. Y de la herramienta: Claude Code le da al agente una utilidad para preguntar que admite como mucho cuatro preguntas por tanda, cada una con entre dos y cuatro opciones. El «cuatro» venía de ahí. Con otra herramienta, el mismo encargo habría empezado de otra manera.

Una instrucción así puede vivir en tres sitios:

• En el encargo, como el de arriba. Funciona, y depende de que te acuerdes cada vez.
• En la herramienta. Algunas traen un modo de planificar o de preguntar. Ayuda, pero no lo controlas tú y cambia de una a otra.
• En el fichero de reglas del proyecto, AGENTS.md, que el agente lee solo cada vez que arranca. Es el sitio bueno: se escribe una vez y vale para cualquier agente y cualquier persona.

La regla cabe en dos líneas. Esta es la de la plantilla que acompaña al tutorial:

2. **Algo nuevo empieza por preguntas, no por código.** Ante un proyecto nuevo, una
   funcionalidad nueva o un encargo ambiguo, no escribas código ni spec todavía. Haz
   como mucho cinco preguntas: solo las que cambien qué se construye, cada una con
   opciones y con tu recomendación razonada.

El número lo pones tú, y hay que ponerlo: «todas las que necesites» dio 23, 30 y 70.

¿Funciona? Lo probamos con el encargo del capítulo 1, el que puso a programar a once agentes. Copiamos la plantilla a dos carpetas vacías, arrancamos un agente nuevo en cada una y les dimos esa misma línea, sin añadir nada. Uno hizo cuatro preguntas y el otro cinco, los dos con opciones y recomendación, y ninguno escribió código. Las respuestas completas están en la página de la plantilla.

De qué más conviene poner en ese fichero, y qué no, trata el capítulo 6. La plantilla ya trae uno listo para usar.

Lo que viene

Ya hay un contrato. Queda algo que lo haga cumplir, porque una spec que nadie comprueba envejece igual que cualquier otro documento. El capítulo siguiente trata de los tests, y de por qué con una IA hay que escribirlos antes que el código y verlos fallar.