AGENTS.md em 2026: o que é e como criar o seu ficheiro em 30 minutos

Materiais práticos sobre vibe coding e trabalho com agentes: documentação Ailoot.

AGENTS.md num parágrafo#

A seguir, o formato é analisado com base em agents.md, na documentação do OpenAI Codex, JetBrains Junie, Cursor Rules Docs, no registo de alterações do GitHub Copilot Coding Agent e no comunicado de imprensa da Linux Foundation sobre a 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, 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». 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?#

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 como formato aberto. No site:

«Pense em AGENTS.md como um README para agentes.»

(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, traduzido do inglês)

Em setembro de 2025, o GitHub Copilot Coding Agent já suportava o formato (registo de alterações, 28.08.2025). 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): 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, 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?#

Tabela de suporte a 30 de maio de 2026; a linha do Claude Code foi atualizada a 24 de setembro de 2026:

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, funciona assim:

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?#

Comparação dos quatro formatos a 30 de maio de 2026:

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, traduzido do inglês)

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?#

O site 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)#

# AGENTS.md

## Project overview

<project-name> - <one phrase describing its purpose>.
Stack: <Next.js / Python / Go / ...>.
Main entities: <users, orders, posts ...>.
Details for people are in README.md.

## Setup commands

```bash
# first install
npm install
cp .env.example .env  # then fill in manually; see list below

# run
npm run dev           # dev server on :3000
npm run build         # production build
npm run start         # run production build
```

## Dev environment

- Node 20+ (via nvm: `nvm use 20`)
- PostgreSQL 16 locally on :5432 (`docker-compose up postgres`)
- Redis is optional, needed only for queues (`docker-compose up redis`)
- `.env`: `DATABASE_URL`, `STRIPE_KEY`, `RESEND_API_KEY`, `JWT_SECRET`
- Never read the entire `.env` file. If you need one variable: `grep "^VAR=" .env`

## Code style

- TypeScript strict mode
- Single quotes, no semicolons (unless ESLint requires them)
- Imports: external first, then internal via `@/`, then relative
- Components in PascalCase; hooks start with `use`
- No `any` without an explicit comment explaining “why it can’t be typed”

Example of a good module:

```ts
import { z } from 'zod'

const UserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
})

export function parseUser(raw: unknown) {
  return UserSchema.parse(raw)
}
```

## Testing

```bash
npm test                                # all tests
npm test -- --testPathPattern=auth      # auth only
npm test -- --watch                     # watch mode
```

All tests must pass (be green) before committing. If a test is red, don’t commit; ask me what to do.

## Pull request guidelines

- Commit format: `<type>(<scope>): <description>` (`feat(auth): add magic-link`)
- Before PR: `npm run build && npm test && npm run lint`
- PR description = what changes, why, and how to test
- Don’t approve your own PR—always wait for human review

## Security

- Secrets only in `.env` and Vault, never in code
- Don’t log personal data (email, phone, name)
- When working with the production DB, use read-only queries only unless explicitly authorized
- Don’t hardcode external service API keys (Stripe, OpenAI) in tests

## Never do this

- Don’t `git push --force` to main. If you need to roll back, use `git revert` or open a new PR
- Don’t run DB migrations without `alembic check` (or the equivalent in your ORM)
- Don’t use `npm install -g` or `sudo` for project dependencies
- Don’t add dependencies without approval (especially heavy ones: webpack plugins, ORM)

Em média, o modelo tem 80–120 linhas. Se o ficheiro ultrapassar 150 linhas, é sinal de que deve ser refatorizado: mova alguma coisa para docs/, ligue a outra informação ou condense-a numa linha. Na prática, os ficheiros com 100–150 linhas funcionam melhor; depois desse ponto, os ganhos de qualidade começam a inverter-se.

Que 5 regras tornam AGENTS.md verdadeiramente útil?#

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?#

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 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, traduzido do inglês)

Como manter AGENTS.md e CLAUDE.md no mesmo repositório?#

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.

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:

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:

# 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». Para saber mais sobre porque um agente precisa de um ficheiro de instruções extenso, leia «O que é engenharia de contexto».

O que mudou em 2026: porque é que a AAIF integrou AGENTS.md na Linux Foundation?#

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, 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, traduzido do inglês)

A 24 de fevereiro de 2026, 146 organizações pertenciam à AAIF (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, 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.

Mais materiais e ferramentas: Ailoot.