Seu Harness É Código: Versione, Teste E Revise AGENTS.md, Skills E Prompts

Existe um arquivo em quase todo time que adotou agentes de código e que ninguém sabe explicar direito. Ele se chama AGENTS.md, ou CLAUDE.md, ou algo parecido, e nasceu num repositório porque alguém quis que o agente parasse de rodar o comando de teste errado. Meses depois, esse texto foi copiado para o segundo repositório, depois para o terceiro, ganhou duas linhas aqui e três ali, e hoje ninguém lembra quem escreveu a regra que proíbe mexer na pasta de migrações nem por que ela está lá. Se você perguntar quando foi a última vez que alguém revisou o arquivo, a resposta mais provável é um silêncio constrangido.

Não estou descrevendo um caso real de uma empresa específica; é uma cena plausível o bastante para que eu desconfie de que muita gente se reconheça nela. O que me incomodou foi perceber, ao longo desta semana, que o contraste entre o cuidado que damos ao código e o descuido que damos a esse arquivo ficou difícil de justificar. O código passa por pull request, revisão, teste e pipeline. O texto que decide como o agente escreve esse código entra no repositório por commit direto, às vezes sem diff legível, às vezes sem nem estar no repositório.

Dois materiais que li nos últimos dias me empurraram para esse argumento, e eles chegam por lados opostos. Um é um paper do Google sobre agentes que reescrevem o próprio harness e mostram que o que está em volta do modelo muda o resultado. O outro é um relato de segurança sobre arquivos de instrução maliciosos que sequestram agentes. Se o harness muda o resultado e também é superfície de ataque, tratá-lo como anotação informal é uma escolha cada vez mais cara.

Antes de seguir, a transparência de sempre. Não rodei o Harness², não reproduzi o ataque e não tenho um estudo que meça o ganho das práticas que vou propor. O que sei vem do paper no arXiv, da cobertura da Flowtivity, da matéria da Cyberpress sobre a pesquisa da Forever Security e do changelog do GitHub. Este é um texto de opinião: o que descrevo das fontes é relato, e o que proponho é hipótese minha, rotulada como tal. O caminho é este: os dois sinais, o que muda quando instrução é tratada como artefato de produção, revisão e dono, uma mini-suíte de regressão para o harness, proveniência e configuração global, e o que eu não sei.

Dois Sinais Na Mesma Semana

O primeiro sinal é o Harness² (escrito com o 2 sobrescrito no título do paper), de pesquisadores do Google Cloud AI Research, publicado no arXiv em 9 de outubro de 2026. Já descrevi o trabalho em detalhe em um post sobre o agente que reescreve o próprio harness, então aqui fico só com o que sustenta o argumento. O paper define o harness como um conjunto de oito componentes editáveis: system prompt, guardrails, memória, skills, guia de ferramentas, scripts, subagentes e um plugin de middleware. Em vez de ajustar o modelo, o sistema ajusta tudo isso em volta dele.

Os números reportados são de ganhos de um passo de até 11,5 pontos no WorkBuddy-Bench, 4,5 pontos no JobBench e 11,8 pontos percentuais no LAB, usando o GLM-5 e o Gemini 3.5 Flash. É preciso ser preciso sobre o que isso é: benchmarks do próprio Google, execuções médias de três rodadas, dois executores (OpenCode e Codex) e dois modelos. É resultado de paper, não resultado em produção, e é número do fornecedor, não medição independente. Mesmo com todo esse desconto, a mensagem estrutural é difícil de ignorar: mexer só no texto, nas skills e nos scripts em volta do modelo moveu o desempenho por diferenças que o paper considera relevantes.

O segundo sinal veio da Forever Security, em 26 de outubro de 2026, na forma que a Cyberpress relatou. Um arquivo AGENTS.md colocado na pasta Downloads instruía o agente a editar o ~/.codex/config.toml, habilitando um servidor MCP e uma sessão sem sandbox, para então instalar o pacote npm function-color, associado à campanha chamada MALFEX. Segundo o relato, os testes da própria Forever com o Codex tiveram mais de 90% de sucesso, com uma carga inofensiva no lugar da maliciosa. No Claude Code, um CLAUDE.md forjado alterou o .claude/settings.json para apontar a um endpoint do atacante e capturou um token OAuth, em cerca de metade dos testes. De novo, o desconto: é relato de imprensa sobre pesquisa de um fornecedor de segurança, não uma medição de taxa de ataque no mundo real. Tratei o tema com mais calma em um post sobre o AGENTS.md malicioso como vetor de ataque.

