Ambiente Legível Para Agentes: O Que Ajustar No Repositório Antes De Trocar De Modelo

Existe um hábito que reconheço em conversas com outros tech leads, e em mim mesmo quando estou com pressa: o agente erra duas ou três vezes seguidas na mesma tarefa e a reação é abrir a lista de modelos. Será que o próximo da fila entende melhor? Às vezes entende. Mas, na maior parte das conversas que acompanho, o erro repetido tinha uma causa bem menos glamourosa: o agente não tinha como ver o que acontecia, não conseguia rodar a coisa de novo do mesmo jeito, ou ninguém tinha escrito em lugar executável a regra que ele quebrou.

Essa dúvida voltou na segunda-feira, quando li um texto do Redreamality, assinado por Remy e publicado em 19 de outubro, chamado "Making the Environment Legible to Agents". Vale dizer o que ele é: uma fonte secundária, que organiza casos de terceiros sob uma tese comum, e não um estudo com medição própria. Mesmo assim, a pergunta que ele coloca é útil: que capacidade falta no ambiente para que esse agente consiga acertar?

Eu não apliquei essas ideias num repositório e não vou fingir que sim. O que faço aqui é estudo de leitura: junto o texto do Redreamality, um artigo de Kyle Kukshtel sobre harness para desenvolvimento de jogos e um resumo de notas de Dan Luu, e tento extrair um mapa que um time possa usar. O mapa tem quatro propriedades e uma ordem de investimento, com ressalvas sobre quando ele não compensa.

Vou começar pela mudança de foco em relação ao que o blog já discutiu sobre harness, passar pelas quatro propriedades com um exemplo de cada, olhar o caso dos jogos em detalhe, depois o de infraestrutura de código e do repositório do Codex, discutir a ordem e o porquê de merge ficar por último, e fechar com os limites de escala e uma forma de medir se o ambiente melhorou.

Do Prompt E Do Laço Ao Repositório: O Que Muda No Foco

Quando escrevi sobre SDD e harness engineering, a imagem dominante era a do laço: o modelo no centro e, em volta dele, o sistema de controle que decide o que ele vê, o que pode fazer e como o resultado é conferido. Agent igual a modelo mais harness. Depois, no post sobre mise en place para codar com agente, o foco foi a preparação: o contexto, as tarefas e os artefatos que você organiza antes de delegar. Os dois olham, de ângulos diferentes, para o que cerca o prompt.

A tese que circula nesta semana empurra a mesma ideia um degrau para baixo. O Redreamality argumenta que, quando escrever código fica barato, o que limita o agente é se o ambiente permite consultar, reproduzir, medir e fazer cumprir. O harness, nessa leitura, desce do laço em torno do modelo para o repositório, o motor de execução e o CI. Em vez de pensar só no que você coloca na janela de contexto, você pensa no que o sistema responde quando o agente pergunta, e no que acontece quando ele erra.

Dá para ver por que a mudança de ênfase é plausível. Se gerar uma implementação custa segundos, o gargalo se desloca para saber se a implementação está certa e para encontrar o ponto onde ela quebrou. Um resumo do Developers Digest sobre notas de Dan Luu chega a uma formulação parecida: o gargalo passou de gerar para verificar. Uma ressalva honesta sobre essa fonte: é um resumo secundário e o ensaio original não foi lido por mim, então trato o que vem dele como sugestão do artigo, sem benchmark por trás.

O ganho prático dessa visão é uma regra simples para o dia em que o agente trava. Antes de trocar de modelo, pergunte que capacidade falta ao ambiente e como torná-la legível e verificável. É a sugestão final do autor do Redreamality, e eu a adotaria como pergunta de triagem mesmo sem ter dados que provem que ela vence a troca de modelo. Ela custa uma conversa e uma leitura do pipeline; a troca de modelo custa migração e reavaliação.

As Quatro Propriedades Com Um Exemplo De Cada

O texto organiza o ambiente legível em quatro propriedades. Elas funcionam melhor quando lidas como perguntas que o agente faria ao sistema. Consultável: posso perguntar ao sistema diretamente, ou só trabalho com cópias locais e suposições? Reproduzível: com as mesmas entradas, obtenho os mesmos resultados? Mensurável: o resultado vem como texto e números que consigo usar, ou como tela que um humano precisa assistir? Fazível por regra, o "enforceable" do original: as regras estão codificadas em código, permissões ou checagens que bloqueiam a violação, ou moram na cabeça de quem revisa?

