Cómo darle a tu agente de programación de IA una "definición de terminado" clara

Cuando un compañero humano toma un ticket ambiguo, llena los vacíos con criterio y hace preguntas. Un agente de programación de IA no hace ninguna de las dos cosas. Lee tu solicitud, escribe el código, ejecuta las comprobaciones que puede y declara terminada la funcionalidad, a menudo sin una sola pregunta aclaratoria. Como lo expresa una guía, cuando le entregas requisitos difusos a un agente, "la holgura no se absorbe: se construye."

Eso convierte tu definición de terminado en lo que mayor efecto multiplicador tiene de todo lo que puedes escribir. Esta guía explica cómo escribir una sobre la que un agente pueda realmente actuar.

Criterios de aceptación vs. definición de terminado

Dos ideas relacionadas que conviene mantener separadas:

• Los criterios de aceptación son específicos de cada funcionalidad: lo que este trabajo concreto debe hacer para considerarse correcto.
• La definición de terminado es de alcance global del proyecto: los controles de calidad que todo cambio debe superar antes de publicarse: pruebas, revisión, documentación, no haber subido secretos.

Piensa en los criterios de aceptación como "¿construimos lo correcto?" y en la definición de terminado como "¿lo construimos según nuestro estándar?". Tu agente necesita ambos. (Atlassian tiene una buena introducción a la distinción.)

Hazla verificable, no aspiracional

La prueba para un buen criterio: ¿podría un script —o el propio agente— comprobar si es cierto? "El formulario de inicio de sesión debería sentirse rápido" es inverificable. Reescríbelo como algo con un límite concreto:

• Enviar credenciales válidas redirige a /dashboard en menos de 500 ms
• Enviar una contraseña incorrecta muestra un error en línea y no navega a otra página
• Enviar un campo vacío se bloquea del lado del cliente antes de cualquier petición de red
• Los inicios de sesión fallidos se limitan a 5 intentos por minuto por IP

Cada línea es algo que el agente puede construir y confirmar. El consejo de Addy Osmani sobre escribir una buena especificación para agentes de IA es centrarse en el qué y el porqué, no en el cómo línea por línea: describe la intención y las restricciones, y deja que el agente elija la implementación.

Un ejemplo concreto

Compara estos dos prompts para la misma tarea.

Ambiguo:

Añade una forma de que los usuarios restablezcan su contraseña.

Con una definición de terminado:

Añade un flujo de restablecimiento de contraseña. Terminado significa:

• Un endpoint POST /auth/reset-request acepta un correo electrónico y siempre devuelve 200 (nunca revelar si el correo existe)
• Se envía por correo un token firmado, de un solo uso y válido durante 1 hora, mediante el mailer existente en src/lib/mail.ts
• POST /auth/reset-confirm valida el token, aplica la política de contraseñas actual e invalida el token tras su uso
• Las pruebas cubren: restablecimiento válido, token expirado, token reutilizado, correo desconocido
• Sin nuevas dependencias sin señalarlas primero

La segunda versión no es más larga por ser burocrática: es más larga porque cada ambigüedad que el agente adivinaría de otro modo queda ahora decidida. Las decisiones sensibles a la seguridad (no filtrar la existencia de la cuenta, expirar los tokens, uso único) son precisamente las que menos quieres que un agente improvise.

Integra el "terminado" en el bucle del agente

El verdadero poder de una definición de terminado verificable es que cierra el bucle de retroalimentación del agente. Un ciclo agéntico de codificar → probar → corregir → repetir solo converge si hay un objetivo claro que alcanzar. Cuando tus criterios se corresponden con pruebas reales, el agente puede ejecutarlas, ver los fallos y corregir su propio trabajo antes de devolvértelo.

Así que no te limites a describir el terminado: dale al agente una forma de comprobarlo:

• Indícale el comando de pruebas (npm test, pytest) y dile que la funcionalidad no está terminada hasta que pasen.
• Para cosas difíciles de verificar en código —legibilidad, seguir un patrón existente— usa una pasada de LLM como juez: un segundo prompt que revise la salida frente a tu listón de calidad. Anthropic y otros han comprobado que esto es eficaz para comprobaciones subjetivas.
• Mantén la seguridad y el "nada de código de marcador de posición/simulado" en tu definición de terminado global del proyecto, para que se aplique a cada cambio, no solo a los que te acuerdes de mencionar.

Ponla donde el agente la vea

Escribe tu definición de terminado global del proyecto una sola vez, en un archivo que el agente lea automáticamente: un AGENTS.md o CLAUDE.md en la raíz del repositorio. Los criterios de aceptación específicos de cada funcionalidad van en el propio prompt de la tarea. De ese modo "nuestro estándar" está siempre en contexto, y solo tienes que detallar lo que es propio del trabajo de hoy.

El cambio es sutil, pero es todo el juego: con un agente capaz, tus criterios de aceptación dejan de ser una nota para un colega y se convierten en la especificación contra la que se construye el código. Escríbelos como tal.