Una spec es memoria de trabajo, no ceremonia

Hay dos formas de escribir una especificación. Una es el documento que nadie lee, que se aprueba en un comité y queda desactualizado a la semana. La otra es un texto corto que existe para que mañana puedas retomar el trabajo sin reconstruir todo el razonamiento desde cero.

La segunda es la que sirve, y se volvió mucho más importante desde que trabajamos con asistentes de IA.

El problema real

Cuando delegas una tarea a un modelo, el resultado depende casi por completo de qué tan claro esté el encuadre. Un pedido vago produce trabajo vago, y lo peor es que produce trabajo vago que parece correcto. Revisar eso cuesta más que haberlo especificado bien desde el principio.

El costo no aparece en la primera iteración. Aparece en la tercera, cuando alguien pregunta por qué se tomó una decisión y nadie recuerda si fue deliberada o si el modelo simplemente eligió por defecto.

Qué hace útil a una spec ligera

No es la extensión. Es que responda tres cosas que el código no puede responder solo:

Qué problema se está resolviendo. No la funcionalidad, el problema. “Agregar un botón de exportar” es una funcionalidad; “el equipo de operaciones necesita los datos del mes en Excel porque su contador no entra al sistema” es un problema. La segunda formulación descarta cinco implementaciones malas de una.

Qué decisiones ya están tomadas y por qué. Esto es lo que se pierde primero. Si decidiste no usar una cola de mensajes, escribe la razón. Dentro de dos meses la razón va a parecer arbitraria, y sin ella alguien la va a revertir.

Qué queda explícitamente fuera. Los límites son más informativos que el alcance. Decir “esto no maneja archivos de más de 50 MB” evita una discusión completa más adelante.

Por qué esto cambia con IA de por medio

Un asistente no tiene contexto entre sesiones. Cada vez que retomás el trabajo, el contexto se reconstruye desde lo que esté escrito. Si no hay nada escrito, se reconstruye desde el código, que muestra qué se hizo pero nunca por qué.

Una spec ligera es, literalmente, la memoria de trabajo del proyecto. No es un artefacto de proceso: es la diferencia entre dirigir el trabajo y descubrir qué pasó.

Lo que no recomendamos

No recomendamos plantillas largas. Una spec de diez secciones obligatorias se completa a medias y deja de leerse. Si el documento no cabe en una pantalla, probablemente esté mezclando decisión con documentación.

Tampoco recomendamos escribirla después. Una spec redactada al final del trabajo describe lo que pasó, no lo que se decidió. Sirve como registro, no como herramienta.

En la práctica

En los proyectos donde acompañamos equipos, la spec suele ser media página por cada cambio significativo: problema, decisiones con su razón, límites. Se escribe antes, se corrige durante, y se archiva cuando el cambio se entrega.

El resultado medible no es un documento mejor. Es que las revisiones dejan de ser arqueología.