Spec vs. prompt
La primera vez que usas Claude Code para algo complejo, el reflejo es escribir un prompt largo: "Hazme una app de tal cosa con tal feature". Funciona para prototipos — pero en la segunda semana te das cuenta de que no puedes reproducir tu propio trabajo. El agente hizo algo distinto cada vez. El código final no refleja ninguna decisión escrita; solo refleja la última conversación que tuviste antes de irte a dormir. El spec resuelve eso: mueve la autoridad del chat efímero a un documento que vive en el repo.
Un prompt pide acción una vez; un spec describe el comportamiento esperado y se mantiene como la fuente de verdad del feature.
La diferencia estructural
Un prompt es un mensaje en un canal: "agrega login con Google". Se evalúa por su output inmediato y se desecha. Si algo sale mal, vuelves a escribir otro prompt.
Un spec es un archivo (idealmente en /specs/ dentro del repo) que describe:
- Contexto: qué parte del sistema toca, qué supuestos hace.
- Comportamiento esperado: input → output, estados, transiciones.
- Casos edge: qué pasa si X falla, si Y está vacío, si Z concurrente.
- Criterios de aceptación: cómo saber que está "hecho".
El spec sobrevive al cierre del chat. La próxima sesión — tuya o de otro agente — empieza leyéndolo.
Por qué importa con agentes
Los agentes olvidan. Su context window se vacía al cerrar la sesión, y aunque tenga memoria, no reconstruye el razonamiento. Si la decisión está en el prompt, la decisión se pierde.
Con spec, el agente puede:
- Leer el spec antes de escribir código.
- Generar tests que validen los criterios de aceptación.
- Reportar diffs entre el comportamiento actual y el esperado cuando algo se rompe.
- Retomar trabajo interrumpido sin que tengas que re-explicar.
Cuándo usar cada uno
- Prompt suelto: exploración, prototipos desechables, one-shots ("renombra esta función", "arregla este typo").
- Spec: cualquier feature que vayas a operar en producción o que otros (incluido tu yo-del-mes-que-viene) vayan a tocar.
La regla práctica: si vas a escribir más de ~50 líneas de código para implementarlo, escribe el spec primero.
Toma la última feature que pediste a un agente por prompt. Escríbela ahora como spec de 10–15 líneas con contexto, comportamiento, al menos 2 casos edge y 3 criterios de aceptación. Si al terminar te das cuenta de decisiones que no habías pensado, ese es exactamente el valor del spec.
- El prompt pide una acción y se desecha; el spec describe comportamiento esperado y vive en el repo.
- Con agentes que olvidan, el spec es lo que convierte decisiones en algo reproducible.
- Si un feature pasa de ~50 líneas, escribe el spec antes de pedir código.