Uma Palavra Errada no AGENTS.md Derrubou a Compilação de 90 para 70 num Bench

Uma rodada de bench de design system descrita pela Southleft avaliou três contextos nas mesmas dez tarefas de design, com três repetições cada. A fatia de gerações que compilaram contra os tipos reais da biblioteca foi 90,0 sem arquivo de instrução, 70,0 com um AGENTS.md e 76,7 com uma skill. Das 19 gerações que falharam de forma grave em toda a rodada, a página atribui 10 a uma única palavra.

O AGENTS.md listava error como tom de status. O valor canônico da biblioteca é danger. No contexto sem arquivo, nenhuma geração esbarrou no problema.

A Southleft então reescreveu o arquivo como um índice que aponta para um contrato gerado e relata a volta ao mesmo patamar de 90 pontos, com um documento 90% menor que o original.

Leia o resultado com os limites na frente. Ele cobre um design system, três repetições por célula, sem variância mostrada. A empresa autora vende serviços de design system, e a página traz uma chamada comercial de consultoria. O agente de código e o modelo ficam anônimos na página. É um padrão que vale testar no seu ambiente, e a evidência para aí.

O que o bench mediu

A página descreve o desenho como 3 cenários diferentes x 3 vezes cada x 10 tarefas de design, 90 gerações avaliadas. Os três cenários correspondem aos três contextos da tabela de resultados, 30 gerações cada:

Contexto	Compila contra os tipos reais	Falhas graves (de 30)	Nota média	Eixo de julgamento
Sem arquivo	90,0	3	95,5	89,3
AGENTS.md	70,0	9	93,0	89,6
Skill	76,7	7	94,2	90,4

Nessa primeira rodada, o contexto vazio ficou à frente dos outros dois na taxa de compilação e na nota média. Os dois contextos de instrução pontuaram abaixo do vazio nesses dois eixos. A explicação da página cobre o arquivo AGENTS.md, e os trechos que lemos silenciam sobre a causa da queda da skill.

Uma palavra errada

A fonte resume numa frase: “One wrong word in the steering document cost ten generations”, ou seja, uma palavra errada no documento de orientação custou dez gerações. O arquivo dizia error. O cânone da biblioteca é danger. Dez gerações com falha foram atribuídas a esse valor.

A falha é estreita e específica. A página relata um dano restrito a este caso, e os números dela sustentam apenas essa leitura. Um valor estava errado, num lugar que o agente lê. O contexto sem arquivo não tinha esse arquivo, então ficou livre dessas falhas.

Nossa leitura do mecanismo: um arquivo que repete vocabulário vira uma segunda fonte de verdade ao lado dos tipos. Quando as duas concordam, a cópia nada acrescenta, porque os tipos já dizem aquilo. Quando divergem, a cópia convence o agente e perde para o compilador. O bench mostra uma divergência, causada por um valor errado. A deriva ao longo do tempo fica fora do alcance dele, embora o mesmo defeito seja o que a desatualização produziria mais tarde.

O que a correção fez

A página descreve a remoção de 90% do conteúdo do AGENTS.md e uma nota menor, 72 contra 90. A tabela dá 70,0 para o arquivo como foi escrito originalmente. Os trechos que lemos deixam em aberto se o 72 é uma rodada separada, então usamos o valor da tabela na comparação acima e registramos a diferença aqui.

Depois o arquivo passou a apontar para o contrato gerado, e a nota voltou: “we sit at the same 90 points baseline with a document that is 90% smaller”, ou seja, estamos no mesmo patamar de 90 pontos com um documento 90% menor. A Southleft também relata custo de tokens do teste cerca de 41% menor e tempo cerca de 22% menor. Os trechos que lemos omitem a base de comparação desses dois percentuais, então os repetimos como números da fonte e deixamos a conclusão de lado.

O princípio de design da página merece citação inteira: “Don’t give agents a list of answers. Give them the language and principles they can use to arrive at the right answer.” Em tradução livre, não dê aos agentes uma lista de respostas, dê a linguagem e os princípios para chegarem à resposta certa. Uma lista de tons de status é uma lista de respostas. Um ponteiro para o contrato que os define é linguagem que o agente resolve na hora da geração, a partir do mesmo artefato que o compilador confere.

