Especificaciones que la IA entiende

En el experimento de la lección anterior, el agente decidió por ti decenas de cosas: si los pedidos van por kilo o por paquete, si hay entregas en domingo, si se cobra en línea. Algunas las adivinó bien. Otras no. Ninguna fue una decisión de Rosa.

La forma de evitarlo no es escribir prompts más largos en el chat. Es escribir una especificación corta, guardarla en el repositorio y pedirle al agente que trabaje a partir de ella. En esta lección escribes la de Tortillería La Güera.

Al terminar podrás:

• escribir una especificación de una página con las cinco secciones que importan;
• redactar criterios de aceptación que se puedan comprobar con una prueba;
• usar al agente para que te entreviste y encuentre huecos, sin delegarle las decisiones;
• reconocer las frases vagas que provocan suposiciones.

Qué es y qué no es un spec para trabajar con IA

Una especificación, o spec, es un documento que dice qué se va a construir y cómo sabremos que está terminado. No es un documento de diseño técnico ni un manual. Para trabajar con un agente, el spec cumple tres funciones:

1. Fija las decisiones del negocio para que el agente no las invente.
2. Define qué significa "terminado" con criterios que el agente puede comprobar.
3. Marca los límites de lo que no se debe construir, para que el agente no agregue cosas "por si acaso".

Una página es suficiente para casi cualquier funcionalidad. Si tu spec pasa de dos páginas, probablemente estás describiendo varias funcionalidades a la vez y conviene separarlas.

Las cinco secciones

Usa siempre la misma estructura. Así el agente y tu equipo saben dónde buscar cada cosa.

La última sección es la que más se olvida y la que más le sirve al agente. Si no dices que el pago en línea queda fuera, es probable que aparezca un módulo de pagos a medio hacer.

Criterios de aceptación verificables

Un criterio de aceptación es una frase que, frente a la app terminada, se responde con sí o no. La prueba de fuego es preguntarte: ¿podría escribir una prueba automática para esto?

Compara:

Un formato que ayuda es "Dado, cuando, entonces":

Dado que hoy es miércoles a las 19:00,
cuando alguien pide 5 kilos para el jueves a las 8:00,
entonces el pedido se rechaza con el mensaje
"Los pedidos para mañana se aceptan hasta las 18:00".

Este formato obliga a fijar el contexto (qué día y hora es), la acción y el resultado esperado, incluido el mensaje. Y se traduce casi directo a una prueba con pytest, como verás en el módulo 2.

El spec de Tortillería La Güera

Este es el spec completo de la primera versión. Guárdalo como docs/SPEC.md en tu repositorio.

# Spec: Pedidos de Tortillería La Güera (v1)

## Problema
Los pedidos de fondas, taquerías y familias llegan por WhatsApp y se
anotan en una libreta. Cada semana hay al menos un error de cantidad o de
hora. El tortillero no sabe con anticipación cuántos kilos preparar por hora.

## Usuarios
- Clientes frecuentes (fondas y taquerías de la colonia): piden la víspera,
  casi siempre lo mismo, desde el celular.
- Personal de mostrador (el sobrino de Rosa): captura los pedidos que llegan
  por WhatsApp.
- Tortillero (Don Chuy): consulta cada mañana cuánto preparar por hora.

## Historias
H1. Como cliente, quiero hacer un pedido desde la web indicando kilos, fecha
    y hora de entrega, para no depender de que alguien lea WhatsApp.
H2. Como personal de mostrador, quiero capturar un pedido que llegó por
    WhatsApp, para que quede en el mismo lugar que los de la web.
H3. Como tortillero, quiero ver los kilos por hora de un día, para preparar
    la masa a tiempo.

## Criterios de aceptación
CA1. Un pedido tiene: nombre del cliente (2 a 80 caracteres), teléfono de
     10 dígitos, kilos, fecha y hora de entrega, y canal ("web" o "whatsapp").
CA2. Los kilos van de 0.5 a 20, en múltiplos de 0.5. Fuera de eso, error 422.
CA3. Horas de entrega válidas: 7:00 a 13:00, a la hora en punto.
CA4. No hay entregas en domingo.
CA5. La fecha de entrega debe ser posterior a hoy (hora de Puebla).
CA6. Los pedidos para mañana se aceptan hasta las 18:00 de hoy.
CA7. Precio: 28 pesos por kilo. El total se guarda en centavos (entero).
CA8. Al crear un pedido válido se responde 201 con el id y el total.
CA9. GET /pedidos?fecha=AAAA-MM-DD lista los pedidos del día ordenados por hora.
CA10. GET /produccion?fecha=AAAA-MM-DD devuelve los kilos totales por hora.
CA11. Todos los mensajes de error están en español y dicen qué corregir.

## Fuera de alcance (v1)
- Pagos en línea. Se paga al recibir.
- Integración automática con la API de WhatsApp.
- Cuentas de usuario e inicio de sesión de clientes.
- Otros productos (totopos, masa). Solo tortilla de maíz.
- Rutas de reparto.

