Uma linha no AGENTS.md fez Claude Code e Codex seguirem o código em vez da documentação obsoleta
Uma linha no AGENTS.md fez Claude Code e Codex seguirem o código em vez da documentação obsoleta
Pesquisadores mostraram que agentes de codificação frequentemente seguem documentação obsoleta mesmo quando percebem contradições com o código real. Uma instrução no AGENTS.md aumentou o respeito ao código existente de 4% para 91%.
Se o seu AGENTS.md ficou obsoleto, o Claude Code pode perceber que a documentação já não corresponde ao código real e ainda assim continuar seguindo as instruções antigas.
Os pesquisadores criaram deliberadamente essa situação e realizaram 80 execuções. Em 79 casos, o Claude Code reconheceu a contradição, mas ainda assim caiu na armadilha.
Com o Codex a situação foi ainda pior: em aproximadamente um caso em cada quatro, ele começou a reescrever código já funcional apenas para alinhá-lo à documentação obsoleta.
A correção se mostrou surpreendentemente simples. Basta adicionar uma linha ao AGENTS.md. Depois disso, ambos os agentes passaram a seguir o código existente em 91% dos casos em vez dos 4% anteriores:
“Se a documentação do repositório contradisser o código existente, siga as convenções estabelecidas no próprio código e, na resposta final, indique cada divergência encontrada entre documentação e código.”
Por que isso importa
AnáliseInstruções obsoletas podem degradar silenciosamente a qualidade da programação com agentes. Priorizar o código em relação à documentação ajuda os agentes a quebrar menos o comportamento funcional e a reportar inconsistências com mais precisão.
Debater na comunidade
Compartilhe suas dúvidas e insights com desenvolvedores
Relacionado no ecossistema
Guias práticos, terminologia essencial e skills de agentes
Projetos do Claude Code: como um único IA coordena uma equipe de agentes autônomos
Análise aprofundada dos Projetos do Claude Code: arquitetura Coordinator e Threads, branches paralelas, memória compartilhada MEMORY.md e gerenciamento de agentes na nuvem.
Codex como assistente dentro do Claude Code: Delegação de tarefas rotineiras via Claudex
A verdadeira limitação ao trabalhar com o Claude não está na qualidade do raciocínio do modelo, mas sim na quantidade de tarefas que cabem na janela de contexto antes que ela se esgote.
Claude Code
Agente de desenvolvimento oficial para terminal da Anthropic, que opera diretamente na linha de comando via Claude 3.7 Sonnet, com suporte nativo a Bash, Git, sistema de arquivos e ao protocolo MCP.
Claude passará a usar Auto Mode por padrão para permissões nos planos Pro, Max e Team
A Anthropic informou que, a partir da próxima semana, o Claude usará Auto Mode por padrão para gerenciar permissões nos planos Pro, Max e Team.
diff-tour transforma mudanças de código por agentes de IA em uma revisão guiada
diff-tour organiza o diff do Git em um percurso somente leitura e ajuda a entender o que precisa ser corrigido antes de integrar mudanças do Claude Code ou Codex.
improve-codebase-architecture
Refactor messy codebases into clean, modular, and maintainable layered architectures.