AGENTS.md e HUMAN.md: o que são e como usar

O que é AGENTS.md

AGENTS.md é um ficheiro Markdown simples na raiz de um repositório. Indica a um agente de programação como trabalhar nesse projeto. O site oficial descreve-o como "um README para agentes: um local dedicado e previsível para fornecer o contexto e as instruções que ajudam os agentes de programação com IA a trabalhar no seu projeto". O formato é mantido pela Agentic AI Foundation, sob a Linux Foundation, e mais de vinte agentes leem este ficheiro, incluindo Codex, Cursor, Jules, Devin e GitHub Copilot (em julho de 2026).

A convenção existe por uma razão prática. Uma pessoa nova na equipa lê o README, tenta adivinhar o comando de compilação e pergunta a alguém quando a suposição está errada. Um agente não pode perguntar. Ele tenta, executa npm test num projeto que usa pnpm test, lê o erro e tenta outra coisa. Cada um desses tokens tem um custo. Registar o comando correto uma vez elimina toda essa classe de falhas.

Não existem campos obrigatórios. O site é explícito: "AGENTS.md é apenas Markdown padrão. Use os cabeçalhos que quiser; o agente limita-se a analisar o texto que fornecer." Essa é toda a especificação. O valor não está no formato. Está no ficheiro existir num caminho que todas as ferramentas já consultam.

Onde o ficheiro fica e qual ficheiro prevalece

Coloque o primeiro na raiz do repositório. Num monorepo, pode adicionar mais ficheiros dentro de cada subprojeto, e a regra é simples: "os agentes leem automaticamente o ficheiro mais próximo na árvore de diretórios, por isso o mais próximo tem precedência." Um conflito entre dois ficheiros é resolvido a favor do ficheiro que está a ser editado, e tudo o que escrever no chat substitui ambos.

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

Vale a pena usar esta estrutura aninhada, porque é a única forma de indicar algo que é verdadeiro numa pasta e falso na seguinte. Uma regra como "cada endpoint valida os seus dados de entrada" deve ficar junto dos endpoints. Num ficheiro na raiz, essa regra é carregada em todas as tarefas não relacionadas e não traz qualquer benefício. Se o seu ficheiro na raiz já tiver uma secção por serviço, dividi-lo numa estrutura aninhada é a solução. Essa estrutura também indica quais regras descem para os níveis inferiores e quais permanecem no topo.

O que deve constar num AGENTS.md

Registe aquilo que um agente não consegue descobrir ao ler o código. Os comandos exatos para compilar, testar e executar o lint vêm primeiro, no formato em que seriam colados num terminal. Inclua o comando para executar um único teste, porque um agente que só sabe executar toda a suite vai executar a suite quarenta vezes. Indique as convenções que diferem das predefinições das ferramentas, porque o agente já conhece a predefinição e só precisa de saber qual é a sua alteração. Inclua o formato das mensagens de commit e as regras dos pull requests, se existirem.

Seja suficientemente concreto para que uma afirmação possa ser verificada. "Use indentação de 2 espaços" é uma instrução utilizável, porque aconteceu ou não aconteceu. "Formate o código corretamente" não é, porque não há nada nessa instrução que possa ser verificado. O mesmo se aplica às localizações: "Os handlers da API estão em src/api/handlers/" é melhor do que "mantenha os ficheiros organizados".

As regras negativas também justificam o espaço que ocupam. "Nunca edite ficheiros em dist/, porque são gerados por npm run build" evita um erro específico. Como indica a causa, o agente consegue deduzir o caso equivalente que não foi descrito. Uma regra sobre o âmbito também pertence aqui, porque um agente deixado ao seu próprio critério reescreve mais do que foi pedido: uma skill amplamente copiada não faz mais do que insistir na menor alteração que funciona.

O que nunca deve estar num deles

Nunca coloque um segredo num destes ficheiros. O ficheiro é guardado no git, carregado no contexto no início de cada sessão e enviado a um fornecedor de modelos em todos os pedidos. Uma chave de API num AGENTS.md fica no histórico do seu repositório e nos logs de terceiros. Aponte para o segredo em vez de o colar: "a palavra-passe da base de dados está em .env, que está no gitignore; peça autorização antes de a ler." A disciplina mais ampla é abordada em manter as credenciais fora do alcance de um agente.

