English

Escribe primero la especificación

Dile a un agente "agrega login" y llenará cada espacio en blanco que dejaste abierto: qué método de autenticación, si hay un flujo de restablecimiento de contraseña, si puede agregar libremente una nueva dependencia para resolverlo. Ninguna de esas suposiciones es incorrecta exactamente: simplemente no son tus decisiones. Te enteras una hora después, tras deshacer la equivocada.

El problema: los prompts vagos obligan a adivinar

"Agrega autenticación" es un objetivo, no una especificación. No dice qué estrategia de tokens, si el restablecimiento de contraseña está dentro del alcance, ni si el agente puede recurrir a una nueva biblioteca para llegar más rápido. Un agente que enfrenta ese vacío hace lo único razonable: elige la respuesta más común. A veces está bien. A menudo no lo está, y solo te enteras después de que el código está escrito, probado y revisado a medias.

Una especificación cierra ese vacío antes de que el agente empiece. No necesita ser un documento formal. Necesita cuatro cosas: qué estás construyendo, por qué, qué queda explícitamente fuera de alcance y las tareas concretas que te llevan hasta ahí.

Qué va en una especificación de una página

Compara las dos:

• Vaga: "agrega autenticación"
• Clara: "tokens JWT, sin restablecimiento de contraseña, sin nuevas dependencias"

Esa sola línea elimina tres decisiones que el agente habría tomado por ti. No son más palabras porque sí: cada cláusula descarta una suposición específica. "Tokens JWT" elige la estrategia de autenticación. "Sin restablecimiento de contraseña" acota el alcance. "Sin nuevas dependencias" restringe la implementación a lo que ya existe en el proyecto.

Una especificación útil responde:

• Qué estás construyendo, en una o dos frases.
• Por qué — la restricción o el objetivo que lo impulsa (para que el agente pueda tomar decisiones de criterio que sigan sirviendo a la intención).
• Qué queda fuera de alcance — las cosas que no debe hacer, que suele ser justo la parte que un prompt simple se salta por completo.
• La lista de tareas — la funcionalidad dividida en piezas pequeñas y ordenadas.

Cómo ejecutarla

1. Escribe la especificación.
2. Elige la siguiente tarea de la lista.
3. Haz que el agente implemente solo esa tarea.
4. Revisa el diff.
5. Haz commit.
6. Pasa a la siguiente tarea.

Este ciclo te mantiene en control en cada paso, en lugar de revisar un solo diff gigante al final, donde los errores son más difíciles de aislar y más costosos de deshacer. Los commits pequeños también te dan un punto de rollback limpio si una tarea se tuerce: reviertes un commit, no el trabajo de un día.

Cuándo vale el esfuerzo

Una especificación de una página es exagerada para un arreglo de una línea: no escribas una para cambiar el color de un botón. Rinde en cualquier cosa con superficie real: una funcionalidad nueva, una integración complicada, cualquier situación donde un agente trabajando desde un prompt escueto tendría que adivinar más de una cosa.

Trucos avanzados

• Las especificaciones no están congeladas. Si una tarea revela que una restricción en realidad no funciona —digamos, "sin nuevas dependencias" resulta que vuelve la verificación JWT irrazonablemente engorrosa— vuelve atrás, edita la especificación y reejecuta esa tarea.
• Restringe resultados, no la estructura del código. Una especificación debe fijar decisiones como la estrategia de autenticación y el alcance, no dictar los detalles exactos de implementación: deja al agente espacio para escribir código idiomático dentro de tus restricciones.
• Nunca agrupes la revisión de tareas. El sentido de dividir la especificación en tareas es la revisión granular: revisar todo al final lo anula.