Lado a lado, os dois sinais dizem a mesma coisa em tons diferentes. O primeiro diz que o texto em volta do modelo é uma alavanca de desempenho, com efeito suficiente para que um laboratório escreva um sistema inteiro para editá-lo. O segundo diz que o mesmo texto é uma alavanca de controle, com efeito suficiente para que um atacante o use como porta de entrada. Uma alavanca que move desempenho e controle é, pela definição que qualquer tech lead usa no dia a dia, código de produção. A diferença é que quase ninguém o trata assim.

Há um terceiro dado de contexto, mais discreto. No changelog de 28 de outubro de 2026, ligado ao GitHub Universe, o GitHub descreve que administradores podem exigir ou bloquear plugins do Copilot e restringir a instalação a fontes aprovadas. A mesma nota diz que configurações no repositório, em .github/copilot/settings.json, definem padrões mas não os impõem. Não preciso extrair mais do que isso: a governança de customizações de agentes apareceu como assunto de plataforma, com controle de administrador e tudo. Quando o fornecedor da plataforma começa a vender controle sobre esse material, o sinal é que o problema já aparece na agenda de quem opera times grandes.

Instrução Que Governa Um Agente É Artefato De Produção

Vale começar pelo que realmente quero dizer com "tratar como código", porque a expressão é fácil de esticar até virar slogan. Não estou propondo escrever testes unitários para parágrafos de texto nem transformar o AGENTS.md num monumento burocrático. Estou propondo reaproveitar, para esse material, as quatro coisas que já fazemos com o resto do que vai para produção: revisão por outra pessoa, histórico rastreável, teste de regressão e capacidade de voltar atrás.

O argumento de fundo é de proporção. Um commit que altera uma função de cobrança passa por revisão porque o impacto de errar é conhecido. Um commit que altera a linha "sempre rode as migrações antes dos testes" no arquivo de instruções muda o comportamento de todos os agentes de todas as pessoas daquele repositório, em todas as tarefas futuras, e a mudança tem um raio de impacto que não aparece no diff. Se o Harness² mostra que esses componentes mexem no resultado por pontos percentuais, o raio é real, mesmo que o número exato dependa do benchmark.

Pense num cenário hipotético: um time com 12 repositórios e um AGENTS.md copiado de um para outro. No começo era o mesmo texto. Seis meses depois, existem 12 variações. Um repositório diz para usar pnpm, outro para usar npm, um terceiro herdou a frase sobre nunca alterar a pasta de migrações mas não tem pasta de migrações, e um quarto tem uma regra de estilo que contradiz o linter. Ninguém decidiu isso; foi deriva. Quando o agente se comporta de forma diferente entre dois repositórios parecidos, a primeira hipótese, que é o modelo ter variado, costuma estar errada, e a segunda, que é o texto ter divergido, ninguém pensa em checar.

Esse é o tipo de situação que as instruções compartilhadas curadas que defendi para times tentam evitar: um núcleo comum mantido num lugar só, com especializações locais pequenas e explícitas. A curadoria é uma forma de dizer que o texto tem dono e tem origem. O que estou acrescentando agora é que esse núcleo precisa ter, além de curador, o mesmo ciclo de mudança que o resto do software: proposta, revisão, aprovação, registro.

Também vale separar tipos de artefato, porque "instrução de agente" abriga coisas bem diferentes. Um AGENTS.md é, em geral, texto declarativo. Uma skill costuma ter instruções e pode ter scripts anexos. Um script de agente é código executável de fato, e um plugin de middleware, na taxonomia do paper, intercepta o fluxo. Cada um pede um nível de cuidado diferente, e o texto puro é o mais fácil de subestimar justamente porque parece inofensivo. Uma skill compartilhada, em particular, é uma dependência, com tudo o que isso implica.

