Frenar a los agentes a propósito

Los agentes más rápidos no construyen mejor software: los disciplinados sí. El regulador que mantiene coherente a RakuAI es la misma disciplina que creemos que necesita todo equipo serio que trabaje con agentes.

Este sábado el plan fue distinto al de los últimos fines de semana. Los últimos fueron fines de semana de rendimiento. Ochenta commits, setenta commits, doscientos ochenta y dos antes de eso. La tendencia iba al alza. Yo dejaba la cola de agentes a máxima velocidad y veía acumularse las líneas de código.

Este fin de semana la frené a propósito hasta treinta y siete commits. La tendencia en este gráfico ahora es a la baja, y es a la baja a propósito, y quiero escribir sobre por qué, porque no creo que sea la tendencia que la mayoría de la gente que construye con agentes de IA esperaría.

Lo que es cierto sobre el flujo de trabajo

Los agentes no se cansan. El rendimiento de la capa de implementación está limitado por el costo de tokens y por cuántos issues hay abiertos en la cola. Si registro cien issues a las seis de la mañana, la cola se vacía y se rellena todo el día y recibo cien PRs de vuelta. Eso es lo que hace el flujo de trabajo cuando se le permite correr a toda máquina.

Lo que no hace, cuando corre a toda máquina, es producir un código coherente. Cada PR llega limpio de forma aislada. La intersección de cuarenta PRs que llegan en un solo día empieza a desalinearse. Las convenciones de nombres divergen. Los límites entre subsistemas se difuminan. El agente que trabajó en un issue asumió algo sobre la capa de runtime que el agente de un issue paralelo no asumió. Para el sábado por la noche, esas dos suposiciones han chocado en un tercer PR que tiene que reconciliarlas, y la reconciliación es un desastre.

El cuello de botella en este flujo de trabajo no es el agente. Es el humano que lee lo que producen los agentes y mantiene la arquitectura coherente.

Lo que cambié

Dos cosas, ambas visibles en el patrón de commits de este fin de semana.

Recorté la profundidad de la cola. En lugar de quince issues de agente abiertos en todo momento, la bajé a seis. Los agentes ya no corren a toda máquina. Corren a un ritmo que me permite leer de verdad su producción antes de que llegue el siguiente lote.

Adelanté la revisión. En lugar de dejar que los PRs de agentes se acumularan hasta tener un lote con el que trabajar, cambié a revisar cada uno en el momento en que se abría. Esto suena más lento, y lo es. También detecta el desalineamiento antes de que se propague. Una mala suposición corregida temprano el sábado no necesita deshacerse el sábado por la noche a través de seis PRs.

El efecto combinado de estos dos cambios es el fin de semana de treinta y siete commits en lugar de uno de ochenta. El efecto combinado también es un código en mejor estado que el del sábado pasado, que es justamente el objetivo.

Lo que sí se completó

Este fin de semana se afianzó una disciplina multi-repositorio. El runtime, el SDK y el repositorio de documentación se movieron juntos. El runtime recibió el resumen del directorio de documentación en el README. El SDK recibió las referencias cruzadas correspondientes. La documentación creció. Ninguno de los tres repositorios se adelantó a los demás.

Esto importa porque en un flujo de trabajo impulsado por agentes, la documentación no es solo documentación. La documentación es la entrada que el agente lee cuando toma el siguiente issue. Si la documentación miente sobre lo que soporta el runtime, el agente escribirá fielmente código para la versión mentirosa del runtime, y ese código no compilará contra la realidad. El remedio es mantener los tres repositorios honestos, todo el tiempo, incluso cuando uno de ellos es en el que naturalmente trabajarías.

Lo otro discretamente importante este fin de semana fue la limpieza de la superficie de la API. Unas cuantas APIs que se habían añadido en la prisa de septiembre resultaron no pertenecer a la superficie pública. Fueron degradadas a internas. Los agentes gestionaron esa degradación en todo el SDK en un solo PR. Ese es el tipo de refactorización que, hecha por un solo humano, toma un día entero. Hecha en este flujo de trabajo, toma un issue, un PR y una revisión cuidadosa.

Lo que significan las “mejores prácticas” en este flujo de trabajo

Una lista breve, afinada este fin de semana por la experiencia de bajar el ritmo.

La documentación es entrada de desarrollo, no salida de desarrollo. Si la documentación es mala, el trabajo es malo. Manténla como mantienes el código. Revísala como revisas el código. Niégate a fusionar una función cuya documentación se haya saltado.

Los límites entre subsistemas son sagrados. El agente no inventará límites que el código no tuviera ya. Si quieres un límite, tienes que trazarlo, etiquetarlo y rechazar los PRs que lo violen.

La sincronización entre repositorios es una tarea de primera clase. Cuando el runtime y el SDK tienen que moverse juntos, la descripción del PR tiene que decirlo, y la fusión de uno queda condicionada a la fusión del otro. La divergencia de estado entre dos repositorios es uno de los modos de fallo más fáciles de evitar y de los más dolorosos de recuperar.

Baja el ritmo a propósito. El agente no lo hace. Tú tienes que hacerlo. El fin de semana en que el agente entrega cien PRs no es el mismo fin de semana en que el código mejora en el valor de cien PRs. El fin de semana en que el agente entrega treinta y siete PRs bien revisados podría serlo.

Lo que podría resultarles útil a los socios

Si estás construyendo algo con agentes de codificación autónomos y te estás topando con la versión de “los agentes trabajan rápido y el código es un desastre” de este flujo de trabajo, la respuesta no son mejores agentes. La respuesta es una cola más pequeña, un paso de revisión más temprano y documentación que los agentes lean como entrada.

Si eres un laboratorio de IA afinando un agente de codificación para flujos de trabajo de PR autónomos como este, la métrica que encuentro más útil en la práctica no son las líneas de código entregadas por día. Es la frecuencia con la que un PR que llegó temprano en la semana tiene que reescribirse más tarde ese mismo fin de semana porque el código se movió debajo de él. Cuanto más bajo sea ese número, mejor es el agente en el trabajo real.

Treinta y siete commits. Un código mejor que el que tenía el sábado pasado. Es sábado por la tarde y voy a salir a caminar.