Cómo escribir criterios de aceptación que un agente pueda verificar

Escribir criterios de aceptación que un agente pueda verificar es la habilidad más crítica para los desarrolladores que pasan de la codificación manual a flujos de trabajo agénticos. Cuando escribimos requerimientos para colegas humanos, a menudo confiamos en el contexto compartido y la intuición. Los humanos pueden inferir que un botón debería ser azul si el resto de la aplicación es azul. Los agentes de IA, sin embargo, operan con instrucciones literales y comprobaciones deterministas. Para aprovechar al máximo herramientas como Claude Code u OpenCode, tus especificaciones deben alejarse de "la funcionalidad debe funcionar" y dirigirse hacia "el siguiente comando debe devolver un código de salida cero".

El cambio hacia el desarrollo agéntico requiere un enfoque más riguroso en la definición. Si un agente no puede confirmar programáticamente que una tarea está completa, es probable que la tarea esté mal definida. Este artículo explora cómo estructurar tus requerimientos para que tus herramientas de IA locales puedan demostrar su propio éxito.

La brecha entre la intención y la verificación

Los criterios de aceptación tradicionales se centran en el "qué" desde la perspectiva del usuario. Para un agente, el "qué" debe estar vinculado al "cómo se prueba". Si le pides a un agente que "mejore el rendimiento del script de inicio de sesión", el agente podría refactorizar el código pero no tener forma de verificar la mejora.

Un criterio verificable sería: "El script de inicio de sesión debe ejecutarse en menos de 200 ms al ser probado con el script de benchmark proporcionado". Esto le da al agente un objetivo claro y un método para comprobar su progreso. En un entorno de paneles múltiples como Deska, puedes ver este proceso desarrollarse en tiempo real. Podrías tener un panel de terminal ejecutando el benchmark mientras el panel del agente itera sobre el código.

Estructuración de criterios para el consumo de LLM

Los agentes funcionan mejor cuando los criterios se dividen en unidades atómicas y probables. Utiliza la siguiente estructura para asegurar que tu agente tenga un camino claro hacia la finalización.

Definición de terminado como código

Siempre que sea posible, define los criterios de aceptación como un caso de prueba fallido. Si estás utilizando agentes de codificación como Codex CLI o Claude Code, comienza pidiendo al agente que cree una prueba que reproduzca la característica faltante o el error. Una vez que la prueba existe, el criterio es simple: la prueba debe pasar.

Restricciones ambientales precisas

Los agentes necesitan conocer los límites de su espacio de trabajo. Especifica rutas, variables de entorno y dependencias esperadas. Debido a que Deska es una aplicación local-first, el agente tiene acceso a tu sistema de archivos real. Debes especificar exactamente en qué directorios debe enfocarse para evitar que deambule por partes no relacionadas de tu código base.

Verificación visual y de interfaz de usuario

Verificar cambios en la interfaz de usuario es históricamente difícil para los agentes de CLI. Sin embargo, al usar agentes dentro de un espacio de trabajo que incluye widgets de navegador, puedes instruir al agente para que revise la estructura del DOM o ejecute pruebas de Playwright. Sé específico sobre los selectores CSS o los roles ARIA en lugar de descripciones visuales como "haz que parezca moderno".

Comparación de métodos de verificación

Diferentes agentes y herramientas manejan la verificación de diversas maneras. Es importante elegir el enfoque correcto según la complejidad de tu tarea.

Aunque las herramientas difieren en su enfoque, el objetivo sigue siendo el mismo: reducir la ambigüedad del estado "terminado". Algunas herramientas enfatizan la ejecución en la nube, mientras que otras se enfocan en el entorno local. Deska te permite ejecutar estos agentes lado a lado para que puedas comparar cómo diferentes modelos interpretan el mismo conjunto de criterios.

Uso del espacio de trabajo para validar

El beneficio de un lienzo infinito es la capacidad de mantener el contexto. Al escribir criterios de aceptación, puedes usar notas para redactar tus requerimientos antes de entregarlos al agente.

1. Abre un panel de Notas y enumera los requerimientos técnicos específicos.
2. Usa Ask Deska para abrir las terminales y paneles de editor necesarios.
3. Pega los requerimientos en el panel del agente (por ejemplo, Claude Code).
4. Monitorea al agente mientras ejecuta comandos en los paneles de terminal.
5. Verifica el resultado en un panel de navegador o ejecutando una suite de pruebas final.

Este flujo de trabajo asegura que el agente no esté operando en el vacío. Tú proporcionas los criterios y el espacio de trabajo proporciona la infraestructura para la verificación. Si estás lejos de tu escritorio, puedes usar la aplicación móvil para revisar si el agente ha terminado su tarea y ha pasado los criterios que definiste.

Gestión de hilos de agentes complejos

Para funcionalidades más grandes, un solo prompt rara vez es suficiente. Debes dividir el proyecto en múltiples hilos de agente. Cada hilo debe tener su propio subconjunto de criterios de aceptación. Esto evita que el agente pierda el contexto o se vea abrumado por una lista masiva de requerimientos.

Por ejemplo, si estás construyendo un nuevo módulo de autenticación:

• Hilo 1: Esquema de base de datos y migraciones.
• Hilo 2: Endpoints de API backend y pruebas unitarias.
• Hilo 3: Formulario de inicio de sesión frontend y lógica de validación.

Cada hilo termina solo cuando se cumplen sus criterios específicos. Este enfoque modular facilita la depuración cuando un agente no logra cumplir con un requerimiento particular.

Preguntas frecuentes

¿Cómo escribo criterios para que un agente refactorice código heredado?

Céntrate en las pruebas de regresión. El criterio principal debe ser que todas las pruebas existentes pasen después de la refactorización. Si las pruebas no existen, el primer requerimiento debe ser que el agente escriba una suite de pruebas que capture el comportamiento actual antes de realizar cualquier cambio.

¿Pueden los agentes verificar requerimientos de accesibilidad?

Sí, si proporcionas las herramientas específicas. Puedes incluir un criterio que requiera que el agente ejecute un linter de accesibilidad o una comprobación de navegador headless utilizando una herramienta automatizada como Axe. Especifica la puntuación objetivo o la ausencia de tipos de error específicos.

¿Qué pasa si el agente afirma que cumplió los criterios pero no es así?

Esto suele suceder cuando los criterios son demasiado vagos. Ajusta los requerimientos agregando un "comando de verificación". En lugar de "asegura que la API sea rápida", usa "asegura que curl devuelva una respuesta en menos de 50 ms". Si el agente falla, puedes usar Ask Deska para señalar la discrepancia específica.

Comienza con flujos de trabajo agénticos

La transición al desarrollo dirigido por agentes es más fácil cuando tienes el entorno adecuado para monitorear y verificar su trabajo. Deska proporciona el lienzo, las terminales y la integración de agentes que necesitas para mantener el control del proceso.

Puedes descargar la aplicación para Mac, Windows o Linux para comenzar a construir tus propios flujos de trabajo verificables hoy mismo. Ya sea que uses un plan de por vida con tus propias llaves o una suscripción gestionada, el espacio de trabajo está diseñado para mantener tu código local y tus agentes productivos.