Não inclua nada que o agente possa obter ao consultar os ficheiros. Uma listagem de diretórios colada, uma cópia da lista de dependências ou uma descrição da arquitetura que repita os nomes das pastas: tudo fica desatualizado na semana seguinte à sua escrita e, entretanto, consome contexto em todas as sessões. Mantenha as armadilhas e as razões. Elimine o inventário. Vale a pena separar as razões, porque um agente que não consiga ver por que motivo existe uma estrutura invulgar irá refatorá-la silenciosamente. É esse o motivo para manter um DESIGN.md junto deste ficheiro.

CLAUDE.md é a versão do Claude Code para a mesma ideia

O Claude Code lê CLAUDE.md e não lê AGENTS.md por conta própria. Um ficheiro de projeto fica em ./CLAUDE.md ou ./.claude/CLAUDE.md, as preferências pessoais para todos os projetos ficam em ~/.claude/CLAUDE.md, e uma organização pode distribuir um ficheiro para toda a máquina em /etc/claude-code/CLAUDE.md no Linux. Os ficheiros descobertos são concatenados desde a raiz do sistema de ficheiros até ao diretório de trabalho, por isso o ficheiro mais próximo do local onde iniciou a sessão é lido por último. Todas as sessões iniciadas nesse diretório carregam a mesma sequência, o que permite executar duas em paralelo na mesma máquina, e essas sessões podem passar trabalho umas às outras enquanto estão em execução.

Se o seu repositório já tiver um AGENTS.md, não mantenha uma segunda cópia. Importe-o e adicione apenas o que for específico do Claude:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Uma ligação simbólica é suficiente quando não tem nada adicional para acrescentar:

ln -s AGENTS.md CLAUDE.md

O comando não apresenta qualquer saída quando termina com sucesso. Na sessão seguinte, execute /context e confirme que CLAUDE.md aparece em Ficheiros de memória. Se não aparecer nessa lista, o ficheiro nunca foi carregado e nada do que contém foi aplicado. Para gerar uma primeira versão em vez de escrever uma, execute /init: o comando lê a base de código e produz um ficheiro inicial. Quando já existe um CLAUDE.md, sugere melhorias em vez de o substituir.

Mantenha cada ficheiro com cerca de 200 linhas ou menos. Ficheiros maiores consomem mais espaço da janela e reduzem a adesão às instruções. Se quiser ver o que mais concorre por esse espaço, o que realmente ocupa a janela de contexto de um agente explica os detalhes.

Um ponto merece destaque. Um AGENTS.md contém orientações, não é um sistema de permissões. O conteúdo chega como contexto normal. O modelo lê-o e normalmente segue-o, mas nada impede uma ação que o contradiga. Quando uma regra que escreveu é ignorada silenciosamente e não consegue perceber porquê, analise as razões pelas quais uma instrução é descartada antes de reescrever o texto pela terceira vez. Para uma regra que tenha de ser cumprida sempre, como "nunca faça push para main", use um hook ou uma definição de permissões. Esses mecanismos executam código e não dependem de o modelo decidir obedecer.

Ferramentas que criam estes ficheiros por si

Dois projetos que estavam na lista de tendências do GitHub em 30 July 2026 mostram a direção desta convenção.

agent0ai/dox (1,368 stars em July 2026) é uma framework para manter atualizada uma árvore de ficheiros AGENTS.md. Não fornece nenhum pacote nem runtime. Copia o conteúdo do seu AGENTS.md para o seu próprio AGENTS.md raiz, e essa é a instalação. Num projeto já existente, diga ao seu agente:

Initialize DOX tree for this project now.

Em seguida, o agente cria os ficheiros AGENTS.md secundários e os respetivos índices, percorre essa árvore antes de editar qualquer ficheiro e atualiza a documentação afetada depois de aplicar uma alteração. A premissa é que a documentação mantida por um agente como consequência do seu trabalho continua correta, enquanto a documentação atualizada manualmente por uma pessoa não.