Revisão E Dono: CODEOWNERS Para Arquivos De Instrução

Aqui começam as propostas práticas, e aviso de uma vez que todas são opinião minha, sem estudo por trás. A primeira é a mais óbvia e a mais barata, e conversa com o que já defendi sobre steering files em projetos agênticos: arquivos de instrução entram por pull request, e o CODEOWNERS do repositório os cobre. Se o AGENTS.md, o CLAUDE.md, a pasta de skills e os scripts de agente aparecem no arquivo de donos, qualquer mudança neles pede aprovação de quem responde por eles. Isso custa uma linha de configuração e muda a natureza do arquivo: ele deixa de ser terra de ninguém.

O segundo ponto é o diff legível. Instruções escritas em parágrafos longos produzem diffs ruins, em que uma mudança de uma palavra reescreve a linha inteira. Uma regra por linha, curta e com verbo no imperativo, facilita ver o que mudou e debater se deveria mudar. Parece detalhe cosmético, mas revisão que não consegue enxergar a mudança vira aprovação automática, e aprovação automática é o que queremos evitar. Quando o arquivo é gerado ou editado por uma ferramenta, o mesmo vale: o diff tem de ser lido por gente antes de entrar.

O terceiro ponto, que tiro diretamente da lógica do Harness², é registrar a evidência da mudança no próprio PR. O paper guarda lições num arquivo chamado EXPERIENCE.md, com aplicabilidade, lições e evidência, e mantém uma edição só se houver contraste de comportamento que a sustente. Não estou dizendo que o paper recomende isso a humanos; estou emprestando a ideia. Uma descrição de PR que responda "qual comportamento errado eu vi e por que esta linha o corrige" faz duas coisas. Obriga quem escreve a ter um motivo, e deixa para quem chegar depois um rastro para decidir se a linha ainda faz sentido. Uma regra sem motivo registrado é uma regra que ninguém tem coragem de remover, e o arquivo só cresce.

O quarto ponto é rollback e dono. Dono significa uma pessoa ou um grupo nomeado, não "o time". Rollback significa que, se uma edição piorar o comportamento dos agentes, voltar ao estado anterior é um git revert, e não uma investigação arqueológica sobre quem mexeu em quê. Isso só funciona se o arquivo estiver no repositório e se as mudanças forem pequenas e atômicas. Um commit que reescreve o arquivo inteiro junto com uma refatoração não é revertível sem levar o resto junto, e isso é um motivo para manter commits de instrução separados.

Testando O Harness: Uma Mini-Suíte Como Hipótese

A parte que mais me interessa, e a mais frágil, é o teste. Código tem teste de regressão porque mudar uma coisa pode quebrar outra e ninguém consegue prever isso de cabeça. O mesmo vale para instruções: uma linha adicionada para corrigir um comportamento pode alterar outro de forma inesperada. Só que, na prática, quase ninguém roda nada antes e depois de editar um AGENTS.md. A edição é validada por impressão: "pareceu melhor na tarefa de hoje".

A hipótese que proponho, inspirada no Probe do Harness² sem afirmar que o paper recomende isso a times, é uma mini-suíte pequena e fixa. Algo como cinco a dez tarefas representativas do repositório, escritas uma vez, com um critério objetivo de sucesso cada uma: corrigir um bug conhecido, adicionar um endpoint seguindo a convenção local, rodar os testes pelo comando certo, não tocar numa pasta proibida. Antes de mergear uma mudança no arquivo de instruções, rodam-se as tarefas com a versão antiga e com a nova, e comparam-se dois sinais: se a tarefa foi resolvida e quantos erros de ferramenta apareceram no caminho.

O paper dá o desenho geral dessa lógica. Cada edição é testada na mesma tarefa, e só permanece se houver contraste de comportamento que a sustente. Isso é diferente de um benchmark gigante: é um teste local, barato, que responde a uma pergunta estreita, a de saber se esta mudança fez o agente se comportar diferente no que eu me importo. A virtude de uma suíte pequena é que ela existe de fato; uma suíte ideal que ninguém monta não protege ninguém.

