Criterios de Aceptación que los Agentes Pueden Verificar

Redactar criterios de aceptación efectivos sigue siendo una de las partes más difíciles de la ingeniería de software. Cuando los humanos leen requisitos, dependen de la intuición y el contexto compartido para llenar los vacíos. Sin embargo, a medida que nos movemos hacia una era de desarrollo autónomo, debemos aprender a escribir criterios de aceptación que los agentes puedan verificar sin intervención humana. Un agente de IA carece de la capacidad de adivinar lo que quisiste decir si las especificaciones son ambiguas. Si un agente no puede verificar un requisito mediante un comando de terminal, una comprobación de navegador o una prueba unitaria, ese requisito está incompleto.

El cambio de la narrativa a la verificación

Las historias de usuario tradicionales se centran en el valor para el usuario, utilizando a menudo la plantilla clásica de "Como, quiero, para que". Aunque esto es útil para los gestores de producto, suele ser demasiado vago para un agente de codificación de IA. Cuando un agente recibe una tarea, necesita una definición de terminado que sea binaria. O el código cumple con el requisito, o no lo hace.

Para lograr esto, los desarrolladores deben pasar de una redacción descriptiva a especificaciones verificables. En lugar de decir que la interfaz de usuario debe ser rápida, debes definir un umbral específico para una métrica de rendimiento. En lugar de decir que el inicio de sesión debe ser seguro, debes especificar el algoritmo de hashing exacto y la respuesta esperada para los intentos fallidos. Este enfoque se alinea estrechamente con los principios del desarrollo dirigido por pruebas, pero se extiende más allá de las pruebas unitarias para incluir estados ambientales y visuales.

Componentes de los criterios de aceptación verificables

Un criterio verificable debe tener una entrada clara, un resultado esperado y un método de observación. Si alguno de estos tres elementos falta, el agente probablemente alucinará o producirá código que pase su propia lógica interna pero falle en el mundo real.

• Indica las condiciones iniciales: El agente necesita saber cómo se ve el entorno antes de que ocurra la acción.
• Define la acción específica: Usa verbos precisos como "ejecutar", "renderizar" o "persistir" en lugar de "manejar" o "procesar".
• Especifica el método de observación: Dile al agente cómo comprobar su trabajo. Esto podría ser un comando curl a una API, un grep en un archivo de log o un selector específico en un navegador sin cabecera.

Al usar herramientas como Claude Code o Codex CLI dentro de los coding agents, proporcionar estos tres pilares permite que el agente se corrija a sí mismo. Si el agente ejecuta un comando y el resultado no coincide con tus criterios, puede iterar sobre el código hasta que la salida de la terminal se alinee con la especificación.

Una receta para especificaciones amigables para agentes

Para escribir criterios que los agentes realmente puedan verificar, sigue esta receta estructurada para cada característica importante o corrección de errores. Esta estructura asegura que el agente se mantenga dentro de los límites de tu arquitectura pretendida.

1. La ruta de ejecución

Define los archivos exactos que deben modificarse y dónde debe residir la nueva lógica. Aunque los agentes pueden explorar una base de código, son más eficientes cuando se les da un punto de partida. Dentro del canvas de Deska, puedes colocar tu panel de notas junto a tu editor de código para mantener estas instrucciones visibles tanto para ti como para el agente.

2. El comando de éxito

Cada requisito debe ir acompañado de un comando que devuelva un código de salida cero cuando tenga éxito. Esto podría ser la ejecución de una suite de pruebas, una comprobación de linter o un script personalizado. Por ejemplo, si estás construyendo un nuevo endpoint de API, el criterio debería ser que un comando curl específico devuelva un estado 200 OK con un esquema JSON determinado.

3. Aserciones visuales y del DOM

Para tareas de frontend, los agentes necesitan saber qué buscar en el resultado renderizado. Si estás usando browser widgets, puedes instruir al agente para que verifique que una clase CSS específica esté presente o que un botón no esté deshabilitado después de cierto evento.

Comparación de métodos de verificación

Diferentes tipos de desarrollo requieren diferentes estrategias de verificación. La siguiente tabla compara cómo interactúan los agentes con varias capas de prueba.

Aprovechando Deska para la verificación de agentes

Deska proporciona un entorno único para este flujo de trabajo debido a su arquitectura local-first. Cuando un agente se ejecuta en un panel, tiene acceso directo a tu sistema de archivos local y a tus terminales. Esto elimina la latencia y los problemas de seguridad asociados con los entornos basados en la nube donde los agentes están aislados del contexto de ejecución real.

Puedes usar el asistente Ask Deska para coordinar múltiples agentes. Por ejemplo, puedes tener un agente escribiendo código en un panel mientras otro agente ejecuta un script de monitoreo en una de las terminals. Debido a que el espacio de trabajo es un lienzo infinito, puedes organizar estos paneles en relación con tus especificaciones técnicas, asegurando que el agente tenga todo el contexto de tus documentos de requisitos.

Si estás lejos de tu escritorio, la aplicación mobile te permite monitorear estos pasos de verificación. Puedes ver si un agente ha terminado una suite de pruebas larga y revisar la salida de la terminal directamente desde tu teléfono. Esto crea un bucle continuo donde el agente trabaja contra tus criterios verificables mientras tú proporcionas supervisión de alto nivel.

Errores comunes en las especificaciones para agentes

Incluso con un enfoque estructurado, es fácil volver a caer en la redacción centrada en humanos. Evita estos errores comunes para mantener la productividad de tus agentes.

• Evita el lenguaje subjetivo: Términos como "fácil de usar", "intuitivo" o "moderno" no significan nada para un agente. Reemplázalos con patrones de UI específicos o estándares de accesibilidad.
• No asumas el estado del entorno: Instruye siempre al agente para que verifique las dependencias o variables de entorno antes de comenzar la tarea principal.
• Cuidado con la lógica circular: Si el agente escribe tanto el código como la prueba sin un criterio de aceptación predefinido por ti, simplemente escribirá una prueba que pase su código defectuoso.

FAQ

¿Cómo escribir criterios de aceptación para LLMs?

Céntrate en resultados binarios y métodos de observación específicos. Trata al agente como a un desarrollador junior que no tiene acceso al historial de tu proyecto pero tiene un conocimiento perfecto de la documentación. Dales los comandos exactos que deben ejecutar para verificar que una tarea está terminada.

¿Pueden los agentes realizar pruebas de regresión visual?

Sí, si tienen acceso a un entorno de navegador y a una imagen de referencia o estado del DOM. En un espacio de trabajo de múltiples paneles, un agente puede comparar el resultado renderizado en un panel de navegador con los requisitos establecidos en un panel de notas.

¿Debo dejar que los agentes escriban sus propias pruebas?

Solo si ya has proporcionado los criterios de aceptación de alto nivel. El agente puede generar la estructura básica para las pruebas unitarias, pero tú debes definir las aserciones. De lo contrario, el agente podría crear pruebas que reflejen sus propios malentendidos de los requisitos.

Comienza a construir con especificaciones verificables

Transicionar a criterios de aceptación verificables no solo hará que tus agentes de IA sean más efectivos, sino que también mejorará la claridad de tu propio proceso de desarrollo manual. Al definir el éxito en términos claros y ejecutables, reduces la ambigüedad y construyes software más robusto. Puedes experimentar con estos flujos de trabajo utilizando los coding agents disponibles hoy mismo.

Descarga Deska para comenzar a organizar tu espacio de trabajo de desarrollo con agentes y terminales uno al lado del otro en un lienzo local y seguro.