Nota del autor: Este artículo está dirigido a desarrolladores que ya usan Agent en su trabajo. Explica qué contexto, materiales de referencia y criterios de aceptación verificables conviene preparar antes de asignar una tarea, y qué aspectos siguen necesitando supervisión humana.
Desde que usas Agent, produces más, pero también terminas más cansado. El 3 de noviembre de 2026, un desarrollador describió esta situación en V2EX: la persona sigue dentro del ciclo, revisando los resultados y corrigiendo en todo momento los desvíos de la tarea y los problemas de diseño. Así es difícil dejar que Agent trabaje con autonomía. En la publicación se mencionaba una experiencia conocida: proporcionar más contexto y materiales de referencia ayuda a Agent a entender la tarea y mejorar la calidad de la entrega. Pero no se explicaba qué significa exactamente «más contexto».
Este no es otro artículo genérico sobre cómo escribir una buena indicación. Aquí nos centramos en la preparación antes de asignar una tarea: cómo convertir un requisito impreciso en objetivos, restricciones, materiales de referencia y criterios de finalización verificables. Así, Agent puede revisar su propio trabajo y tú solo necesitas intervenir en unos pocos momentos clave. Eso sí, por ahora no hay datos comparativos públicos que permitan cuantificar el efecto de los distintos métodos de preparación. Los casos del artículo resumen situaciones habituales; conviene comprobar los resultados en tus propias tareas.
Qué te llevarás: una estructura reutilizable para definir tareas de Agent, una forma de redactar criterios de aceptación y una guía para decidir qué puede revisar Agent por su cuenta y qué requiere una decisión humana.
Puntos clave del contexto y los criterios de aceptación para un agente
Antes de escribir la descripción de una tarea, conviene tener una idea general: cuando un agente se desvía, suele ser porque entiende de forma distinta a ti qué debe hacer, hasta dónde debe llegar o qué no puede tocar. Esta tabla recoge los cinco elementos que debe incluir una buena descripción de tarea.
| Elemento | Descripción | Problema que resuelve |
|---|---|---|
| Objetivo | Explica en una frase qué se debe entregar y para quién | Evita que el agente amplíe los requisitos por su cuenta o tome una dirección equivocada |
| Contexto | Estado actual del proyecto, módulos relacionados e intentos previos | Evita reinventar la rueda o descartar decisiones de diseño existentes |
| Restricciones | Archivos que no se pueden modificar, tecnologías obligatorias y requisitos de rendimiento o compatibilidad | Evita soluciones que funcionan, pero no sirven en la práctica |
| Referencias | Ejemplos de código existentes, documentación de interfaces y muestras de estilo | Ayuda a que el estilo y la estructura del resultado encajen con el proyecto |
| Criterios de aceptación | Condiciones de finalización comprobables una por una y, de ser posible, automáticamente | Permite que el agente revise su propio trabajo y reduce la necesidad de examinar cada línea |
Formas habituales en que un agente se desvía de la tarea
La publicación original no daba ejemplos concretos de desviaciones, así que aquí recopilamos algunas de las más comunes en agentes de programación y de ejecución de tareas. Aunque parezcan diferentes, su origen suele estar en la ausencia de algún elemento en la descripción de la tarea.
| Desviación | Causa habitual | Cómo prevenirla |
|---|---|---|
| Corrige un bug y, de paso, refactoriza medio módulo | El alcance del objetivo no está claro y no se han delimitado los cambios | Indica en las restricciones qué archivos o funciones se pueden modificar |
| Introduce una dependencia nueva que el proyecto no usa | Desconoce las tecnologías existentes | Enumera las dependencias actuales en el contexto e indica si está prohibido añadir otras |
| El estilo del código no coincide con el resto del proyecto | Faltan ejemplos de referencia | Adjunta una o dos implementaciones similares como referencia |
| Dice que ha terminado, pero no cubre escenarios clave | Los criterios de finalización son ambiguos | Redacta los criterios de aceptación como comprobaciones ejecutables |
| La solución es técnicamente viable, pero no responde a la intención del producto | Las decisiones de diseño no se explicaron de antemano | Una persona debe tomar primero las decisiones de diseño y después encargar la implementación al agente |
El último caso merece especial atención. No se debe a que falte contexto, sino a que las decisiones de diseño requieren criterio humano. Volveremos sobre este punto más adelante.
Cómo preparar una descripción de tarea para un agente: estructura en cinco partes
Al reunir los cinco elementos anteriores en un documento, obtienes una descripción que el agente puede entender y usar para comprobar su propio trabajo. Conviene mantenerla en Markdown dentro del repositorio del proyecto, por ejemplo, con el nombre TASK.md. También puedes colocar las restricciones generales en un archivo de instrucciones del proyecto, como AGENTS.md, y los objetivos concretos en el documento de cada tarea.
Primera parte: cómo definir el objetivo de la tarea
El objetivo debe explicar en una frase qué se va a entregar, para quién y en qué situación se usará. Una descripción como «optimizar el módulo de inicio de sesión» puede llevar al agente a mejorar el rendimiento, refactorizar el código o rediseñar la interfaz. Una opción más clara sería: «Hacer que la interfaz de inicio de sesión devuelva un código de error uniforme cuando la contraseña sea incorrecta, para que el frontend muestre un aviso, sin modificar el flujo de inicio de sesión correcto».
Si la tarea es relativamente grande, conviene añadir debajo del objetivo una frase que indique qué queda fuera del alcance. Las exclusiones explícitas suelen ser más eficaces que las descripciones positivas para evitar que el agente amplíe los requisitos por su cuenta.
Segunda parte: cómo proporcionar contexto al agente
Lo importante del contexto no es la cantidad, sino la relevancia. Entregarle todo el repositorio al agente no equivale a darle suficiente contexto: también necesita saber qué partes están relacionadas con la tarea. Puedes organizarlo en este orden:
- Módulos relevantes: enumera los archivos o directorios directamente relacionados con la tarea, como la lógica de inicio de sesión en
src/auth/y sus archivos de prueba. - Decisiones previas: explica por qué se diseñó así, por ejemplo: «Los códigos de error se definen de forma centralizada en el módulo
errors; no se escriben directamente en el código de negocio». - Soluciones ya probadas: si antes se intentó y descartó alguna opción, explica por qué para evitar que el agente vuelva a recorrer el mismo camino.
- Explicación de términos: aclara los términos de negocio internos del proyecto que el agente no puede deducir de forma fiable a partir del código.
Tercera parte: lista de restricciones para el agente
Las restricciones son clave para evitar resultados que «funcionan, pero no sirven». Puedes enumerar las más habituales en una lista para que el agente las revise tanto antes de empezar como al terminar:
- El alcance de los cambios permitidos y los archivos que no se pueden modificar, como los scripts de migración de bases de datos o las definiciones de interfaces públicas.
- Las restricciones de la pila tecnológica, como «no añadir dependencias de terceros» o «usar únicamente la biblioteca de registro que ya utiliza el proyecto».
- Los requisitos de compatibilidad y rendimiento, como «mantener sin cambios las firmas de las interfaces existentes».
- Cómo actuar ante situaciones inciertas, por ejemplo: «Si es necesario modificar una interfaz pública, detente y explica por qué; no la modifiques por tu cuenta».
El último punto es importante. Darle al agente una condición clara para detenerse y preguntar a una persona ahorra mucho más trabajo que descubrir después que actuó por su cuenta.
Cuarta parte: cómo elegir materiales de referencia para el agente
Los materiales de referencia ayudan al agente a seguir prácticas existentes, en lugar de partir de cero. Lo más eficaz suele ser una implementación similar dentro del mismo proyecto, por ejemplo: «Para añadir una interfaz, sigue el ejemplo de src/user/, incluidos la validación de parámetros y el manejo de errores». En cuanto a la documentación externa, proporciona solo las secciones relacionadas con la tarea e indica la versión para evitar que el agente escriba código para una interfaz obsoleta.
Cómo redactar criterios de aceptación verificables para un Agent
Los criterios de aceptación son la parte de la descripción de una tarea donde más fácil es caer en la vaguedad, y también donde más vale la pena dedicar tiempo. La regla es sencilla: si un Agent no puede verificar por sí mismo si cumple un criterio de aceptación, entonces es un deseo, no un criterio.
| Redacción vaga | Redacción verificable | Cómo verificarlo |
|---|---|---|
| El código debe ser de calidad | Superar las comprobaciones de lint existentes en el proyecto, sin nuevas advertencias | El Agent ejecuta el comando de comprobación e informa del resultado |
| La funcionalidad debe funcionar correctamente | Añadir pruebas unitarias para tres casos: contraseña incorrecta, cuenta inexistente e inicio de sesión correcto. Todas deben pasar | Ejecutar las pruebas y compartir un resumen de los resultados |
| No afectar otras funcionalidades | Toda la suite de pruebas existente debe pasar y no se deben modificar los archivos prohibidos por las restricciones | Ejecutar todas las pruebas y listar los archivos modificados |
| La documentación debe estar completa | Añadir a la documentación de la interfaz una explicación de los códigos de error, con el mismo formato que las entradas existentes | Comparar cada punto con el ejemplo de referencia |
| El rendimiento no debe empeorar | No añadir consultas a la base de datos en la ruta crítica | Explicar en el resumen cómo cambió el número de consultas |
Una vez redactados, pide al Agent al final de la descripción de la tarea que informe del estado de cada criterio de aceptación: si se cumple, en qué se basa y, si no se cumple, por qué. Así, para revisar el resultado, solo tendrás que consultar esa tabla en lugar de leer todos los cambios desde el principio.
Guía rápida de contexto y criterios de aceptación para agentes
Aquí tienes un proceso que puedes seguir directamente. No necesitas herramientas adicionales: basta con un documento Markdown para empezar.
5 pasos para preparar las instrucciones de una tarea para un agente
- Escribe primero los criterios de aceptación y después el objetivo: hacerlo en ese orden te obliga a definir qué significa que la tarea esté terminada y evita que el objetivo sea demasiado amplio.
- Añade el contexto necesario: incluye solo los módulos relevantes, las decisiones ya tomadas y los intentos fallidos, sin extenderte demasiado.
- Enumera las restricciones y las condiciones de parada: especifica qué no se puede tocar y en qué situaciones el agente debe detenerse y consultar.
- Elige uno o dos ejemplos de referencia: prioriza implementaciones similares dentro del proyecto y, si usas documentación externa, enlaza solo las secciones relevantes.
- Pide un informe estructurado: al terminar, el agente debe informar sobre cada criterio de aceptación e incluir una lista de los archivos modificados y los problemas pendientes.
Ejemplo de descripción de una tarea para un agente (corrección de mensajes de error de inicio de sesión)
Este es un esquema para un caso hipotético. Puedes sustituir su contenido por el de tu propia tarea:
- Objetivo: el endpoint de inicio de sesión debe devolver el mismo código de error cuando la contraseña sea incorrecta o la cuenta no exista, para que el frontend muestre el mensaje correspondiente. No se modificará el flujo de inicio de sesión correcto ni el estilo de la página.
- Contexto: los códigos de error se definen de forma centralizada en el módulo
errors. Antes se intentó evaluar el texto del error en el frontend, pero se descartó por problemas con los distintos idiomas. - Restricciones: solo se pueden modificar
src/auth/y sus pruebas correspondientes; no se añadirán dependencias; si es necesario cambiar la definición de una interfaz pública, hay que detenerse y explicarlo. - Referencia: el manejo de errores del endpoint de registro en
src/user/. - Criterios de aceptación: añadir pruebas unitarias para tres escenarios y que todas pasen; que también pasen todas las pruebas existentes; que el linter no genere nuevas advertencias; y añadir a la documentación de la API la descripción de dos códigos de error.
- Formato del informe: revisar cada criterio de aceptación, enumerar los archivos modificados y explicar los problemas pendientes.
🚀 Consejo para empezar: puedes encargar la misma tarea a distintos modelos y comparar cuál respeta mejor las restricciones y las condiciones para detenerse. Con una plataforma de agregación como APIYI apiyi.com, puedes cambiar entre modelos de distintos proveedores usando una sola interfaz y la misma clave API. Así te ahorras registrar y configurar varias cuentas y puedes hacer pruebas comparativas con tus propias tareas reales.
Revisión cruzada de soluciones de agentes con modelos de distintos proveedores
El autor de la publicación original también planteó una inquietud: los modelos de un mismo proveedor podrían compartir puntos ciegos. Por eso, quería que agentes de distintos proveedores se revisaran entre sí, pero por ahora solo podía pasarles información mediante documentos Markdown o copiando y pegando, lo que complicaba mucho la coordinación. Esta idea se puede combinar con el método del artículo: la descripción de la tarea y los criterios de aceptación son la mejor base común para una revisión cruzada. Quien revise no necesita entender todas tus intenciones; basta con que contraste cada punto con los mismos criterios.
Una opción sencilla es asignar distintos roles a los modelos y darles a todos la misma descripción de la tarea:
| Rol | Entrada | Responsabilidad | Forma de acceso |
|---|---|---|---|
| Ejecutor | Descripción de la tarea | Implementar la solución y comprobar su trabajo según los criterios de aceptación | Tu agente de programación habitual |
| Revisor A | Descripción de la tarea + resumen de cambios | Revisar los criterios de aceptación uno por uno y señalar los casos que no se han cubierto | Modelo de otro proveedor, al que se puede llamar mediante la interfaz unificada de APIYI |
| Revisor B | Descripción de la tarea + resumen de cambios | Comprobar específicamente si se incumplen las restricciones o las condiciones de parada | Modelo de un tercer proveedor; basta con cambiar el nombre del modelo en la misma interfaz |
| Persona | Resumen de las opiniones de los revisores | Ocuparse solo de los desacuerdos entre revisores y de las cuestiones de diseño | Ninguna |
Si te animas a escribir un pequeño script que conecte «resultado de la ejecución → envío a los modelos revisores → recopilación de opiniones», podrás reemplazar la mayor parte del trabajo manual de copiar y pegar. APIYI ofrece una interfaz unificada compatible con los SDK más utilizados: basta con cambiar el nombre del modelo en el script para llamar al modelo de otro proveedor. Esto simplifica precisamente la parte más engorrosa de incorporar agentes de distintos proveedores. Eso sí, lo que se automatiza es el intercambio de información; la decisión final debe seguir en manos de una persona.
Qué problemas puede resolver el contexto del agente y cuáles necesitan supervisión humana
Un contexto bien preparado puede reducir muchas correcciones, pero no elimina por completo la intervención humana. La publicación original menciona tanto las «desviaciones de la tarea» como los «problemas de diseño», pero son dos tipos de problemas distintos: los primeros suelen deberse a la falta de información; los segundos, a decisiones entre distintas alternativas.
| Tipo de problema | ¿Puede resolverlo el contexto? | Motivo | Papel de la persona |
|---|---|---|---|
| Cambios fuera del alcance previsto | En general, sí | Si las restricciones están claras, el agente puede comprobarlas por sí mismo | Revisar la lista de cambios por muestreo |
| Inconsistencias de estilo y formato | En general, sí | Los ejemplos de referencia bastan como modelo | Revisar de vez en cuando |
| Cobertura de pruebas incompleta | En gran medida, sí | Basta con especificar los escenarios en los criterios de aceptación | Comprobar que la lista de escenarios esté completa |
| Decisiones de arquitectura y diseño | Difícilmente | Requieren valorar varias opciones razonables | Decidir de antemano y documentarlo en la descripción de la tarea |
| Intención del producto y experiencia de usuario | Difícilmente | Dependen de los objetivos de negocio y del conocimiento de los usuarios | Definirlas antes y validarlas después |
| Si los propios criterios de aceptación son correctos | No | El agente solo puede comprobarlos, no cuestionar sus premisas | Debe asumirlo una persona |
Los problemas de diseño son difíciles de delegar por completo en un agente porque, por lo general, no tienen una única respuesta correcta. Por ejemplo, los códigos de error pueden colocarse en un módulo compartido o en uno de negocio, y ambas opciones pueden funcionar. La elección depende de los planes de evolución del equipo y de sus prácticas de mantenimiento, información que suele formar parte del criterio de las personas y que es difícil plasmar por completo por escrito.
Por eso, una estrategia más práctica es adelantar la intervención humana: tomar las decisiones de diseño antes de empezar la tarea e incorporarlas a las restricciones. Así, no tendrás que vigilar al agente mientras trabaja; al terminar, solo tendrás que revisar la lista de aceptación y los puntos de desacuerdo entre quienes revisan. El papel de la persona en el ciclo pasa de «acompañar todo el proceso» a «marcar la dirección al inicio y validar el resultado al final».
Preguntas frecuentes
Q1: ¿Qué son los criterios de aceptación de un agente?
Son condiciones que deben cumplirse al terminar la tarea y que se pueden comprobar una por una, por ejemplo: «se superaron todas las pruebas especificadas» o «no se modificaron los archivos protegidos». Permiten que el agente revise su propio trabajo y que una persona evalúe el resultado rápidamente, sin leer toda la salida línea por línea.
Q2: ¿Cuanto más contexto se proporcione, mejor?
No. La información irrelevante puede diluir lo importante e incluso hacer que el agente modifique partes que no debería tocar. Conviene seleccionar el contexto según la tarea: módulos relevantes, decisiones previas, intentos fallidos y terminología necesaria. Si no tienes claro si cierta información es útil, puedes usar APIYI apiyi.com para invocar distintos modelos y probar versiones resumidas y completas de la descripción de la tarea, y así ver cuál se desvía menos.
Q3: ¿Hay que escribir una descripción tan completa para cada tarea pequeña?
No hace falta. Las restricciones generales y el contexto del proyecto pueden incluirse en un archivo de instrucciones a nivel de proyecto y reutilizarse. Para cada tarea solo hay que añadir el objetivo, el material de referencia y los criterios de aceptación. Para un cambio que lleva unos minutos, normalmente basta con una frase que describa el objetivo y dos o tres criterios de aceptación.
Q4: ¿Para qué tipos de agentes y tareas sirve este método?
Es especialmente útil para agentes de programación y agentes que realizan tareas con entregables concretos, como corregir errores, implementar interfaces, generar documentación u organizar datos. En tareas muy exploratorias, donde el objetivo aún no está definido, es difícil establecer de antemano criterios de aceptación claros. En esos casos, conviene que la persona y el agente acuerden primero una dirección antes de ejecutar la tarea.
Q5: ¿Cómo se puede hacer una revisión cruzada con modelos de distintos proveedores sin copiar y pegar constantemente?
Puedes escribir un pequeño script que envíe el resultado y la descripción de la tarea a los modelos encargados de la revisión y luego reúna sus observaciones. Gracias a la interfaz unificada de APIYI apiyi.com, basta con cambiar el nombre del modelo en el script para invocar modelos de distintos proveedores, sin tener que integrar por separado el SDK y la cuenta de cada uno. Esto permite crear rápidamente un prototipo de flujo de «ejecución + revisión por varias partes».
Q6: ¿Cuáles son las limitaciones de este método?
En primer lugar, no sustituye el criterio de diseño: las decisiones de arquitectura y la intención del producto siguen dependiendo de las personas. En segundo lugar, si los criterios de aceptación son incorrectos, el agente los cumplirá fielmente. Además, por ahora faltan datos públicos que cuantifiquen las diferencias entre los resultados de los distintos métodos de preparación. Por eso, conviene hacer comparaciones a pequeña escala con tus propias tareas y registrar cuántas veces hay que corregir el rumbo.
Puntos clave sobre el contexto y los criterios de aceptación para agentes
- Las desviaciones suelen deberse a la falta de información: si faltan el objetivo, las restricciones o los materiales de referencia, puede ser necesario rehacer el trabajo.
- Los cinco elementos de la descripción de una tarea: objetivo, contexto, restricciones, materiales de referencia y criterios de aceptación. Todos son necesarios.
- Los criterios de aceptación deben poder verificarse: si el agente no puede comprobarlos por sí mismo, son solo una aspiración.
- Establece condiciones de parada: indicar cuándo debe detenerse y preguntar ahorra esfuerzo frente a corregir después.
- Toma las decisiones de diseño por adelantado: las personas deben decidir las concesiones de arquitectura y producto e incorporarlas a las restricciones.
- Usa los mismos criterios para la revisión cruzada: mediante la interfaz unificada de APIYI puedes invocar modelos de distintos proveedores y comparar sus revisiones.
Resumen
Gran parte del cansancio de supervisar el ciclo de trabajo de un agente se debe a que las tareas se delegan con información incompleta. Eso obliga a estar pendiente todo el tiempo y corregir el rumbo sobre la marcha. Para preparar bien el trabajo desde el principio, hay tres puntos clave:
- Describe la tarea en cinco apartados: objetivo, contexto, restricciones, materiales de referencia y criterios de aceptación. Así el agente sabe qué hacer, hasta dónde llegar y qué no debe tocar.
- Redacta los criterios de aceptación como puntos verificables: pide al agente que informe sobre cada uno para que tú solo tengas que revisar la tabla de comprobación y los problemas pendientes.
- Distingue lo que puedes resolver con contexto de lo que requiere supervisión humana: decide las concesiones de diseño de antemano y deja los propios criterios de aceptación bajo responsabilidad humana.
En tu próxima tarea real, prueba a escribir primero los criterios de aceptación y completar después los demás apartados. Registra también cuántas veces tienes que intervenir durante el proceso para usarlo como referencia de mejora. Si estás probando la revisión cruzada con modelos de distintos proveedores, puedes acceder a ellos mediante la interfaz unificada de APIYI en apiyi.com y comprobar, con tareas reales, qué combinación reduce más tus intervenciones.
📚 Referencias
- Hilo de V2EX – Cómo reducir la intervención humana para que los agentes trabajen de forma independiente y mejoren la calidad de las entregas: fuente del tema de este artículo
- Enlace:
v2ex.com/t/1254207 - Descripción: aborda el desgaste de las personas que participan en el ciclo de trabajo de un agente, el papel del contexto y la idea de una revisión cruzada entre agentes de distintos proveedores.
Autor: Equipo técnico de APIYI
Intercambio técnico: Puedes contactarnos desde la página principal de APIYI, apiyi.com, para compartir experiencias sobre instrucciones para tareas de agentes y colaboración entre varios modelos.
