# AGENTS.md em 2026: o que é e como criar o seu ficheiro em 30 minutos
> Formato AGENTS.md, suporte em ferramentas de IA, modelo pronto a usar, regras e erros. Como coordenar AGENTS.md com CLAUDE.md e outros ficheiros de instruções.
Source: https://ailoot.ai/blog/pt-pt/agents-md-guide-template/
Canonical: https://ailoot.ai/blog/pt-pt/agents-md-guide-template/
Language: pt-PT
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-034
Revision: sha256-d4dba3a877478f4dbd4d14b53e316da51eff165b63b0ca8ad1e4380cef5d557f
Materiais práticos sobre vibe coding e trabalho com agentes: [documentação Ailoot](https://ailoot.ai/docs/).
## AGENTS.md num parágrafo
Destaque da secção
AGENTS.md é um ficheiro Markdown simples na raiz do projeto que contém instruções para um agente de IA: como instalar dependências, executar testes, que estilo de código seguir e no que não mexer. O formato é aberto, foi criado pela OpenAI em agosto de 2025 e integrou a Linux Foundation em dezembro desse mesmo ano. Muitas ferramentas de programação podem utilizá-lo, mas a descoberta varia conforme o cliente e a versão: algumas carregam AGENTS.md automaticamente, enquanto outras exigem uma configuração explícita do nome do ficheiro ou do caminho de leitura. Desde a versão 2.1.277 (setembro de 2026), o Claude Code também lê AGENTS.md se o projeto não tiver CLAUDE.md. Se CLAUDE.md estiver presente, o Claude Code lê apenas esse ficheiro por predefinição, e AGENTS.md é incluído com a linha `@AGENTS.md` ou através de uma ligação simbólica.
A seguir, o formato é analisado com base em [agents.md](https://agents.md), na documentação do [OpenAI Codex](https://github.com/openai/codex), [JetBrains Junie](https://junie.jetbrains.com/docs/guidelines-and-memory.html), [Cursor Rules Docs](https://cursor.com/docs/rules), no [registo de alterações do GitHub Copilot Coding Agent](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/) e no [comunicado de imprensa da Linux Foundation sobre a Agentic AI Foundation](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation). Todos os números e funcionalidades estão atualizados a 30 de maio de 2026, e o suporte de AGENTS.md no Claude Code é descrito de acordo com a [documentação da Anthropic](https://code.claude.com/docs/en/memory#agents-md), atualizada em 24 de setembro de 2026.
Se não faz ideia do que é este zoo de ferramentas disponíveis no mercado ou porque precisam de um ficheiro comum, leia primeiro o guia [«Com que programar em 2026: 8 ferramentas de IA, do Claude Code ao Antigravity»](https://ailoot.ai/blog/pt-pt/ai-coding-tools/). Este artigo centra-se especificamente no formato AGENTS.md e em como criar o seu em 30 minutos.
## O que é AGENTS.md e de onde veio?
Destaque da secção
AGENTS.md é um formato aberto de ficheiro Markdown no qual pode escrever instruções para agentes de IA. A OpenAI lançou-o em agosto de 2025 juntamente com o Codex CLI e convidou de imediato coautores: Cursor, Sourcegraph Amp, Google Jules e Factory. A ideia é simples: «não vamos criar um ficheiro proprietário para cada ferramenta; vamos chegar a acordo sobre um único». A 9 de dezembro de 2025, AGENTS.md, juntamente com o MCP da Anthropic e o goose da Block, integrou a Linux Foundation como um dos três projetos fundadores da nova Agentic AI Foundation. Em dezembro desse mesmo ano, mais de 60 000 repositórios do GitHub já continham AGENTS.md na raiz.
Anteriormente, cada ferramenta de IA tinha o seu próprio ficheiro de regras: a Anthropic tinha `CLAUDE.md`, o Cursor tinha `.cursorrules`, o GitHub tinha `.github/copilot-instructions.md`, o Aider tinha `.aider.conf.yml` e a JetBrains tinha `.junie/guidelines.md`. Se a sua equipa tivesse três agentes diferentes, isso significava três ficheiros paralelos com o mesmo conteúdo, que divergiriam numa semana.
A OpenAI foi a primeira a cansar-se disto. Em agosto de 2025, lançou o Codex CLI e, ao mesmo tempo, lançou [agents.md](https://agents.md) como formato aberto. No site:
> «Pense em AGENTS.md como um README para agentes.»
>
> ([agents.md](https://agents.md), traduzido do inglês)
A ideia principal é que AGENTS.md complementa o README. O README é escrito para pessoas: «o que é o projeto, como o executar localmente, como contribuir». AGENTS.md é escrito para o agente: comandos de shell exatos, critérios verificáveis para considerar algo «concluído» e limites como «nunca mexas nisto».
No site:
> «AGENTS.md complementa o README: contém contexto adicional, por vezes detalhado, de que o agente precisa — passos de compilação, testes e convenções que sobrecarregariam o README ou simplesmente não são necessários para quem contribui como pessoa.»
>
> ([agents.md](https://agents.md), traduzido do inglês)
Em setembro de 2025, o GitHub Copilot Coding Agent já suportava o formato ([registo de alterações, 28.08.2025](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/)). Em dezembro, juntaram-se Cursor, Junie, Gemini CLI, Aider e mais uma dúzia de ferramentas. A 9 de dezembro de 2025, a Linux Foundation criou a [Agentic AI Foundation (AAIF)](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation): os seus três projetos fundadores eram AGENTS.md da OpenAI, MCP da Anthropic e goose da Block. Os membros fundadores eram AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft e OpenAI. A 24 de fevereiro de 2026, a fundação já incluía [146 organizações](https://www.linuxfoundation.org/press/agentic-ai-foundation-welcomes-97-new-members), entre as quais Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, UiPath e Hitachi.
A partir daí, AGENTS.md deixou de ser «mais uma coisa da OpenAI» e tornou-se um padrão de facto.
## Que agentes de IA leem AGENTS.md e quais não leem?
Destaque da secção
AGENTS.md é usado em muitas ferramentas de programação, incluindo os clientes abaixo. Leia a tabela como um mapa das formas de carregamento, não como uma promessa de suporte nativo idêntico: a descoberta automática, a configuração explícita, a precedência dos nomes e o tratamento de ficheiros aninhados podem variar. O Claude Code da Anthropic foi uma exceção durante muito tempo: o issue \#6235, que pedia suporte, permaneceu aberto de agosto de 2025 a agosto de 2026. Desde a versão 2.1.277 (18 de setembro de 2026), o Claude Code lê AGENTS.md por si só se o projeto não tiver CLAUDE.md. Se CLAUDE.md estiver presente, lê apenas esse ficheiro por predefinição, e AGENTS.md é incluído com a linha `@AGENTS.md` dentro de CLAUDE.md ou através de uma ligação simbólica.
Tabela de suporte a 30 de maio de 2026; a linha do Claude Code foi atualizada a 24 de setembro de 2026:
| Ferramenta | Lê AGENTS.md | Data / fonte |
|----|----|----|
| OpenAI Codex CLI | Sim (formato nativo) | agosto de 2025, [agents.md](https://agents.md) |
| GitHub Copilot Coding Agent | Sim | 28.08.2025, [GitHub Changelog](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/) |
| Cursor | Sim, raiz + ficheiros aninhados | [Cursor Rules Docs](https://cursor.com/docs/rules) |
| JetBrains Junie | Sim, projeto + global `~/.junie/AGENTS.md` | [Junie Docs](https://junie.jetbrains.com/docs/guidelines-and-memory.html) |
| Gemini CLI (Google) | Sim, através de `.gemini/settings.json` com `fileName: AGENTS.md` | [agents.md](https://agents.md) |
| Jules (Google) | Sim, coautor do padrão | agosto de 2025 |
| Sourcegraph Amp | Sim, coautor do padrão | agosto de 2025 |
| Aider | Sim, através de `read: AGENTS.md` em `.aider.conf.yml` | [agents.md](https://agents.md) |
| Factory | Sim, coautor do padrão | agosto de 2025 |
| OpenCode | Sim | — |
| Zed | Sim | [agents.md](https://agents.md) |
| Warp | Sim | [agents.md](https://agents.md) |
| VS Code | Sim | [agents.md](https://agents.md) |
| Windsurf | Sim | — |
| Devin (Cognition) | Sim, através de Spec Kit Skills | abril de 2026 |
| RooCode, Kilo Code, Augment Code | Sim | [agents.md](https://agents.md) |
| **Claude Code (Anthropic)** | **Sim, se o projeto não tiver CLAUDE.md** | Desde a versão 2.1.277 (18.09.2026), [documentação do Claude Code](https://code.claude.com/docs/en/memory#agents-md) |
A Anthropic foi a última das grandes empresas a aderir. Em agosto de 2025, foi aberto no repositório oficial `anthropics/claude-code` o issue \#6235, a pedir suporte para AGENTS.md.
O issue permaneceu aberto durante quase um ano e foi fechado a 17 de agosto de 2026; a versão 2.1.277, com suporte para AGENTS.md, foi lançada a 18 de setembro. A lógica da Anthropic é a seguinte: CLAUDE.md tem precedência e AGENTS.md é lido quando não existe CLAUDE.md na pasta de trabalho nem em qualquer pasta ascendente. De acordo com a [documentação](https://code.claude.com/docs/en/memory#agents-md), funciona assim:
| O que existe no projeto | O que o Claude Code lê |
|----|----|
| Apenas AGENTS.md | AGENTS.md |
| AGENTS.md e CLAUDE.md (ou CLAUDE.local.md) | Apenas CLAUDE.md |
| CLAUDE.md com a linha `@AGENTS.md` | CLAUDE.md, que inclui AGENTS.md |
O senão: um `CLAUDE.local.md` pessoal também conta e, nesse caso, o Claude Code deixa de ler AGENTS.md. Pode alterar este comportamento em `/config`, em Project instructions — por exemplo, para fazer com que o Claude Code leia ambos os ficheiros ao mesmo tempo. Nas versões anteriores à 2.1.277, AGENTS.md não é carregado automaticamente; a linha `@AGENTS.md` em CLAUDE.md continua a ser a solução alternativa.
## Em que difere AGENTS.md de CLAUDE.md e `.cursorrules`?
Destaque da secção
Tecnicamente, não há nada de especial neles: os quatro formatos (AGENTS.md, CLAUDE.md, `.cursorrules`, `.github/copilot-instructions.md`) são ficheiros Markdown comuns com instruções para um agente. A diferença está em quem os lê e onde se encontram. AGENTS.md pode reunir as instruções comuns a vários clientes, mantendo separadas as configurações de descoberta ou carregamento específicas de cada um. CLAUDE.md destina-se apenas ao Claude Code, mas dá-lhe acesso a funcionalidades avançadas: regras associadas a caminhos, `CLAUDE.local.md` para substituições pessoais, `@import` para incluir outros ficheiros e uma hierarquia de projeto + utilizador + local. `.cursorrules` está obsoleto no Cursor — o novo sistema usa `.cursor/rules/*.mdc` com associação automática por tipo de ficheiro. `.github/copilot-instructions.md` só é necessário para o Copilot na Web.
Comparação dos quatro formatos a 30 de maio de 2026:
| Formato | Quem o lê | Onde se encontra | Ponto forte | Ponto fraco |
|----|----|----|----|----|
| **AGENTS.md** | Vários clientes, com descoberta ou configuração própria | Raiz do repositório e subpastas conforme as regras do cliente | Instruções comuns, sem depender de um único fornecedor | Descoberta, precedência e regras pessoais variam conforme o cliente |
| **CLAUDE.md** | Apenas Claude Code | Raiz + `~/.claude/CLAUDE.md` + `CLAUDE.local.md` | Hierarquia, regras associadas a caminhos, `@import`, skills, hooks | Apenas Claude. Não funciona no Cursor / Codex / Copilot |
| **`.cursor/rules/*.mdc`** | Apenas Cursor | `.cursor/rules/.mdc` | Associação automática por tipo de ficheiro (TS, Python, caminhos específicos) | Apenas Cursor, sintaxe `.mdc` não normalizada |
| **`.github/copilot-instructions.md`** | GitHub Copilot (Web + clássico) | `.github/` | Funciona diretamente no browser em GitHub.com | Apenas Copilot, duplica AGENTS.md |
A ideia principal: AGENTS.md resolve o problema de «um ficheiro para todos os agentes», mas não o de «definições pessoais que não quero enviar para o repositório». O Claude Code tem `CLAUDE.local.md` para isso, e o Cursor tem ficheiros `.mdc` locais na pasta do utilizador. AGENTS.md, por si só, não oferece essa possibilidade — é necessário combiná-lo com outros ficheiros ou acordar em equipa que as regras pessoais sejam escritas em secções ignoradas pelo Git.
Outro detalhe importante são os monorepos. Codex e Cursor aplicam a regra «prevalece o AGENTS.md mais próximo»:
> «Num monorepo, coloque um AGENTS.md separado dentro de cada pacote. Os agentes leem automaticamente o ficheiro mais próximo na árvore de diretórios, e prevalece o mais próximo.»
>
> ([agents.md](https://agents.md), traduzido do inglês)
[agents.md](https://agents.md) refere que o monorepo principal da OpenAI contém 88 ficheiros AGENTS.md para diferentes subpacotes. Se trabalhar num monorepo, distribua as regras por níveis: regras gerais na raiz e regras específicas nas subpastas.
## O que deve conter um bom AGENTS.md?
Destaque da secção
A estrutura de um bom AGENTS.md tem 8 secções que se encontram na maioria dos ficheiros populares: visão geral do projeto, comandos de configuração, estilo de código, dicas sobre o ambiente de desenvolvimento, instruções de teste, diretrizes para PR, considerações de segurança e limites (o que não fazer). Tudo o resto é opcional. A regra principal: cada item deve ser um comando exato ou um exemplo concreto, e não uma ideia geral como «escreva código limpo».
O site [agents.md](https://agents.md) propõe um formato flexível — «qualquer Markdown». Mas 80% dos bons ficheiros existentes contêm as mesmas oito secções. A regra principal: cada item deve ser um comando exato ou um exemplo concreto. Uma ideia abstrata como «escreva código limpo» será ignorada pelo agente.
1. **Visão geral do projeto** — 2–3 linhas. O que é o projeto, a quem se destina e qual é o seu objetivo principal. Sem marketing. Exemplo: «Bot de Telegram para integração num workshop pago. Stack: Next.js 14, Prisma, PostgreSQL. É acionado quando é criado um novo registo em `purchases`.»
2. **Comandos de configuração** — comandos de shell exatos para executar localmente. `npm install`, `npm run dev`, `npm run build`. Nada de «é assim que normalmente fazemos».
3. **Estilo de código / convenções** — regras específicas com um exemplo, não «escreva código limpo». Por exemplo: «TypeScript strict, aspas simples, sem exports por predefinição, nomes dos componentes em PascalCase, hooks começam por `use`.»
4. **Dicas sobre o ambiente de desenvolvimento** — onde estão as coisas importantes. Que variáveis são necessárias em `.env`, onde estão guardados os segredos, que portas estão a ser usadas e como trabalhar com a DB local.
5. **Instruções de teste** — como executar um teste específico e o que conta como resultado «verde». Por exemplo: `npm test -- --testPathPattern=user-auth`; espera-se uma aprovação de 100%.
6. **Diretrizes para PR / commits** — formato das mensagens de commit, lista de verificação antes do PR (testes, linter, documentação) e quem aprova.
7. **Considerações de segurança** — o que nunca deve acontecer. «Nunca faça commit de `.env`. Os segredos pertencem apenas ao Vault. Não mostre dados pessoais dos utilizadores nos registos.»
8. **Limites / Nunca fazer** — proibições acompanhadas de uma alternativa. «Não use `git push --force` em main. Se precisar de reverter, use `git revert` ou `git reset` num feature branch.»
Em cada secção, siga o princípio «comando em vez de ideia». O agente vai ignorar «tenha cuidado com as migrações». Vai seguir «Antes de `alembic upgrade head`, execute `alembic check`. Se indicar um erro, não aplique a migração; pergunte-me».
## Modelo AGENTS.md pronto a usar (copie e adapte)
Destaque da secção
Abaixo está um modelo inicial de AGENTS.md para um projeto Web típico. Copie-o para a raiz do repositório, substitua `
`, `` e os comandos exatos, e remova as secções de que não precisa. A adaptação demora 20–30 minutos — ou mais, se for a primeira vez.
Destaque da secção
Um bom AGENTS.md segue cinco regras: comandos em vez de ideias, proibições com alternativas, exatamente uma fonte de verdade, critérios de conclusão verificáveis e menos de 150 linhas.
1. **Comandos em vez de ideias.** Um agente não entende «tenha cuidado com as migrações». Vai seguir `alembic check` antes de `alembic upgrade head`. Os agentes trabalham com comandos e condições, não com estados de espírito. Formule todas as regras fundamentais como «faça X, caso contrário Y».
2. **Proibições com uma alternativa.** Um simples «não faça force push» é silenciosamente ignorado pelo agente ao fim de dois ou três pedidos. A combinação «não faça X; faça Y em vez disso» funciona. Exemplo: «Não use `git push --force` em main; se precisar de reverter, use `git revert` ou abra um PR novo.»
3. **Exatamente uma fonte de verdade.** O AGENTS.md da raiz é a fonte de verdade para todo o projeto. Se tiver um monorepo, use ficheiros AGENTS.md aninhados nas subpastas, segundo a regra «prevalece o mais próximo». Não tenha ficheiros paralelos com instruções em conflito.
4. **Critérios verificáveis para considerar algo «concluído».** «Os testes têm de passar» não serve para nada. Um critério exato é: `npm test` devolve o código de saída 0 e não imprime `FAIL` em stdout. «O código deve estar limpo» também não serve para nada. Um critério exato é: `npm run lint` termina sem avisos. Um agente só compreende o que significa «concluído» quando a condição é descrita explicitamente.
5. **Um ficheiro com menos de 150 linhas.** Acima das 150 linhas, as métricas começam a deteriorar-se: o agente gasta mais contexto a ler e não deteta regras importantes. Se não couber, mova os detalhes para `docs/architecture.md` e ligue-o a partir de AGENTS.md, deixando no ficheiro apenas comandos e limites.
## Que 10 erros transformam AGENTS.md em lixo?
Destaque da secção
A principal razão para AGENTS.md não funcionar é a formulação vaga. Num estudo de mais de 2 500 repositórios, o GitHub Blog mostrou que a maioria dos ficheiros falha por estar escrita de forma demasiado genérica. Por exemplo, «És um assistente de programação útil» não dá absolutamente nenhuma informação útil ao agente. Seguem-se 10 erros típicos e a forma como aparecem em ficheiros maus: duplicar o README, texto sem estrutura, mais de 30 proibições sem alternativas, prioridades em conflito, segredos escritos diretamente, documentação desatualizada e complexidade arquitetural excessiva para tarefas simples.
1. **Regras vagas sem comandos.** O agente vai ignorar «tenha cuidado com as migrações» — para ele, essa frase é vazia. Só funciona um comando específico com uma condição: «Execute `alembic check` antes de `alembic upgrade head`. Se houver um erro, não aplique a migração; pergunte-me.»
2. **«Código limpo.»** Uma frase inútil. Substitua-a por um padrão específico: «Use componentes funcionais com hooks. Exemplo: `function LoginForm() { const [email, setEmail] = useState(''); ... }`»
3. **Texto sem estrutura.** Se AGENTS.md tiver 300 linhas de prosa sem títulos, o agente gastará 80K tokens de contexto em passagens irrelevantes e não verá o que importa. Use títulos H2/H3, secções curtas e listas com marcadores.
4. **Um ficheiro com mais de 150 linhas.** As métricas de qualidade pioram depois deste limite. Divida o conteúdo entre um ficheiro principal e ligações para os detalhes em `docs/`.
5. **Mais de 30 proibições sem alternativas.** Se o ficheiro tiver uma longa lista de «não faça X, não faça Y» sem explicar «faça Z em vez disso», o agente andará às cegas.
6. **Duplicar README.md.** Se já escreveu «como instalar e executar» no README, não copie isso para AGENTS.md. Em vez disso, remeta para o README numa linha e descreva em AGENTS.md aquilo de que o agente precisa, mas quem contribui como pessoa não.
7. **Segredos escritos diretamente.** AGENTS.md pode ser público (está no Git). Não inclua chaves de API, tokens ou palavras-passe reais. Inclua apenas referências a repositórios de segredos: «Consulte o Vault: `secret/staging/db`.»
8. **Prioridades em conflito sem hierarquia.** «Avance depressa» + «mantenha 90% de cobertura de testes» deixa o agente sem saber o que escolher. Indique a ordem explicitamente: «Cobertura de testes ≥80% em primeiro lugar, depois a rapidez. Em caso de conflito, os testes têm prioridade.»
9. **Documentação desatualizada.** A descrição da arquitetura diz REST + polling quando, na realidade, já se usam WebSockets. O agente segue a descrição desatualizada e danifica a arquitetura. Regra: atualize AGENTS.md no mesmo PR que o código sempre que a arquitetura mudar.
10. **Complexidade arquitetural excessiva para uma tarefa simples.** Se alguém pedir a alteração de duas linhas numa configuração, o agente não deve ter de ler toda a topologia de 14 microsserviços. Mova a arquitetura «aprofundada» para `docs/architecture.md`; em AGENTS.md, deixe apenas «se a tarefa for arquitetural, consulte `docs/architecture.md`».
[O estudo do GitHub Blog sobre mais de 2 500 repositórios AGENTS.md](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/) apresenta a conclusão principal:
> «A maioria dos ficheiros para agentes falha por ser demasiado genérica. “És um assistente de programação útil” não funciona.»
>
> ([GitHub Blog](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/), traduzido do inglês)
## Como manter AGENTS.md e CLAUDE.md no mesmo repositório?
Destaque da secção
Há três cenários: (1) só Claude Code — mantenha CLAUDE.md; AGENTS.md não é necessário. (2) apenas ferramentas que não sejam Claude (Codex, Cursor, Copilot, Junie) — use AGENTS.md como fonte única de verdade. (3) equipa mista com Claude Code e outras ferramentas — torne AGENTS.md o ficheiro principal. Se não tiver regras separadas para o Claude, pode dispensar CLAUDE.md: desde a versão 2.1.277, o Claude Code lê AGENTS.md por si só. Se tiver regras separadas, ligue AGENTS.md a CLAUDE.md através de uma ligação simbólica ou da importação `@AGENTS.md`. No macOS e Linux, mude o nome só se AGENTS.md não existir. Se ambos existirem, preserve e combine primeiro as regras e use um CLAUDE.md curto com `@AGENTS.md`; nunca sobreponha o AGENTS.md existente. No Windows, as ligações simbólicas exigem o Developer Mode, por isso é mais simples usar uma importação.
A principal questão prática é como manter ambos os ficheiros sem duplicar conteúdo. Há três cenários:
**Cenário 1: só Claude Code.** Mantenha CLAUDE.md e use todas as funcionalidades do Claude Code: `~/.claude/CLAUDE.md` para instruções ao nível do utilizador, `CLAUDE.md` para o projeto, `CLAUDE.local.md` para substituições pessoais, `@import` para incluir outros ficheiros e `.claude/skills/` para competências especializadas. AGENTS.md não é necessário.
**Cenário 2: vários clientes de programação.** Mantenha as regras comuns em AGENTS.md e ligue e verifique cada cliente separadamente. O Gemini CLI permite configurar o nome do ficheiro de contexto; o Aider pode carregar um ficheiro pela configuração de leitura. São formas explícitas de carregamento, não uma descoberta automática idêntica.
| Forma de carregamento | O que verificar |
|----|----|
| Descoberta automática de AGENTS.md | As regras documentadas da versão instalada para a raiz, ficheiros aninhados e precedência |
| Configuração explícita, como no Gemini CLI ou Aider | O nome ou caminho de leitura configurado e a vista de contexto carregado do cliente |
| Carregamento condicional ou importação no Claude Code | A versão instalada e os ficheiros que têm precedência; consulte o [guia específico de AGENTS.md no Claude Code](https://ailoot.ai/blog/pt-pt/claude-code-agents-md-support/) |
Inicie uma sessão nova num repositório de teste inofensivo, adicione uma instrução única e inofensiva, como «inclua o marcador instructions-loaded na resposta de teste», e consulte a vista de ficheiros carregados ou os registos documentados do cliente, além da resposta. Repita para cada cliente e versão que utiliza. Uma afirmação gerada de que o ficheiro foi lido não é prova independente de carregamento; um teste bem-sucedido não demonstra suporte em todas as outras ferramentas.
**Cenário 3: equipa mista (Claude Code + outras ferramentas).** Em 2026, esta é a configuração mais comum. A solução é tornar AGENTS.md o ficheiro principal. Se não tiver regras apenas para Claude Code, não crie CLAUDE.md: desde a versão 2.1.277, o Claude Code lê AGENTS.md quando não existe CLAUDE.md no projeto. Se tiver essas regras, faça de CLAUDE.md uma ligação simbólica ou um wrapper curto com uma importação `@AGENTS.md`.
Antes de alterar qualquer ficheiro, inspecione e copie ambos. Se existirem os dois, reúna as instruções comuns sem conflito em AGENTS.md e mantenha as específicas Claude em CLAUDE.md com `@AGENTS.md`. Preserve ligações simbólicas existentes.
Para um CLAUDE.md normal **só quando AGENTS.md estiver ausente**, esta proteção macOS/Linux recusa sobrepor um destino ou ligação existente:
```bash
if [ -e AGENTS.md ] || [ -L AGENTS.md ]; then
printf '%s\n' 'STOP: AGENTS.md exists; merge both files first.' >&2
elif [ -f CLAUDE.md ] && [ ! -L CLAUDE.md ]; then
mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md
else
printf '%s\n' 'STOP: inspect the existing CLAUDE.md path first.' >&2
fi
```
Depois de mudar o nome com sucesso, CLAUDE.md é uma ligação simbólica para AGENTS.md.
No Windows, criar uma ligação simbólica exige o Developer Mode (ou privilégios de administrador), o que pode não ser prático para toda a equipa. Uma alternativa é um CLAUDE.md curto que importa AGENTS.md:
```markdown
# CLAUDE.md
@AGENTS.md
## Claude Code specific
- Use .claude/skills/ for specialized prompts
- When working with Skills, consult .claude/skills/INDEX.md
- Use Plan Mode before major changes (Shift+Tab)
```
No Claude Code, esta sintaxe inclui AGENTS.md através de uma linha e acrescenta depois instruções específicas do Claude Code. Se mais tarde quiser remover AGENTS.md, basta eliminar a importação. Esta linha não faz com que o ficheiro seja lido duas vezes: de acordo com a documentação do Claude Code, o mesmo AGENTS.md não é carregado duas vezes, mesmo que possa ser lido automaticamente.
Estrutura canónica para uma equipa que usa várias ferramentas em 2026:
```
repo-root/
├── AGENTS.md # fonte de verdade, ≤150 linhas
├── CLAUDE.md # apenas se existirem regras específicas do Claude: ligação simbólica → AGENTS.md OU @AGENTS.md + extras
├── .cursor/rules/ # substituições específicas apenas para o Cursor
├── .github/copilot-instructions.md # «Consulte AGENTS.md», se usado
└── docs/architecture.md # arquitetura detalhada referenciada por AGENTS.md
```
Há mais informação sobre CLAUDE.md no guia [«Como configurar CLAUDE.md corretamente»](https://ailoot.ai/blog/pt-pt/claude-md-template/). Para saber mais sobre porque um agente precisa de um ficheiro de instruções extenso, leia [«O que é engenharia de contexto»](https://ailoot.ai/blog/pt-pt/context-engineering/).
## O que mudou em 2026: porque é que a AAIF integrou AGENTS.md na Linux Foundation?
Destaque da secção
A 9 de dezembro de 2025, a Linux Foundation criou a Agentic AI Foundation (AAIF) com três projetos fundadores: AGENTS.md da OpenAI, MCP da Anthropic e goose da Block. Os membros fundadores eram AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft e OpenAI. A 24 de fevereiro de 2026, a fundação incluía 146 organizações. Isto significa que AGENTS.md deixou de ser «uma coisa da OpenAI» e se tornou um padrão da indústria, a par do MCP. Na prática, se estiver a desenvolver um produto que deve funcionar com agentes de diferentes fornecedores, ter AGENTS.md na raiz é uma regra básica. Sem ele, terá de manter três ou quatro ficheiros paralelos que divergem ao fim de um mês.
A principal história política de maio de 2026 na programação com IA não foi o lançamento de outro modelo, mas a consolidação dos formatos. Anteriormente, cada fornecedor tinha o seu próprio ficheiro de regras, o que era conveniente para os fornecedores, mas penoso para as equipas que trabalhavam com várias ferramentas.
Num [comunicado de imprensa de 9 de dezembro de 2025](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation), a Linux Foundation anunciou a Agentic AI Foundation como estrutura abrangente para três formatos:
- **AGENTS.md** da OpenAI — um formato de ficheiro de instruções para agentes
- **Model Context Protocol (MCP)** da Anthropic — um protocolo para ligar ferramentas externas a agentes
- **goose** da Block — uma framework de agentes de código aberto
Do comunicado de imprensa da Linux Foundation:
> «Reunir estes projetos sob a égide da AAIF garante que podem desenvolver-se com a transparência e a estabilidade que só uma governação aberta proporciona.»
>
> ([comunicado de imprensa da Linux Foundation, 9 de dezembro de 2025](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation), traduzido do inglês)
A 24 de fevereiro de 2026, [146 organizações pertenciam à AAIF](https://www.linuxfoundation.org/press/agentic-ai-foundation-welcomes-97-new-members) (97 novos membros em dois meses). Entre os novos membros Gold estavam Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, Hitachi, UiPath, American Express e Autodesk. A Anthropic está no nível Platinum, promovendo o MCP. A OpenAI está no nível Platinum, promovendo AGENTS.md. A Block está no nível Platinum com o goose.
Isto altera a posição de AGENTS.md: de «formato da OpenAI» para padrão da indústria. Na primavera de 2026, o Claude Code ainda estava à margem, mas em setembro, com a versão 2.1.277, aprendeu a ler AGENTS.md por si só. CLAUDE.md não desapareceu e, por predefinição, continua a ter precedência quando existe no projeto.
Um ponto de partida prático é guardar as regras comuns do projeto em AGENTS.md e acrescentar a importação, o ficheiro de ligação ou a configuração explícita de leitura necessária em cada cliente utilizado. No Claude Code, verifique a versão instalada e a precedência dos ficheiros de instruções antes de decidir se precisa de uma importação em CLAUDE.md ou de uma ligação simbólica. Verifique o carregamento em cada cliente; este guia não estabelece uma percentagem de cobertura.
## E agora?
AGENTS.md é o primeiro elemento fundamental de «como chegar a acordo com um agente para que trabalhe de forma previsível». A seguir vem o segundo elemento: uma pasta de conhecimento do projeto, que contém o contexto empresarial, o público, os produtos e os preços. O terceiro elemento é a [engenharia de contexto](https://ailoot.ai/blog/pt-pt/context-engineering/), que reúne tudo: que ficheiros o agente vê em cada passo, como o estado é preservado entre sessões e como alternar entre diferentes modelos.
Materiais práticos: [documentação Ailoot](https://ailoot.ai/docs/).
### Fontes
- [agents.md — site oficial do padrão](https://agents.md)
- [Linux Foundation: criação da Agentic AI Foundation (9 de dezembro de 2025)](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation)
- [A AAIF dá as boas-vindas a 97 novos membros (24 de fevereiro de 2026)](https://www.linuxfoundation.org/press/agentic-ai-foundation-welcomes-97-new-members)
- [OpenAI cofundadora da Agentic AI Foundation](https://openai.com/index/agentic-ai-foundation/)
- [GitHub Changelog: o agente de programação do Copilot suporta AGENTS.md (28 de agosto de 2025)](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/)
- [GitHub Blog: lições de mais de 2500 repositórios AGENTS.md](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/)
- [Documentação do Claude Code: como o Claude lê AGENTS.md](https://code.claude.com/docs/en/memory#agents-md)
- [Documentação das diretrizes do JetBrains Junie](https://junie.jetbrains.com/docs/guidelines-and-memory.html)
- [Cursor Rules Docs](https://cursor.com/docs/rules)
Mais materiais e ferramentas: [Ailoot](https://ailoot.ai/).
## Perguntas frequentes
### E se AGENTS.md e CLAUDE.md já existirem?
Copie e compare os dois antes de alterar. Reúna regras comuns em AGENTS.md, mantenha as específicas Claude em CLAUDE.md e adicione @AGENTS.md; não mude o nome de um sobre o outro.
### Como torno verificáveis as instruções?
Escreva comandos exatos de configuração e testes, defina o resultado esperado e o que não pode mudar. Transfira arquitetura detalhada para documentação ligada para manter as instruções principais fáceis de ler.
## Ailoot · A empresa e a sua carteira de projetos
A Ailoot assenta numa experiência operacional consolidada, numa ampla base de clientes, num serviço estável e no acompanhamento contínuo dos KPI.
A empresa e a sua carteira de projetos: milhões de clientes; vendas mensais na ordem dos milhares de milhões.
A Ailoot aplica essa experiência operacional ao acesso por API a funcionalidades de IA nos produtos dos clientes, agentes, aplicações e automatizações.