CLAUDE.md e AGENTS.md: dar contexto ao agente

Na padaria, a dona deixa um papel colado na porta do armário para quem vem ajudar ao sábado: «O forno grande demora 40 minutos a aquecer. As encomendas estão na prateleira de cima. Nunca mexer na caixa registadora.» Quem chega lê o papel e começa a trabalhar sem perguntar tudo outra vez.

O agente é o ajudante de sábado. Não contes que se lembre, de uma sessão para a outra, de que a página é em português europeu, nem de que o horário não se mexe sem ordem tua. Ou repetes tudo em cada sessão, ou deixas um papel na porta.

O conceito: um bilhete que o agente lê ao entrar

O bilhete é um ficheiro de texto na pasta do projecto. Por omissão, o agente lê-o sozinho no início de cada sessão. Deve responder a três perguntas:

• O que é este projecto e quais são os ficheiros principais.
• Como se verifica que ficou bem.
• O que nunca se faz.

O Claude Code procura um ficheiro chamado CLAUDE.md. O Codex procura um chamado AGENTS.md. A ideia é a mesma, muda só o nome. O .md quer dizer Markdown: texto simples, em que # marca um título e - marca um ponto de uma lista.

Um exemplo completo

# Página da Padaria do Largo

## O que é
Site de uma página: horário, pão do dia e contactos.
Ficheiros: index.html (conteúdo) e estilo.css (aspecto).

## Como verificar
- Depois de cada mudança, mostra o diff e diz-me o que devo ver no browser.
- A página tem de continuar legível numa janela estreita, como a de um telemóvel.

## Regras
- Escreve sempre em português europeu.
- Não mudes o horário nem os preços sem eu pedir.
- Nunca leias nem mostres o ficheiro .env.
- Antes de mudar qualquer ficheiro, mostra-me o plano e espera pela minha resposta.

O que pôr e o que não pôr

Põe:

• o que é o projecto, em duas ou três frases;
• os ficheiros principais e para que serve cada um;
• como se verifica que está bem;
• regras concretas que se possam verificar.

Não ponhas:

• segredos (chaves, palavras-passe, tokens). O ficheiro entra no Git e vai para o fornecedor em cada sessão;
• textos longos. Uma página de história da padaria gasta espaço e esconde as regras que importam;
• coisas que mudam todos os dias, como a lista de tarefas da semana;
• o que o agente descobre sozinho a ler os ficheiros.

Como se faz hoje: onde ficam os ficheiros

Isto é como está a 6 de Outubro de 2026; se o ecrã for diferente, procura o botão com o mesmo nome. O sinal ~ quer dizer a tua pasta pessoal.

Claude Code (guia oficial: Memória do Claude Code):

• CLAUDE.md na raiz do projecto (ou .claude/CLAUDE.md): as regras do projecto, partilhadas com quem trabalha nele.
• ~/.claude/CLAUDE.md: as tuas preferências pessoais, para todos os projectos.
• CLAUDE.local.md na raiz: notas pessoais só deste projecto. Junta-o ao .gitignore.

Codex (guia oficial: AGENTS.md no Codex):

• AGENTS.md na raiz do repositório: as regras do projecto. Pode haver outros em subpastas, e o mais próximo da pasta onde trabalhas é lido por último.
• ~/.codex/AGENTS.md: as tuas preferências pessoais, para todos os projectos.

As duas ferramentas têm o comando /init, que lê o projecto e escreve um primeiro rascunho do ficheiro. Revê esse rascunho e corta o que não precisas.

As duas ferramentas no mesmo projecto

Se usas as duas, escreve as regras uma só vez no AGENTS.md. Depois cria um CLAUDE.md com esta linha:

@AGENTS.md

A linha @AGENTS.md diz ao Claude Code para importar o outro ficheiro. Por baixo dela podes acrescentar regras só para o Claude. Por omissão, nas versões recentes, o Claude Code lê o AGENTS.md quando não há CLAUDE.md, mas, se houver os dois, lê só o CLAUDE.md. Isto depende da versão e das definições; a importação resolve-o sem depender de nenhuma delas.

Os agentes também conseguem guardar notas próprias entre sessões, a chamada memória automática; isso fica para o Nível 2.