Para cada uma, um exemplo curto, todos hipotéticos. Imagine um agente que precisa entender por que uma função foi escrita de certo jeito. Se o repositório só existe como cópia local rasa, ele adivinha; se há um servidor que responde a consultas de histórico e de autoria de linha, ele pergunta. Isso é consultável, e é o tipo de capacidade que o caso da Anthropic, mais adiante, ilustra.

Reproduzível aparece quando um teste passa na máquina do agente e falha no CI. Pense num teste que depende do relógio do sistema ou de uma ordem de execução que muda. O agente corrige, roda de novo, vê verde, entrega, e o pipeline reprova. Sem entradas controladas, o sinal é ruído, e ruído convence o agente de que terminou. Mensurável é o caso do desempenho: um profiler com interface gráfica não serve a quem lê texto, enquanto uma saída textual com tempos por função serve.

Fazível por regra é a mais subestimada. Uma convenção como "a camada de domínio não importa nada da camada de infraestrutura" costuma viver em documento de arquitetura e em comentário de revisão. Um humano atento a aplica na maior parte das vezes. Um agente que produz dezenas de mudanças por dia vai esbarrar nela com frequência, e cada violação vira trabalho de revisão. Se a regra vira uma checagem que falha o build e explica o motivo, a violação deixa de custar atenção humana e passa a custar uma iteração do próprio agente.

As quatro propriedades se apoiam entre si: reproduzir sem medir dá um resultado idêntico que ninguém interpreta, e medir sem reproduzir dá número que muda sem motivo. Por isso a ordem de investimento importa mais que a lista.

Isso também se distingue dos arquivos de orientação como AGENTS.md, que dizem ao agente o que fazer em prosa. É a forma mais fraca de regra, porque depende de ele ler e obedecer; uma checagem executável só deixa passar o que cumpre a regra.

O Caso Dos Jogos: Tornar O Estado Endereçável

O exemplo mais concreto que li vem de Kyle Kukshtel, em "How to engineer an AI harness for game development", publicado em 10 de outubro e baseado numa palestra de 12 de setembro no Indie Rodeo, em Calgary. Segundo o próprio autor, o texto foi escrito à mão. A tese dele é que um jogo vira o próprio harness quando um LLM consegue ler o estado, alterá-lo e verificar o resultado. O problema de partida é que LLMs têm dificuldade com jogos porque boa parte do jogo é dado opaco que não é código, e a correção que ele propõe é tornar esse estado endereçável.

Quase cada decisão dele mapeia para uma das quatro propriedades. Para reprodutibilidade, a aleatoriedade passa por uma fonte única com semente, de modo que qualquer estado do jogo possa ser reconstruído. Para consultabilidade e mudança controlada, ele defende save e load desde o início, com um tipo genérico de objeto, o "Thing", que carrega atributos, uma flag de vivo e um enum de tipo. A vantagem é ter um único caminho de serialização. Ele mesmo trata isso como trade-off: um tipo único simplifica a leitura do estado e pode complicar o modelo de domínio.

A decisão que acho mais instrutiva é a de expressar mudanças como objetos de comando serializáveis, que um processador aplica. Como o comando é dado, ele pode ser gravado, reexecutado e escrito à mão ou por um agente, sem recompilar. Para ilustrar a ideia, e só isso, um comando poderia ter esta forma:

{ "tipo": "mover", "alvo": "thing_42", "para": [3, 7], "semente": 1234 }

Esse exemplo é meu, ilustrativo, e não vem do artigo. O que ele captura é o princípio: a intenção vira dado, o dado é registrável, e o registro permite repetir a cena. Junto a isso, Kukshtel mantém dados estáticos em arquivos externos fora do build e põe a lógica de simulação numa biblioteca separada, com o motor conversando por comandos e diffs de estado.

Na medição, duas escolhas chamam atenção. Para progresso visual, o autor usa screenshots com camadas de interface e de gameplay que podem ser ligadas e desligadas, e faz diff de imagem, por exemplo com odiff, que devolve uma pontuação de similaridade como linha de base entre turnos. Recortar a região relevante reduz o ruído. Para desempenho, usa profilers com saída em texto, como o samply, porque agentes leem texto melhor que interfaces gráficas. Com isso, descreve o agente rodando um ciclo de editar, testar e medir em segundos.