O eixo de julgamento quase não se mexeu

As notas de julgamento foram 89,3 sem arquivo, 89,6 com AGENTS.md e 90,4 com a skill. É uma dispersão de cerca de um ponto, enquanto o eixo de compilação variou vinte. O que quer que os arquivos de instrução estivessem fazendo, este bench registrou o julgamento quase parado.

Lemos isso contra uma tese nossa, que deve ficar registrada como nossa: um arquivo de instrução ganha seu lugar ao carregar o julgamento que os tipos não conseguem codificar (quando usar um tom de status, como um componente deve soar, o que o time nunca publica). Para essa metade da tese, o bench da Southleft fica em silêncio. Ele dá evidência para a outra metade: fatos que os tipos já guardam pertencem aos tipos, porque uma cópia errada teve custo mensurável aqui, e o bench deixou a cópia certa sem teste.

Como isso se encaixa no que já publicamos

Nosso texto sobre contexto passivo tratou de uma avaliação da Vercel em que um índice comprimido de AGENTS.md superou skills. O arquivo reescrito pela Southleft também é um índice, então ele é consistente com aquele texto e o mantém de pé. Antes da reescrita, a skill pontuou acima do AGENTS.md neste bench (76,7 contra 70,0).

Nosso texto sobre um arquivo de política de design e seu loop de avaliação tratou da divisão em três da Vercel: julgamento vai em prosa, mecânicas reutilizáveis vão numa folha de estilos, e falhas que uma máquina detecta ganham uma verificação determinística. A divisão da Southleft é parecida. A prosa carrega o julgamento, e o vocabulário vem de um contrato gerado. O que o caso da Southleft acrescenta é uma regra mais estreita dentro do próprio índice: uma lista de valores copiada é onde mora o risco, e um ponteiro para o artefato gerado o remove.

O que a evidência não consegue dizer

Quatro limites. Primeiro, três repetições por célula sem variância mostrada; uma oscilação de 20 pontos em 30 gerações é grande, e outro sorteio poderia cair diferente. Segundo, um único design system, então tudo aqui vale só para aquela biblioteca. Terceiro, uma fonte vendedora de serviços, o que é motivo para ler os números com cuidado e para conferir o bench por conta própria; ele vive num repositório de terceiros que ficou fora da nossa leitura. Quarto, a contabilidade tem uma ponta solta: a página atribui 10 falhas ao valor error, enquanto o contexto AGENTS.md mostra 9 falhas graves. Ou uma das dez está no contexto da skill (a página não põe nenhuma no contexto sem arquivo), ou as duas cifras contam coisas diferentes. O que temos deixa essa escolha em aberto.

A página também traz uma nota de prontidão externa de 40 a 50. Esse número é estimativa da própria empresa autora, e deixamos de usá-lo.

Faça isso agora

Escolha um arquivo de instrução que seus agentes leem, numa base de código com APIs tipadas. Procure nele valores literais: membros de enum, nomes de tokens, nomes de props, tons de status, nomes de funções. Liste cada um.

Para cada item, ache o artefato que já o guarda: os tipos gerados, um schema, uma exportação de tokens. Apague a cópia e coloque um ponteiro no lugar, ou gere essa seção do arquivo a partir do artefato no build, para que ninguém a digite.

Depois rode a verificação que a Southleft rodou, num tamanho que você consiga pagar. Pegue dez tarefas reais. Rode cada uma três vezes sem arquivo e três vezes com o arquivo. Conte quantas gerações compilam contra os tipos reais. Se o arquivo pontuar abaixo do contexto vazio, ache os valores que ele declara e que os tipos também declaram. Comece por aí.

Fontes

Southleft. “What Does AI-Readiness Mean in Design Systems? | Southleft.” Setembro de 2026.

A Victorino ajuda times de engenharia a desenhar os arquivos de instrução que seus agentes leem, mantê-los pequenos e medir se ajudam antes que alguém confie neles: contato@victorino.com.br | www.victorino.com.br