Una buena story no es una larga

Cuando un agente vuelve con algo que no da en el blanco, la reacción obvia es escribir más la próxima vez: más detalle, más contexto, más prosa. Pero la longitud es un mal indicador de calidad. Una spec que rivaliza con un RFC no hace que un agente sea más agudo — a partir de cierto punto, el tamaño puro juega en su contra, porque "los límites de la ventana de contexto y el 'presupuesto de atención' del modelo se interponen". El mejor enfoque es dividir tareas grandes en otras más pequeñas en lugar de empaquetarlo todo en un único prompt gigante. [1]

El objetivo nunca fue un ticket más largo. Es eliminar la ambigüedad que, de otro modo, aparecería como código deficiente y una revisión ruidosa — como lo expresa un proveedor de herramientas para agentes. [2] Una story se juzga por una sola cosa: ¿vuelve el agente habiendo construido lo que querías decir? Todo lo demás es decoración.

La razón por la que esto importa más ahora es que el lector ha cambiado. Una user story siempre ha sido un punto de partida para una conversación — un desarrollador la lee, se acerca a quien la escribió, hace seis preguntas y rellena el resto con lo que sabe sobre el código base y el equipo. [3] Un agente no puede acercarse a nadie. Lee lo que hay en la página, rellena cada hueco con su mejor suposición y construye exactamente lo que adivinó. [3]

Y cuando la story deja margen para la interpretación, el agente interpretará — la culpa rara vez es del modelo, es del contrato que se le entregó. [4] El modelo rara vez es la variable que tú controlas. La story sí lo es. [5]

La story más sólida para un agente no empieza con una lista de tareas, sino con una misión clara. Indica el objetivo y unos pocos requisitos centrales a alto nivel, y deja que el agente desarrolle los detalles desde ahí — los modelos son buenos elaborando a partir de una directriz sólida, pero necesitan una misión clara para no desviarse. [1] Tu trabajo en la story es transmitir la visión; el trabajo del agente es todo lo demás.

Por eso el formato clásico de user story ha perdurado: empaqueta tres piezas de intención en una sola frase — "como [tipo de usuario], quiero [un objetivo], para [una razón]". La tercera cláusula, la que todo el mundo se salta, es la que transmite la visión:

"Sin ella, el agente optimiza para la petición literal de la funcionalidad. Con ella, el agente puede razonar sobre casos límite." [6]

Observa qué pasa sin ella. "Arregla el bug de inicio de sesión" es una instrucción completa para un humano que estaba presente cuando se reportó el bug. Para un agente es una sugerencia — podría devolver un pull request de 400 líneas que toca el flujo de restablecimiento de contraseña, el middleware de sesión y una feature flag, cuando el arreglo real era una errata en un mensaje de error. [4] La visión en esa story — quién está bloqueado, qué debería pasar en su lugar, por qué importa — es lo que habría elegido la implementación correcta al primer intento.

Un lector humano rellena los huecos con criterio, memoria y un mensaje barato en Slack. Un agente los rellena con sus valores por defecto — y elegirá tranquilamente tres intentos cuando querías decir cinco, o bloqueará cuentas de forma que cualquiera pueda bloquear a todos tus clientes. [3] El oficio consiste en nombrar las decisiones en las que un valor por defecto equivocado te costaría caro. Una prueba sencilla para cada decisión abierta: "¿Me molestaría si el agente lo adivinara?" Si la respuesta es sí, pertenece a la story. [7]

Lo que queda fuera del alcance importa tanto como el alcance. Una breve lista de "no tocar" — los comportamientos, archivos y límites que el agente debe dejar en paz — suele ser la frase más útil de toda la story, porque sin ella el agente trata la limpieza útil como un permiso. [8] Los no-objetivos explícitos evitan que arregle cosas que nadie pidió. [9] O, en palabras de un desarrollador: "Cinco líneas en el ticket evitan dos horas de revisión." [4]

Una story que transmite esto bien se lee como un pequeño contrato: el problema, el resultado esperado, los criterios de aceptación, las restricciones y lo que está fuera de límites. No porque una plantilla sea mágica — sino porque cada campo es un hueco que, de otro modo, se rellenaría con una suposición.

El hábito de mayor impacto es escribir primero los criterios de aceptación y dejar que atraigan al resto de la story hacia el enfoque. [7] Los criterios de aceptación son comportamiento observable — lo que debe ser cierto después del cambio — no una repetición de la petición. "El formulario se envía" es un deseo; "al enviar con un token caducado se muestra la pantalla de sesión expirada y no se borra el mensaje redactado" es una comprobación.

Las mejores comprobaciones son las que el propio agente puede ejecutar: el comando a ejecutar, el test que debe pasar, los casos de fallo a cubrir. Escritas una vez, dan "criterios de aceptación que definen terminado tanto para el agente como para la persona" — "una única fuente de verdad a partir de la cual construye el agente y contra la que comprueba el revisor". [10]

Define también el traspaso. Pide al agente, en cada story, que "resuma los archivos cambiados, las comprobaciones ejecutadas, los fallos encontrados y cualquier riesgo restante" en su pull request. [9] Cuesta una línea en la story y hace que cada revisión sea más rápida.

Otro truco que mantiene honesta la visión: haz que el agente convierta tu intención en un primer borrador de spec y luego corrige el borrador. Si la reformulación de la story por parte del agente no coincide con lo que querías decir, el hueco está en tu story — y es mucho más barato encontrarlo antes del pull request. [1]

Los agentes no necesitan prosa que describa tu arquitectura — pueden leer el código. Lo que no pueden inferir es qué partes de él toca esta story. Señala en lugar de describir: haz referencia a los archivos a tocar, los patrones existentes a imitar, las convenciones a respetar. [7] Un ejemplo de cinco líneas en la story enseña al agente más que un párrafo que explica la regla.

Y mantén el trabajo del tamaño de una story — algo que se pueda construir y verificar en una sola tarde — y divide lo que sea más grande a nivel de story, antes de enviarlo, no a mitad de la ejecución. [7] Stories más pequeñas y afiladas son también lo que hace manejable ejecutar varios agentes en paralelo — mira nuestra guía de agentes de código en paralelo.

Aquí está el mismo issue de Linear, escrito dos veces.

Esa última comprobación es la prueba de "¿me molestaría si el agente lo adivinara?" en acción: sin especificarlo, un agente razonable podría fácilmente mostrar el mensaje de bloqueo solo para cuentas reales — y revelar qué correos están registrados.

Todo lo de esta guía — la misión, los no-objetivos, los criterios de aceptación, los archivos a mirar — es lo que el redactor de stories de Aerunit prepara por ti. Tú describes el trabajo; Aerunit lee tus repositorios y propone issues de Linear con alcance, criterios de aceptación y no-objetivos, señalando el código que importa. Tú editas, apruebas, y la story queda lista para un agente.

Aerunit lee cada repositorio que toca una story antes de escribirla, de modo que el trabajo entre varios repos obtiene un plan coherente: una story principal más un sub-issue por repositorio afectado. Y las convenciones e instrucciones reutilizables de tu equipo se guardan una vez como contexto compartido y skills, y luego se alimentan a cada story y a cada ejecución de agente — así no repites "imita el patrón existente" en cada ticket, y los agentes no reinventan tus patrones.