Desacelerando os Agentes de Propósito

Agentes mais rápidos não constroem software melhor — agentes disciplinados constroem. O freio que mantém a RakuAI coerente é a mesma disciplina que achamos que todo time sério conduzido por agentes precisa.

Plano diferente neste sábado comparado aos últimos fins de semana. Os últimos foram fins de semana de vazão. Oitenta commits, setenta commits, duzentos e oitenta e dois antes disso. A tendência estava subindo. Eu estava cavalgando a fila de agentes totalmente aberta e vendo as linhas de código se acumularem.

Neste fim de semana eu reduzi de propósito para trinta e sete commits. A tendência neste gráfico agora está caindo, e está caindo de propósito, e quero escrever sobre por quê porque não acho que essa seja a tendência que a maioria das pessoas construindo com agentes de IA esperaria.

O que é verdade sobre o fluxo de trabalho

Os agentes não cansam. A vazão da camada de implementação é limitada pelo custo de tokens e por quantas issues estão abertas na fila. Se eu registrar cem issues às seis da manhã, a fila esvazia e reabastece o dia todo e eu recebo cem PRs de volta. É isso que o fluxo de trabalho faz quando é deixado rodar totalmente aberto.

O que ele não faz, quando roda totalmente aberto, é produzir uma base de código coerente. Cada PR entra limpo isoladamente. A interseção de quarenta PRs entrando em um dia começa a se desviar. Convenções de nomenclatura divergem. Fronteiras de subsistema ficam turvas. O agente que trabalhou em uma issue assumiu algo sobre a camada de runtime que o agente em uma issue paralela não assumiu. Até o sábado à noite as duas suposições colidiram em um terceiro PR que tem que reconciliá-las, e a reconciliação é uma bagunça.

O gargalo neste fluxo de trabalho não é o agente. É o humano lendo o que os agentes produzem e mantendo a arquitetura coerente.

O que eu mudei

Duas coisas, ambas visíveis no padrão de commits deste fim de semana.

Cortei a profundidade da fila. Em vez de quinze issues abertas na fila de agentes o tempo todo, baixei para seis. Os agentes não estão mais rodando totalmente abertos. Estão rodando em um ritmo que me permite de fato ler a produção deles antes de o próximo lote entrar.

Movi a revisão para antes. Em vez de deixar os PRs dos agentes esperando até eu ter um lote para trabalhar, mudei para revisar cada um assim que abria. Isso soa mais lento, e é. Também pega desvio antes que ele se propague. Uma suposição ruim corrigida cedo no sábado não precisa ser desfeita até o sábado à noite através de seis PRs.

O efeito combinado dessas duas mudanças é o fim de semana de trinta e sete commits em vez de um fim de semana de oitenta commits. O efeito combinado também é uma base de código em melhor estado do que estava no sábado passado, que é o ponto.

O que ainda entrou

Uma disciplina multi-repositório ficou mais firme neste fim de semana. O runtime, o SDK, e o repositório de documentação se moveram juntos. O runtime ganhou a visão geral do diretório de documentação no README. O SDK ganhou as referências cruzadas correspondentes. A documentação cresceu. Nenhum dos três repositórios ficou à frente dos outros.

Isso importa porque, em um fluxo de trabalho conduzido por agentes, a documentação não é só documentação. A documentação é a entrada que o agente lê quando pega a próxima issue. Se a documentação mente sobre o que o runtime suporta, o agente vai escrever fielmente código para a versão mentirosa do runtime, e esse código não vai compilar contra a realidade. O remédio é manter os três repositórios honestos, o tempo todo, mesmo quando um deles é aquele em que você naturalmente trabalharia.

A outra coisa silenciosamente importante deste fim de semana foi a limpeza da superfície de API. Algumas APIs que tinham sido adicionadas na correria de setembro acabaram não pertencendo à superfície pública. Foram rebaixadas para internas. Os agentes cuidaram do rebaixamento através do SDK em um único PR. Esse é o tipo de refatoração que, feita por um único humano, leva um dia inteiro. Feita neste fluxo de trabalho, leva uma issue e um PR e uma revisão cuidadosa.

O que “melhores práticas” significam neste fluxo de trabalho

Uma lista curta, afiada neste fim de semana pela experiência de cortar o ritmo.

Documentação é entrada de desenvolvimento, não saída de desenvolvimento. Se a documentação é ruim, o trabalho é ruim. Mantenha-a como você mantém código. Revise-a como você revisa código. Recuse-se a mesclar uma funcionalidade cuja documentação foi pulada.

Fronteiras entre subsistemas são sagradas. O agente não vai inventar fronteiras que a base de código ainda não tinha. Se você quer uma fronteira, você tem que desenhá-la, rotulá-la, e recusar os PRs que a violam.

Sincronização entre repositórios é uma tarefa de primeira classe. Quando o runtime e o SDK têm que se mover juntos, a descrição do PR tem que dizer isso, e a mesclagem de um fica condicionada à mesclagem do outro. Divergência de estado entre dois repositórios é um dos modos de falha mais fáceis de evitar e um dos mais dolorosos de recuperar.

Desacelere de propósito. O agente não faz isso. Você tem que fazer. O fim de semana em que o agente entrega cem PRs não é o mesmo fim de semana em que a base de código melhora o equivalente a cem PRs de valor. O fim de semana em que o agente entrega trinta e sete PRs bem revisados pode ser.

O que parceiros podem achar útil

Se você está construindo algo com agentes de codificação autônomos e está caindo na versão “os agentes trabalham rápido e a base de código é uma bagunça” desse fluxo de trabalho, a resposta não é agentes melhores. A resposta é uma fila menor, uma passada de revisão mais cedo, e documentação que os agentes leem como entrada.

Se você é um lab de IA ajustando um agente de codificação para fluxos de trabalho de PR autônomo como este, a métrica que acho mais útil na prática não é linhas-de-código-entregues por dia. É com que frequência um PR que entrou no início da semana tem que ser reescrito depois no mesmo fim de semana porque a base de código se moveu por baixo dele. Quanto menor esse número, melhor o agente é no trabalho de verdade.

Trinta e sete commits. Uma base de código melhor do que eu tinha no sábado passado. Sábado à tarde e eu vou dar uma volta.