O que Kukshtel não promete merece o mesmo destaque. Ele diz que as técnicas valem para projetos maiores: um jogo pequeno que publicou não precisou de nada disso. Diz que o ponto é gerenciar contexto e remover gargalos de compilação, não compensar alguma limitação fundamental dos LLMs. E nota que muitas das práticas melhoram o desenvolvimento de jogos com ou sem IA. Essa última observação ajuda a decidir: se o investimento se paga sem o agente, o argumento de custo-benefício fica mais fácil.

Infraestrutura De Código: Os Casos Da Anthropic E Do Codex

O segundo domínio que o Redreamality usa é a infraestrutura de controle de versão e de entrega. Todos os números desta seção vêm desse texto, que por sua vez os atribui a casos de terceiros; eu não os verifiquei de forma independente, e o leitor deve tratá-los como relato de fonte secundária. Segundo ele, a Anthropic migrou o monorepo do git para o Scion. Os merges teriam passado de cerca de 2.500 por dia em maio de 2026 para mais de 30.000 em setembro. O detalhe do Scion está no post de terça sobre revisão por intenção; aqui só importa o ângulo da legibilidade.

Sob esse ângulo, o Redreamality destaca dois movimentos. Primeiro, clientes sempre online e um servidor que responde a consultas de histórico e de blame: é a propriedade consultável levada ao sistema de versionamento, em que o agente pergunta em vez de arrastar uma cópia. Segundo, a fila de merge global teria sido substituída por teste pós-merge e pré-deploy, com humanos revisando a intenção e não cada linha. Aqui, a verificação deixa de ser um portão serial e passa a ser um sinal contínuo, o que só funciona se o ambiente for reproduzível e medido.

O outro caso é o do repositório do Codex, segundo o mesmo texto. Uma equipe pequena teria construído cerca de um milhão de linhas, com aproximadamente 1.500 pull requests mesclados, em cinco meses. As decisões de ambiente descritas são específicas. Cada worktree ganha o próprio aplicativo em execução e a própria pilha de observabilidade, que o agente consulta; é o que o blog já tratou do lado do isolamento em worktrees para rodar agentes em paralelo, agora com a camada de observação em cima. O conhecimento fica numa pasta estruturada de documentos, e as mensagens de lint explicam como corrigir a violação.

Esse último detalhe é pequeno e, para mim, o mais transferível de todo o texto. Uma mensagem de lint que apenas diz "violação da regra X" obriga o agente a deduzir a correção; uma que diz o que mudar entrega a correção no momento da falha. Para um agente, que lê a saída do lint como parte do laço, a mensagem é a instrução.

Há uma ressalva que o próprio texto registra e que eu repetiria em voz alta: segundo o Redreamality, a OpenAI reconhece que a abordagem de poucos gates de merge seria irresponsável em ambientes de menor vazão. Ou seja, o relaxamento da revisão que esses casos mostram não é um modelo a copiar, é uma consequência de ter reprodutibilidade, monitoramento e reversão pagos de antemão, num volume em que a revisão linha a linha não escala. Copiar a ausência de portão sem copiar a infraestrutura que a sustenta é a leitura errada do caso.

A Ordem De Investimento E Por Que Merge Fica Por Último

O Redreamality propõe uma ordem de investimento em cinco passos, e a ordem é a parte que mais me interessa, porque a maioria dos times começa pelo fim. O primeiro passo é tornar a verificação headless e com saída em texto ou números. Se um teste só pode ser julgado por alguém olhando uma tela, o agente não participa do julgamento. Transformar a checagem em algo que roda sem interface e imprime um resultado legível é o ganho de maior alavancagem e o de menor risco.

O segundo passo é centralizar o não determinismo: sementes, tempo e funções matemáticas passam por pontos únicos que você controla. É o que Kukshtel faz com a aleatoriedade, e é o que torna possível repetir uma falha. O terceiro é isolar ambientes por mudança, para que agentes possam rodar em paralelo sem pisar uns nos outros, o que reaproveita a lógica dos worktrees com aplicativo próprio. O quarto é transformar regras de arquitetura em lints e testes que falham, com mensagens que ensinam a corrigir.

O quinto passo é mudar merge e controle de versão, e o texto o coloca por último de propósito: só com reversão automática, monitoramento e permissões. A razão é de risco. Os quatro primeiros passos aumentam o que o agente sabe e o que ele não pode quebrar; o quinto reduz o que um humano confere antes de algo ir para a frente. Reduzir a conferência sem poder desfazer rápido é trocar um gargalo por um incidente.

