Una issue bien escrita para tu equipo puede ser una mala especificación para un agente de código. La persona que la lee rellena lo que falta con lo que sabe del producto, del cliente y de lo que se habló ayer en la daily. El agente no tiene nada de eso.
La idea que defiende este insight: cuando a una tarea le falta información, un agente de código al que nadie se lo pide suele no preguntar: lo inventa y sigue. Por eso convertir una issue en una especificación no se delega en el agente. Lo hace una persona que conoce el producto, antes de que el agente escriba una línea.
Lo que una issue da por sabido
Una issue es una nota entre compañeros. «Añadir filtro por fecha al listado de pedidos» basta si quien la recoge sabe qué es un pedido, qué fecha cuenta y a quién preguntar. Casi siempre se dan por sabidas tres cosas: dónde está el cambio, qué no se debe tocar y cuándo se da por terminado. Esa lista es nuestra, no de un estudio. Un agente que recibe solo esa frase tiene que decidir las tres, y lo hace sin avisar.
Lo que hace el agente cuando falta algo
Tres estudios recientes miden lo mismo con métodos distintos: qué pasa cuando a la instrucción le faltan datos.
El primero es Ambig-SWE (Vijayvargiya, Zhou, Yerukola, Sap y Neubig; aceptado en ICLR 2026). Parte de 500 issues de SWE-bench Verified, un conjunto de issues reales de repositorios de código abierto, y genera con GPT-4o versiones resumidas a las que les faltan datos. Resultado: sin una indicación explícita, los modelos casi nunca interactúan, ni siquiera con instrucciones gravemente incompletas. Y solo dos de los seis modelos evaluados distinguieron con una precisión notable (89 % y 84 %) una tarea completa de una incompleta, y eso cuando se les animaba a preguntar. Cuando el agente podía preguntar a un usuario simulado, el rendimiento mejoraba hasta un 74 % respecto a no poder hacerlo.
El segundo es «Ask or Assume?» (Edwards y Schuster, Universidad de Viena; EMNLP 2026). Usa 500 issues de SWE-bench Verified a las que se quitan detalles como fragmentos de código, rutas de archivos y trazas de error. Con Claude Sonnet 4.5 como modelo base, el agente resuelve el 70,8 % con la issue completa. Con la issue incompleta y sin poder preguntar, el 54,8 %. Con un montaje que separa la detección de lo que falta de la ejecución del código y pregunta antes de actuar, el 69,4 %. Con un segundo modelo, el 69,4 % frente al 72,8 % con la issue completa.
En puntos, nuestra cuenta: de los 16 que se pierden con la issue recortada, el montaje que pregunta recupera 14,6. La diferencia no la pone un modelo mejor, sino un paso en el proceso: detectar lo que falta y preguntar antes de escribir código.
El tercero es «Coding Agents Are Guessing» (Ji y otros, Universidad de Ciencia y Tecnología de Hong Kong y Universidad de Tongji, julio de 2026). Mide tareas de operaciones (DevOps) con 2.208 variantes de 69 familias de tareas y cinco combinaciones de agente y modelo. Su conclusión, traducida: la falta de especificación, más que hacer fallar a los agentes, hace que adivinen. Según la configuración, preguntaron entre el 1,7 % y el 44,5 % de las ejecuciones puntuadas. Y avisar del radio de impacto de la acción apenas reducía que el agente actuara.
Riesgo Son benchmarks, no equipos reales. En Ambig-SWE las issues incompletas son resúmenes generados con GPT-4o. En «Ask or Assume?» se quitan detalles de issues reales y quien contesta es un usuario simulado (GPT-5.1) que tiene la issue completa; tu equipo necesita una persona de verdad. «Coding Agents Are Guessing» mide operaciones, no funcionalidades. Los modelos son los de cada estudio. Nos quedamos con la dirección, no con el porcentaje.
Lo que debe llevar una issue antes de dársela a un agente
Los estudios no dicen cómo escribir una issue, dicen qué pasa cuando le faltan datos. A partir de ahí, esta es nuestra propuesta: seis cosas que la persona suele llevar en la cabeza y el agente necesita por escrito. La columna de la derecha es la pregunta que, contestada, cierra cada hueco.
| Lo que la issue deja implícito | Lo que el agente tiene que saber | La pregunta que lo cierra |
|---|---|---|
| Dónde está el cambio | Módulos, archivos y puntos de entrada afectados | ¿Dónde se toca y dónde no? |
| Qué significa cada término | El concepto del dominio tal como existe en este código («pedido», «fecha») | ¿A qué campo o concepto se refiere exactamente? |
| Los casos límite | Vacíos, zonas horarias, permisos, volúmenes grandes | ¿Qué pasa cuando la entrada es rara? |
| Cuándo está terminado | Criterios de aceptación que se puedan comprobar | ¿Qué prueba demostraría que está hecho? |
| Qué no se puede romper | Contratos de API, datos de clientes, migraciones | ¿Qué cambio sería visible fuera o irreversible? |
| Quién decide si hay riesgo | La persona que aprueba si afecta a dinero, datos o seguridad | ¿Quién lo aprueba antes de fusionarlo? |
Elaboración de onext
Quién cierra los huecos
El agente puede ayudar, con una condición. Se le pide que, antes de escribir código, liste lo que le falta como preguntas y no como suposiciones; es, en esencia, lo que hace el montaje que propone «Ask or Assume?». Pero quien contesta es una persona que conoce el producto. La secuencia que proponemos, dentro del Spec-Driven Development (SDD), el desarrollo guiado por especificaciones:
- Pedir al agente una lista de preguntas sobre la issue, sin código. Tiene que ser una instrucción explícita: sin ella, según Ambig-SWE, casi no pregunta.
- Una persona que conoce el producto contesta por escrito, en la propia issue, para que lo lea quien venga después.
- Con las respuestas, la issue pasa a ser una especificación: alcance, límites y criterios de aceptación que se puedan comprobar.
- Donde hay riesgo (dinero, datos personales, seguridad, cambios que no se pueden deshacer), una persona aprueba la especificación antes de que el agente implemente, y se decide cómo deshacer lo que haga. Una persona decide donde hay riesgo.
Una issue está lista para un agente cuando nadie tiene que explicarle nada más: lo que falta se pregunta antes, no se descubre en la revisión.
Un ejemplo, inventado
La issue dice «Añadir filtro por fecha al listado de pedidos». Antes de escribir código, un agente debería preguntar: ¿la fecha es la de creación o la de entrega? ¿El rango incluye el último día? ¿En qué zona horaria se interpreta? ¿Hay paginación y cuántos pedidos puede haber? ¿Quién puede ver qué pedidos? Si nadie lo contesta, el agente elige una respuesta por cada pregunta, y quien revisa se entera, si se entera, leyendo el diff. Es un ejemplo para ilustrar; no es de ningún cliente.
Es la misma lógica que explicamos en Specs y agentes: la especificación es donde se firma, pero un paso antes: aquí no se firma la especificación, se escribe. Lo que el agente no puede adivinar de tu código, como las decisiones de arquitectura, lo vimos en decisiones de arquitectura. Y si lo que llega a revisión es una suposición que nadie detectó, la ganancia se queda esperando allí, como contamos en más código, la misma entrega.
Una prueba para esta semana
Coge tres issues que tu equipo vaya a empezar. Dale cada una al agente con una sola instrucción: «No escribas código. Lista lo que necesitas saber y no está en la issue». Cuenta cuántas preguntas son útiles y cuántas habrías descubierto en la revisión. Es una prueba de nuestra cosecha, no un método medido. Si en alguna no pregunta nada, no la des por buena: los modelos de Ambig-SWE distinguían mal una tarea completa de una incompleta.
Si quieres ver con alguien de fuera cómo se escribe esto sobre el código de tu equipo, el diagnóstico es gratuito, y si en el diagnóstico no vemos diferencia, no hay Quick-start. Antes, puedes ver en qué punto estás con el autodiagnóstico de SDD. Cómo es el resto del camino está en AI-Accelerated Development. El método completo está en Spec-Driven Development con IA.
Preguntas frecuentes
¿Qué diferencia hay entre una issue y una especificación para un agente de código?
Una issue es una nota entre compañeros: da por sabido dónde está el cambio, qué no se debe tocar y cuándo se da por terminado. Una especificación para un agente lo dice por escrito: alcance, límites, casos límite y criterios de aceptación que se puedan comprobar. Lo que en la issue completa la persona con su conocimiento del producto, al agente hay que dárselo.
¿Los agentes de código preguntan cuando falta información?
Sin que se lo pidan, rara vez. En Ambig-SWE, los modelos casi nunca interactúan sin una indicación explícita, ni siquiera con instrucciones gravemente incompletas. En Coding Agents Are Guessing, según la configuración, los agentes preguntaron entre el 1,7 % y el 44,5 % de las ejecuciones. En «Ask or Assume?», el montaje que separa la detección de lo que falta de la ejecución pregunta antes de actuar.
¿Hay que escribir una issue mucho más larga para un agente?
No conocemos un estudio que mida la longitud ideal. Lo que los estudios quitan a las issues para dejarlas incompletas son detalles concretos: fragmentos de código, rutas de archivos, trazas de error. No hace falta más texto, sino la información que el agente no puede deducir: dónde, qué no tocar y cuándo está hecho.
¿Puede el propio agente convertir la issue en una especificación?
Puede ayudar con la mitad del trabajo: leer la issue y listar lo que le falta como preguntas, sin escribir código. La otra mitad no es suya: contestar esas preguntas exige conocer el producto, el cliente y el contexto del negocio, y lo hace una persona. Sin esa respuesta, el agente vuelve a rellenar los huecos con suposiciones.
¿Qué tareas no deberían ir directas a un agente?
Las que afectan a dinero, datos personales, seguridad o cambios que no se pueden deshacer. En esas, la especificación la aprueba una persona antes de que el agente implemente. El estudio sobre instrucciones de operaciones (DevOps) vio que avisar al agente del radio de impacto apenas reducía que actuara: pedirle cuidado no sustituye a que alguien decida.
¿Cómo compruebo si mi equipo lo está haciendo bien?
Con una prueba pequeña: coge tres issues a punto de empezar, pide al agente que liste lo que necesita saber sin escribir código y cuenta cuántas preguntas son útiles, es decir, cuántas habrías descubierto en la revisión. Si no pregunta nada, no significa que la issue esté completa: los modelos de Ambig-SWE distinguían mal una tarea completa de una incompleta.
Fuentes
- Sanidhya Vijayvargiya, Xuhui Zhou, Akhila Yerukola, Maarten Sap y Graham Neubig, «Ambig-SWE: Interactive Agents to Overcome Underspecificity in Software Engineering», arXiv:2502.13069, versión 3 del 21 de febrero de 2026 (aceptado en ICLR 2026).
- Nicholas Edwards y Sebastian Schuster (Universidad de Viena), «Ask or Assume? Uncertainty-Aware Clarification-Seeking in Coding Agents», arXiv:2603.26233, versión 3 del 7 de septiembre de 2026 (versión final para EMNLP 2026).
- Zimo Ji, Zekai Zhang, Congying Xu, Zongjie Li, Yudong Gao, Shuai Wang y Shing-Chi Cheung, «Coding Agents Are Guessing: Measuring Action-Boundary Violations in Underspecified DevOps Instructions», arXiv:2607.02294, 2 de julio de 2026.
- Las citas de fuentes en inglés están traducidas por onext. La tabla, los pasos, el ejemplo, la prueba de esta semana y el cálculo de los puntos recuperados son elaboración propia de onext.
Bernat López es fundador y CEO de onext, boutique de IA. Acompaña a equipos de desarrollo y de producto a trabajar con IA con método —especificación antes de programar, una persona que decide donde hay riesgo y Spec-Driven Development— y aplica a su propia empresa lo que propone: onext funciona con su propio sistema agéntico.
LinkedIn →