Há limites que preciso apontar, e o primeiro vem do próprio material. A Flowtivity, ao comentar o Harness², destaca que o seletor pode escolher uma saída pior e que premissas erradas se propagam. Em português claro: um processo que testa e escolhe pode escolher mal, e um erro de interpretação no começo contamina o que vem depois. Para uma mini-suíte feita por humanos, o análogo é que as tarefas podem ser pouco representativas, ou o critério de sucesso pode premiar o comportamento errado. Uma suíte ruim dá confiança falsa, o que talvez seja pior do que não ter suíte.

O segundo limite é a variância. Agentes não são determinísticos, e uma única rodada por versão não diz muito. O paper usa médias de três rodadas, e acho um bom piso para qualquer comparação desse tipo: menos do que isso é anedota. O terceiro é o custo, em tempo e em dinheiro de execução, que cresce com o tamanho da suíte e com o número de edições. Existe um ponto em que o teste custa mais do que a mudança vale, e aí a resposta correta é não testar essa mudança.

Esse raciocínio é parente do que discuti em como avaliar a qualidade de agentes com evals. A diferença de foco é que lá a pergunta era sobre o agente, e aqui é sobre o texto que o governa. Em ambos os casos, a disciplina é a mesma: definir o que é "bom" antes de mexer, medir antes e depois, e desconfiar da melhora que só existe na sua impressão. Um time que já tem evals de agentes provavelmente já tem a maior parte da infraestrutura necessária; falta apontá-la para o arquivo de instruções.

Proveniência E Configuração Global

O caso MALFEX traz uma lição que a mini-suíte não cobre, porque o ataque descrito não depende de o arquivo piorar o desempenho: ele depende de o arquivo vir de fora. A proposta aqui é simples e meio antipática, que é tratar qualquer AGENTS.md de origem externa como entrada não confiável. Um repositório baixado, uma pasta recebida, um projeto de exemplo clonado para estudar: antes de abrir um agente dentro dele, vale ler os arquivos de instrução com os próprios olhos, do mesmo jeito que se espera que alguém leia um script de instalação antes de executá-lo.

No caso relatado pela Cyberpress, o arquivo estava na pasta Downloads, e o alvo do ataque foi a configuração do agente, não o código do projeto. O ~/.codex/config.toml e o .claude/settings.json são arquivos que mandam no comportamento do agente: servidores MCP, permissões, endpoints. Isso me leva à segunda proposta, a de separar duas camadas que costumam ficar misturadas na cabeça das pessoas. De um lado, a instrução do projeto: versionada, revisada, compartilhada. De outro, a configuração global do desenvolvedor: pessoal, fora do repositório, e que merece auditoria própria.

A configuração global é a mais negligenciada porque é invisível para o time. Ninguém revisa o arquivo de configuração do agente na máquina do colega, e ele muda de forma silenciosa quando um instalador, um tutorial ou o próprio agente o altera. Um hábito que me parece razoável, e que é só ideia minha, é vigiar mudanças nesses arquivos: um hash guardado, um alerta quando o arquivo muda sem que a pessoa tenha pedido, ou, no mínimo, o hábito de olhar o diff depois de qualquer sessão estranha. Um agente que edita a própria configuração para desligar o sandbox deveria acender uma luz amarela, e hoje quase nunca acende.

Aqui o contexto do GitHub é útil como contraponto. O changelog de 28 de outubro mostra a plataforma oferecendo controles de administrador sobre plugins, com listas de fontes aprovadas. Isso é a mesma ideia de proveniência, só que implementada por quem tem poder central. A observação do próprio changelog de que configurações no repositório definem padrões, mas não impõem, é o que me interessa: o que mora no repositório orienta, e o que impõe vem de cima. Para um tech lead, isso sugere uma divisão de trabalho. O repositório guarda a intenção do time; a política da organização guarda o limite.

