Claude Code 2.1.277 introduz fallback AGENTS.md com limites de feature‑flag

A atualização lançada a 18 de setembro de 2026 do Claude Code, agora na versão 2.1.277, traz consigo suporte nativo à convenção AGENTS.md, um ficheiro em formato Markdown que agrega, a nível de repositório, contexto de desenvolvimento, comandos de teste e regras de contribuição, consolidando assim informações que antes eram dispersas.

Quando um projecto não contém um ficheiro CLAUDE.md, o Claude Code recairá automaticamente para a leitura de AGENTS.md, permitindo que as equipas mantenham uma única fonte de verdade para os metadados de instruções, sem a necessidade de duplicar ficheiros para cada ferramenta ou camada da cadeia de desenvolvimento.

Configuração e controlo

Os operadores podem alternar entre CLAUDE.md e AGENTS.md através do menu /config; a escolha feita é armazenada localmente no cliente, mas a implementação subjacente depende de um plugin interno que só é activado quando um flag de funcionalidade é obtido remotamente, tal como relatado por Korben.

A arquitectura baseada em flags significa que, se o tráfego não essencial ou a telemetria for desactivada, pode impedir a carga do flag; neste cenário o Claude Code reverte silenciosamente ao comportamento anterior, ignorando AGENTS.md sem gerar qualquer erro visível ao utilizador.

Uma solução documentada consiste em manter um ficheiro CLAUDE.md mínimo que simplesmente importa AGENTS.md usando a sintaxe @AGENTS.md; desta forma garante‑se que o fallback funcione mesmo quando o flag não puder ser recuperado devido a restrições de rede.

Panorama de compatibilidade

O lançamento inicial não inclui integração com os principais back‑ends cloud, nomeadamente Amazon Bedrock, Google Vertex AI ou Microsoft Foundry; utilizadores dessas plataformas continuarão a depender de CLAUDE.md ou de ferramentas externas até que uma atualização futura amplie a cobertura para esses serviços.

Vários outros assistentes de desenvolvimento já reconhecem a convenção AGENTS.md, incluindo Codex, Gemini CLI, Devin, Cursor e GitHub Copilot; o suporte já existente reduz a duplicação de instruções em todo o ecossistema e facilita a adoção do novo mecanismo de fallback.

Checklist prática para equipas

• Verificar que /config mostra AGENTS.md selecionado como fonte de instruções
• Confirmar que existe apenas um ficheiro CLAUDE.md para importar @AGENTS.md caso o flag seja bloqueado
• Testar se o Claude Code indica visivelmente "A carregar instruções do projeto a partir de AGENTS.md" na UI
• Garantir que as definições de telemetria ou privacidade não bloqueiam a recuperação do flag remoto

As equipas devem também monitorizar que o número da versão por si só não basta como prova de suporte; a UI tem de indicar explicitamente que as instruções do projeto foram carregadas a partir de AGENTS.md, caso contrário o fallback pode ter falhado silenciosamente, passando despercebido pelos programadores.

Porque o fallback depende de um flag remoto, organizações com políticas de rede rigorosas podem precisar de colocar em lista branca o ponto de extremidade do serviço de flags ou ajustar as definições de privacidade, de modo a garantir um comportamento consistente e previsível.

Na prática, a adição do fallback AGENTS.md simplifica a integração de novos contribuidores, alinha o Claude Code com outros assistentes de IA que já suportam a mesma convenção e reduz a sobrecarga de manutenção de múltiplos ficheiros de instruções sincronizados entre si.

Para organizações de língua portuguesa, o impacto concreto traduz‑se num fluxo de trabalho mais suave e transparente: os programadores podem colocar toda a orientação relevante do projeto num único ficheiro AGENTS.md, o Claude Code honrará automaticamente esse ficheiro quando CLAUDE.md estiver ausente, e as equipas podem validar o comportamento através da UI e da checklist simples acima referida.

É importante notar que, embora a funcionalidade esteja presente a partir da versão 2.1.277, a sua eficácia está condicionada à disponibilidade do flag remoto; testes internos mostraram que, em ambientes onde o acesso à internet é restrito, o fallback pode não ser acionado sem a devida configuração de exceções.

Os desenvolvedores que já utilizam AGENTS.md em outros assistentes podem migrar facilmente para o Claude Code, pois a sintaxe permanece a mesma; basta garantir que o ficheiro está na raiz do repositório e que o plugin interno está activo.

A documentação oficial recomenda ainda que, ao introduzir AGENTS.md, se mantenha a estrutura de seções (por exemplo, "## Contexto", "## Testes" e "## Contribuição") para que o Claude Code possa parsear corretamente o conteúdo e oferecer sugestões contextuais precisas.

Em suma, a versão 2.1.277 representa um passo significativo na direção de uma experiência de desenvolvimento mais unificada, ao mesmo tempo que introduz dependências novas que exigem atenção a nível de infraestrutura e políticas de segurança.

Para os leitores em Portugal, especialmente aqueles baseados em Lisboa, a adoção desta funcionalidade pode acelerar a entrega de código ao reduzir a necessidade de múltiplas revisões de documentação e ao melhorar a colaboração entre equipas distribuídas.