Como escrever um ficheiro AGENTS.md para agentes de programação
Escreva um AGENTS.md curto com comandos de instalação e de testes, regras e limites, faça com que o Claude Code e o Gemini CLI o carreguem e teste-o com uma tarefa pequena.
Um ficheiro AGENTS.md é um ficheiro Markdown simples na raiz do repositório que diz aos agentes de programação como trabalhar no projeto: que comandos executar, onde está o código e em que não devem mexer. Não tem secções obrigatórias. Mantenha-o curto, torne cada regra verificável e confirme que cada agente o carrega.
Este guia explica o que incluir, dá um modelo, mostra como o Claude Code e o Gemini CLI encontram o ficheiro e propõe um teste rápido. Os mesmos passos aplicam-se quando inicia agentes a partir do telemóvel com o Mono da Reunified.
1. Decida o que pôr no ficheiro
O site agents.md descreve-o como um README para agentes. Inclua os factos de que todas as sessões precisam e deixe de fora tudo o que o agente consegue perceber pelo código.
| Ponha no AGENTS.md | Deixe de fora |
|---|---|
| Comandos de instalação, testes e lint | Palavras-passe, chaves de API e tokens |
| Onde está o código principal | Uma árvore de ficheiros completa ou a lista de dependências |
| Convenções que diferem das predefinições | Procedimentos longos (em vez disso, ponha uma ligação para um documento) |
| Ficheiros que nunca devem ser editados, ações que exigem perguntar primeiro | Preferências pessoais (use o ficheiro ao nível do utilizador do seu agente) |
Num monorepo, pode acrescentar um AGENTS.md dentro de cada pacote. O ficheiro mais próximo tem prioridade, e uma instrução direta na conversa sobrepõe-se a ele.
2. Comece por um modelo curto
Eis um exemplo fictício para o «tidy-recipes», uma aplicação web em TypeScript que usa pnpm:
# AGENTS.md
## Overview
TypeScript web app for saving recipes. Components live in src/components.
## Setup
- `pnpm install`
## Test and lint
- `pnpm test` and `pnpm lint`
## Code style
- TypeScript only. One component per file.
## Boundaries
- Never edit db/migrations/.
- Ask before adding a dependency.
## Before you finish
- Run `pnpm test` and `pnpm lint`.
- List the files you changed and the test results.Indique apenas comandos que já executou neste repositório. Se um estiver errado, o agente confia nele na mesma.
3. Escreva regras verificáveis para o agente
Uma boa regra permite-lhe verificar depois se o agente a seguiu.
| Vaga | Concreta |
|---|---|
| Testar as alterações | Executar pnpm test e pnpm lint antes de terminar |
| Manter os ficheiros organizados | Os componentes ficam em src/components |
| Ter cuidado com a base de dados | Nunca editar db/migrations/ |
| Resumir o trabalho | Listar os ficheiros alterados e os resultados dos testes |
Escreva os limites como regras de «nunca» e de «perguntar primeiro», uma por linha.
4. Faça com que o Claude Code e o Gemini CLI o leiam
O site agents.md lista o Codex, o Gemini CLI, o opencode e outros agentes compatíveis com o formato, mas nalguns é preciso mudar primeiro uma definição.
Por predefinição, as versões recentes do Claude Code só leem o AGENTS.md quando não existe nenhum CLAUDE.md, .claude/CLAUDE.md ou CLAUDE.local.md no diretório de trabalho ou acima dele (consulte a documentação sobre memória). Se tem um desses ficheiros ou uma versão mais antiga, importe o AGENTS.md a partir do CLAUDE.md. O projeto tidy-recipes tem um CLAUDE.md antigo, por isso acrescente esta linha no topo e mantenha por baixo as notas que só servem para o Claude:
@AGENTS.md
Prefer small commits.Comece uma sessão nova, execute /context e confirme que o CLAUDE.md aparece nos ficheiros de memória («Memory files»). Se não houver CLAUDE.md, /memory mostra em vez disso o caminho do AGENTS.md.
O Gemini CLI lê o GEMINI.md por predefinição. Para acrescentar o AGENTS.md, ponha isto no .gemini/settings.json do projeto (consulte a documentação do GEMINI.md):
{
"context": {
"fileName": ["AGENTS.md", "GEMINI.md"]
}
}Comece uma sessão nova e execute /memory show para ver o que foi carregado. Para outros agentes, consulte a respetiva documentação.
5. Teste o ficheiro com uma tarefa pequena
Numa sessão nova, dê ao agente esta tarefa:
Primeiro, lista as regras do projeto que carregaste e o ficheiro de onde vem cada uma. Depois, muda o texto do botão «Save recipe» para «Save» em src/components/SaveButton.tsx. Não alteres mais nada.
Compare o resultado com o ficheiro:
- Indicou o AGENTS.md (ou o CLAUDE.md com a importação).
- Executou
pnpm testepnpm linte comunicou os resultados. - Não mexeu em db/migrations/ nem acrescentou nenhuma dependência.
- Listou os ficheiros que alterou.
Confirme a edição por si com git diff (consulte como rever alterações de código feitas por IA). Se o agente não conseguir indicar uma regra, o ficheiro provavelmente não foi carregado, por isso volte ao passo 4. Se indicou uma regra e não a cumpriu, torne-a mais concreta.
6. Mantenha-o curto e atualizado
A documentação do Claude Code sugere manter o CLAUDE.md abaixo das 200 linhas, porque os ficheiros mais longos ocupam mais contexto e são seguidos com menos fiabilidade. Faça o mesmo com o AGENTS.md. O guia da janela de contexto explica o que acontece quando o contexto fica cheio.
Atualize o ficheiro quando um agente repetir um erro, e apague comandos desatualizados e regras contraditórias. Faça commit do ficheiro e reveja as alterações que lhe fizerem como reveria código.
O ficheiro orienta o agente, mas não impõe nada. Para bloquear uma ação, use as definições de permissões do agente ou recuse o pedido (consulte o guia de permissões de ferramentas).
No Mono, o agente arranca no diretório de trabalho do projeto no seu computador, onde procura estes ficheiros. Pode abrir o AGENTS.md, o CLAUDE.md ou o .gemini/settings.json no editor do Mono, também a partir do telemóvel, e as edições guardam-se sozinhas. Para criar o ficheiro, peça ao agente ou abra um terminal a partir do cartão do projeto. O Mono não verifica o ficheiro nem muda qual deles o agente carrega. O Mono ainda não está disponível, mas pode inscrever-se na lista de espera.