## Verificación de punta a punta
Con la app corriendo, crear un pedido válido por web, uno por WhatsApp y uno
inválido por cada criterio CA2 a CA6; consultar /pedidos y /produccion del
día y comprobar que los números cuadran.

Fíjate en algunos detalles. Los usuarios tienen nombre y situación concreta. Los criterios están numerados, así podrás referirte a ellos desde el plan, las pruebas y los commits ("cubre CA4"). La zona horaria aparece explícita en CA5 porque es justo el tipo de detalle que un agente ignora. Y hay una sección final de verificación de punta a punta: la documentación de Claude Code recomienda terminar los specs con un paso que pruebe que la funcionalidad funciona completa, y es un buen hábito con cualquier herramienta.

Deja que el agente te entreviste

No tienes que escribir el spec solo. Una técnica útil es pedirle al agente que te haga preguntas antes de redactar nada. Su trabajo es encontrar huecos; el tuyo, responderlos con información real del negocio.

Voy a construir una app de pedidos para una tortillería en Puebla.
Te pego mis notas abajo. Antes de escribir cualquier cosa, entrevístame:
hazme preguntas de una en una sobre reglas del negocio, casos raros y
decisiones que yo no haya tomado. No me preguntes cosas técnicas de
implementación todavía. Cuando ya no tengas preguntas importantes,
escribe un borrador en docs/SPEC.md con estas secciones: Problema,
Usuarios, Historias, Criterios de aceptación (numerados y verificables),
Fuera de alcance y Verificación de punta a punta.

Notas:
- venden tortilla de maíz por kilo, 28 pesos
- entregan en la mañana a fondas y taquerías
- los pedidos llegan por WhatsApp

En Claude Code, el agente puede usar su herramienta de preguntas con opciones para hacerte la entrevista. En otras herramientas lo hará como mensajes normales. En ambos casos, cuidado con una trampa: si no sabes la respuesta, no dejes que el agente la decida. Escribe "pendiente, preguntar a Rosa" y pregunta. Un spec con huecos marcados es mejor que uno con suposiciones escondidas.

Preguntas que un buen agente hará en este caso, y que tal vez no habías pensado: ¿qué pasa si una taquería pide para el mismo día? ¿Un cliente puede cambiar un pedido? ¿Hay un máximo de kilos por hora que la máquina pueda producir? Esta última es interesante: la respuesta de Rosa fue "unos 60 kilos por hora". No entra en la v1, pero la anotas en Fuera de alcance como "límite de capacidad por hora, para v2".

Revisa el borrador como si fueras el agente

Cuando tengas el borrador, léelo con la mirada de alguien que va a implementarlo sin poder preguntarte nada. Busca:

1. Palabras sin número: "pocos", "rápido", "temprano", "grande". Cámbialas por cifras.
2. Reglas sin dueño: "se valida el horario". ¿Qué horario? ¿Qué pasa si no cumple?
3. Mensajes no definidos: si el error importa al usuario, escribe el texto.
4. Zona horaria y unidades: hora de Puebla, centavos, kilos. Siempre explícito.
5. Criterios que dependen de otros sistemas: si dice "se notifica por WhatsApp", eso es otra funcionalidad entera.

También puedes pedirle a una sesión nueva del agente que haga esta revisión:

Lee docs/SPEC.md. Eres quien va a implementarlo y no podrás hacerme
preguntas después. Lista cada punto donde tendrías que adivinar algo,
citando la línea. No propongas soluciones, solo los huecos.

Pedirlo en una sesión nueva importa: la sesión que redactó el spec tiende a leerlo con lo que ya "sabe" y no ve los huecos.

Práctica

Escribe el spec real de tu proyecto:

1. Crea docs/SPEC.md en el repositorio tortilleria-la-guera que iniciaste en la lección anterior.
2. Abre una sesión del agente y usa el pedido de entrevista de esta lección con tus propias notas. Responde las preguntas; marca como "pendiente" lo que no sepas.
3. Compara el borrador del agente con el spec de ejemplo. Agrega lo que falte y quita lo que el agente haya inventado.
4. Revisa cada criterio de aceptación con la pregunta "¿podría escribir una prueba para esto?". Reescribe los que no pasen.
5. En una sesión nueva, pide la revisión de huecos con el segundo pedido de esta lección. Corrige el spec.
6. Abre notas/experimento-1.md y comprueba cuántas de las suposiciones del experimento quedaron resueltas por el spec.
7. Haz commit: git add docs/SPEC.md && git commit -m "docs: spec v1 de pedidos".

Quiz

Resumen

• Un spec para trabajar con IA fija decisiones del negocio, define "terminado" y marca límites.
• Usa cinco secciones: problema, usuarios, historias, criterios de aceptación y fuera de alcance, más una verificación de punta a punta.
• Cada criterio debe responderse con sí o no; numéralos para citarlos en el plan, las pruebas y los commits.
• Deja que el agente te entreviste para encontrar huecos, pero las respuestas del negocio las das tú.
• Revisa el borrador en una sesión nueva buscando palabras sin número, reglas sin dueño y unidades implícitas.