Um cenário hipotético: um serviço de pagamentos com testes que dependem da data atual e um pipeline que só roda de madrugada. O retorno vem antes de mexer no merge: injetar o relógio para o teste ficar determinístico, fazer a suíte rodar em minutos com relatório em texto e escrever o lint que proíbe acesso ao banco fora da camada de repositório.

Uma ponta que o resumo das notas de Dan Luu acrescenta, de novo como sugestão do artigo, é a separação entre quem redige e quem julga. Um agente que avalia a própria mudança é autorreferencial, então vale dar a ele um sinal externo, como um fuzzer ou o CI, pedir um caminho de reprodução e um teste que falhe antes da correção, e conferir que ele falha antes e passa depois.

Quando Não Compensa E Como Medir Se Melhorou

Nem tudo isso se paga em qualquer projeto, e as fontes são razoavelmente claras. Kukshtel diz que o jogo pequeno que publicou não precisou de nada disso, e que o valor aparece em projetos maiores. O caso do Codex é uma equipe pequena, mas num repositório que cresceu para cerca de um milhão de linhas em cinco meses, segundo o texto, e a OpenAI, ainda segundo o Redreamality, reconhece que a abordagem não serve a ambientes de menor vazão. Em escala pequena, o custo de montar ambientes isolados, observabilidade por worktree e lints sob medida pode superar o ganho. Vale começar pelo passo um e subir só quando a dor aparecer.

O ambiente não resolve tudo: Kukshtel afirma que o ponto é gerenciar contexto e remover gargalos de compilação, não suprir limitação fundamental dos modelos. Se o agente erra por falta de capacidade de raciocínio, nenhum lint resolve, e trocar de modelo pode ser correto. A regra prática que proponho é de triagem, não de dogma: se a falha se repete na mesma tarefa, pergunte primeiro que capacidade falta ao ambiente; se o ambiente já responde, reproduz, mede e bloqueia, e a falha persiste, aí a troca de modelo tem base.

Para saber se o ambiente melhorou, o resumo sobre as notas de Dan Luu sugere medir o agente por tipo de tarefa, como reprodução de bug, migração, refactor, interface e arquitetura, em vez de uma nota geral. Eu acrescentaria duas métricas simples, ambas deduzidas por mim e não vindas das fontes. A primeira é a taxa de falha por tipo de tarefa antes e depois de cada mudança de ambiente. A segunda é o tempo do ciclo de editar, testar e medir, que é justamente o número que Kukshtel descreve como caindo para segundos no caso dele. Se o ciclo encurta e a taxa de falha da tarefa não muda, o gargalo está em outro lugar.

Um último cuidado: mudar ambiente e modelo ao mesmo tempo apaga a leitura. Mude uma coisa por vez e compare tarefas do mesmo tipo; nenhuma fonte que li traz benchmark comparando ganho de ambiente com ganho de modelo.

Conclusão

O que me convence nessa leitura é menos a tese em si do que o tipo de pergunta que ela abre. Em vez de "qual modelo acerta mais", a pergunta passa a ser "o que o agente consegue ver, repetir, medir e ser impedido de quebrar neste repositório". Ela vira trabalho de engenharia comum: injetar o relógio, imprimir resultado em texto, escrever o lint com mensagem boa. Kukshtel observa que muitas dessas práticas melhoram o desenvolvimento com ou sem IA, o que reduz o risco de jogar o investimento fora.

Também fico com cautela sobre o que não sei. A base aqui é um texto secundário que reúne casos de terceiros, um artigo de um desenvolvedor de jogos descrevendo a própria prática e um resumo de notas que eu não confrontei com o original. Os números sobre Anthropic e OpenAI chegam por uma única fonte, e nenhuma delas compara ganho de ambiente com ganho de modelo. É um argumento plausível, bem ancorado em exemplos, e ainda sem medição que o sustente em geral.

Por isso a conclusão que me parece segura é a mais modesta: da próxima vez que um agente falhar repetidamente na mesma tarefa, gaste uma hora olhando que capacidade falta ao ambiente antes de abrir a lista de modelos. Se a resposta for "nenhuma", você ganhou uma base melhor para trocar. Se for "esta aqui", você provavelmente ganhou algo que vale além deste agente e deste ano.

Fontes:

• Redreamality — Making the Environment Legible to Agents
• Kyle Kukshtel — How to Engineer an AI Harness for Game Development
• Anthropic Engineering — Redesigning Source Control at Anthropic
• Developers Digest — Dan Luu's Agentic Coding Notes Point to the Real Bottleneck