HUMAN.md, o mesmo princípio aplicado a si

Intuition-Lab/personal-model (1,260 estrelas em julho de 2026) aplica o padrão a uma pessoa em vez de a um repositório. O projeto apresenta o seu HUMAN.md como o resultado do sistema, e não como um ficheiro que escreve: "um modelo vivo do que importa agora, de como tende a tomar decisões e de para onde a sua atenção se está a direcionar". É executado localmente no macOS 13 ou posterior, recolhe atividade depois de autorizar o macOS e disponibiliza o resultado a agentes através de MCP (model context protocol). O processo curto de instalação:

uv tool install personal-model
persome onboard
persome model open --after 30

Não precisa de nada disso para obter a maior parte do benefício. Um HUMAN.md escrito manualmente tem cerca de vinte linhas: a sua função, o seu fuso horário, a stack que realmente usa, as decisões que já tomou e não quer reabrir e a quantidade de explicações que quer receber. Evita as mesmas explicações repetidas que um ficheiro de projeto evita, mas num nível superior.

Há uma ressalva. Um HUMAN.md é um perfil de uma pessoa, portanto é sensível por definição. Mantenha-o fora de um repositório público. Coloque-o em ~/.claude/CLAUDE.md ou num CLAUDE.local.md ignorado pelo git na raiz do projeto. Esse ficheiro é carregado juntamente com o ficheiro versionado e é tratado da mesma forma.

Um modelo inicial que pode copiar

Este modelo é curto de propósito. Elimine as secções que não se aplicam e evite adicionar secções que não consiga manter atualizadas.

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

Escreva o texto e corrija-o no próprio ficheiro. O sinal para adicionar uma linha é ter introduzido a mesma correção duas vezes no chat. Esta regra mantém o ficheiro útil e impede que cresça até se tornar um documento que ninguém lê, incluindo as máquinas. Quando estiver estável, o ficheiro acompanha o repositório. Isto é especialmente importante quando o agente é executado noutro local que não o seu portátil: executar um agente de programação no seu próprio servidor explica essa configuração.

FAQ

AGENTS.md é o mesmo ficheiro que CLAUDE.md?

São a mesma ideia em dois nomes de ficheiro. O Claude Code lê CLAUDE.md e ignora AGENTS.md, a menos que os associe. Mantenha um único ficheiro como fonte de verdade e faça uma ligação do outro para ele, com uma linha que contenha @AGENTS.md no início do seu CLAUDE.md ou com ln -s AGENTS.md CLAUDE.md. Duas cópias completas mantidas separadamente terão diferenças dentro de um mês.

Escrever um AGENTS.md garante que o agente o seguirá?

Não. O conteúdo é fornecido como contexto, por isso o modelo lê-o e, em geral, cumpre-o, mas nada impede uma ação que o contradiga. As instruções vagas são seguidas com menos fiabilidade, e dois ficheiros com orientações opostas deixam o agente escolher um deles arbitrariamente. Para uma regra que tem de ser respeitada sempre, use um hook ou uma regra de permissões. O cliente aplica-os independentemente da decisão do modelo.

O AGENTS.md deve ser incluído no git?

Sim, quando contém informações verdadeiras sobre o projeto: comandos de build, estrutura e convenções. Essa é a finalidade do ficheiro, porque os agentes dos seus colegas começam então com o mesmo contexto que o seu. Informações pessoais ou específicas de uma máquina devem ficar num ficheiro separado, ignorado pelo git. As credenciais não devem ficar em nenhum dos dois.

O que é o HUMAN.md e preciso de um?

O HUMAN.md é um perfil legível por máquina sobre uma pessoa, e não sobre um projeto. Contém a sua função, as suas restrições e as decisões já tomadas, para que não sejam reabertas em cada sessão. Não precisa de ferramentas para começar: vinte linhas escritas manualmente no seu ficheiro de instruções ao nível do utilizador fornecem a maior parte do valor. Trate-o como dados pessoais e mantenha-o fora de qualquer repositório que publique.