Num cenário hipotético, imagine um dev que recebe, de um recrutador, um repositório de exercício técnico com um AGENTS.md na raiz, e abre o agente dentro dele sem ler nada. Se o arquivo disser ao agente para mexer na configuração global e instalar algo, o dano acontece antes de a pessoa ter escrito uma linha de código. A defesa não é sofisticada: ler o arquivo, abrir o agente em modo restrito, ou abrir primeiro uma sessão sem permissões de escrita fora do diretório. Nenhuma dessas medidas é infalível, e a pesquisa relatada mostra taxas de sucesso altas o bastante para que o hábito de leitura valha mais do que a confiança no agente.

O Que Eu Não Sei

Preciso ser claro sobre o tamanho do que estou afirmando. Não existe, nas fontes que li, um estudo que meça o ganho das práticas que propus aqui. O Harness² mede o efeito de editar o harness de forma automática, em benchmarks do Google; o relato da Forever Security mede a taxa de sucesso de um ataque em testes do próprio fornecedor. Nenhum dos dois mede se PR obrigatório, CODEOWNERS, mini-suíte ou revisão de proveniência reduzem erros ou ataques em times reais. O que fiz foi juntar duas observações e extrair uma consequência de engenharia, que me parece razoável, mas que continua sendo extrapolação.

Há também o custo, e ele não é pequeno. Burocracia em excesso é um jeito eficiente de fazer o time contornar o processo. Se cada ajuste numa linha do AGENTS.md exigir uma suíte de testes e dois aprovadores, as pessoas vão parar de editar o arquivo e voltar a corrigir o agente na conversa, que é justamente o comportamento que gera conhecimento não registrado. A formalidade tem de caber no impacto. Não sei onde fica a linha para cada time, e suspeito que a resposta honesta é que ela se descobre errando para um lado e para o outro.

Por fim, não sei até que ponto os incidentes relatados são típicos. A Cyberpress descreve a pesquisa da Forever; não encontrei no material uma estimativa independente de quantos desenvolvedores abrem repositórios de origem desconhecida com agentes, nem de quantos já foram atingidos. O que sei é que o vetor é plausível, que o relato mostra execução em dois produtos diferentes e que o custo da defesa mínima, ler o arquivo, é quase nulo. Quando o custo da precaução é tão baixo, não preciso de estatística de incidência para recomendá-la.

Conclusão

O que me convenceu, no fim, não foi nenhum número isolado. Foi o desenho conjunto: o texto em volta do modelo mexe no desempenho, segundo um paper do Google, e mexe no controle, segundo um relato de segurança. Qualquer artefato que reúna as duas propriedades já recebe, em outras partes do nosso trabalho, revisão, histórico, teste e dono. Aplicar o mesmo a AGENTS.md, skills e scripts de agente não é uma ideia radical; é consistência com o que já fazemos.

Também preciso repetir o que não sei. As práticas deste texto são hipóteses minhas, derivadas de leitura, não de uso, e não há estudo citado aqui medindo o ganho delas. A parte que defendo com mais convicção é a mais barata: arquivo de instrução no repositório, com dono e revisão, e desconfiança de qualquer arquivo de origem externa. A parte que defendo com menos é a mini-suíte, que depende de tarefas bem escolhidas e de paciência com a variância dos agentes.

Se eu tivesse de resumir numa pergunta para levar à próxima reunião de time, seria esta: se alguém alterar o arquivo que governa o seu agente hoje, quem vai saber, quem vai poder desfazer e como vocês vão perceber se o comportamento piorou? Se a resposta for desconfortável, já é um começo. O resto é calibrar a formalidade ao tamanho do risco, e isso, como quase tudo em engenharia, só se aprende ajustando.

Fontes:

Seu Harness É Código: Versione, Teste E Revise AGENTS.md, Skills E Prompts

Seu Harness É Código: Versione, Teste E Revise AGENTS.md, Skills E Prompts

Dois Sinais Na Mesma Semana

Instrução Que Governa Um Agente É Artefato De Produção

Revisão E Dono: CODEOWNERS Para Arquivos De Instrução

Testando O Harness: Uma Mini-Suíte Como Hipótese

Proveniência E Configuração Global

O Que Eu Não Sei

Conclusão

Receba os artigos mais relevantes da semana, sem quebrar seu ritmo de leitura

eltonjose