AGENTS.md e HUMAN.md: como usar no projeto

O que é AGENTS.md

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

O motivo para essa convenção existir é prático. Uma pessoa nova na equipe lê o README, tenta adivinhar o comando de build e pergunta a alguém quando a tentativa falha. Um agente não pode perguntar. Ele tenta, executa npm test em um projeto que usa pnpm test, lê a falha e tenta outra coisa. Você paga por cada um desses tokens. Registrar o comando correto uma vez elimina toda essa classe de falhas.

Não há campos obrigatórios. O site deixa isso explícito: "AGENTS.md é apenas Markdown padrão. Use os títulos que quiser; o agente simplesmente analisa o texto fornecido." Essa é toda a especificação. O valor não está no formato. Está no arquivo localizado em um caminho que todas as ferramentas já verificam.

Onde o arquivo fica e qual arquivo prevalece

Coloque o primeiro na raiz do repositório. Em um monorepo, você pode adicionar outros dentro de cada subprojeto. A regra é simples: "os agents leem automaticamente o arquivo mais próximo na árvore de diretórios, portanto o arquivo mais próximo tem precedência." Um conflito entre dois arquivos é resolvido em favor do arquivo que está sendo editado. Tudo o que você digitar no chat substitui os dois.

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 o aninhamento, porque essa é a única forma de declarar algo que é verdadeiro em uma pasta e falso na seguinte. Uma regra como "cada endpoint valida sua entrada" deve ficar ao lado dos endpoints. Em um arquivo na raiz, ela é carregada em todas as tarefas não relacionadas e não traz nenhum benefício.

O que deve constar em um AGENTS.md

Registre o que um agente não consegue descobrir lendo o código. Os comandos exatos de build, teste e lint vêm primeiro, no formato em que seriam colados em um terminal. Inclua o comando para executar um único teste, pois um agente que sabe apenas executar toda a suíte executará toda a suíte quarenta vezes. Descreva as convenções que diferem do padrão da ferramenta, pois o agente já conhece o padrão e precisa saber apenas sobre o seu desvio. Inclua o formato das mensagens de commit e as regras de pull request, se houver.

Seja específico o suficiente para que uma afirmação possa ser verificada. "Use indentação de 2 espaços" é uma instrução útil porque é possível verificar se isso ocorreu. "Formate o código corretamente" não é, porque não há nada verificável nessa instrução. O mesmo vale para locais: "Os handlers da API ficam em src/api/handlers/" é melhor que "mantenha os arquivos organizados".

Regras negativas também merecem espaço. "Nunca edite arquivos em dist/; eles são gerados por npm run build" evita um erro específico. Como a regra informa a causa, o agente consegue deduzir o caso equivalente que não foi documentado.

O que nunca deve estar em um deles

Nunca coloque um segredo em um desses arquivos. O arquivo é versionado no git, carregado no contexto no início de cada sessão e enviado a um provedor de modelos em todas as solicitações. Uma chave de API em um AGENTS.md é uma chave de API no histórico do seu repositório e nos logs de terceiros. Aponte para o segredo em vez de colá-lo: "a senha do banco de dados está em .env, que é ignorado pelo git; peça autorização antes de lê-lo." A disciplina mais ampla é abordada em mantendo credenciais fora do alcance de um agente.

Não inclua nada que o agente possa descobrir observando. Uma listagem de diretório colada, uma cópia da sua lista de dependências ou uma visão geral da arquitetura que apenas repete os nomes das pastas: tudo isso fica desatualizado na semana seguinte à sua criação e, enquanto isso, consome contexto em todas as sessões. Mantenha as armadilhas e os motivos. Remova o inventário.

CLAUDE.md é a implementaçã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 arquivo do 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 arquivo para toda a máquina em /etc/claude-code/CLAUDE.md no Linux. Os arquivos encontrados são concatenados da raiz do sistema de arquivos até o diretório de trabalho. Portanto, o arquivo mais próximo do local em que você iniciou a sessão é lido por último.

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

@AGENTS.md

## Claude Code

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

Um link simbólico funciona quando você não precisa adicionar nada:

ln -s AGENTS.md CLAUDE.md

O comando não exibe nada quando é concluído com sucesso. Na próxima sessão, execute /context e confirme que CLAUDE.md aparece em Arquivos de memória. Se ele não estiver nessa lista, o arquivo nunca foi carregado e nada do seu conteúdo foi aplicado. Para gerar um primeiro rascunho em vez de escrever um arquivo, execute /init: ele lê a base de código e produz um arquivo inicial. Quando já existe um CLAUDE.md, ele sugere melhorias em vez de substituí-lo.

Mantenha cada arquivo com menos de aproximadamente 200 linhas. Arquivos maiores consomem mais espaço da janela de contexto, e a aderência às instruções diminui. Se quiser ver o que mais compete por esse espaço, o que realmente preenche a janela de contexto de um agente explica isso em detalhes.

Um ponto merece destaque. Um AGENTS.md fornece orientações, mas não é um sistema de permissões. O conteúdo chega como contexto comum. O modelo o lê e geralmente o segue, mas nada bloqueia uma ação que o contradiga. Para uma regra que deve ser aplicada sempre, como "nunca faça push para main", use um hook ou uma configuração de permissão, pois esses mecanismos são executados como código e não dependem de o modelo decidir obedecer.

Ferramentas que escrevem esses arquivos para você

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

agent0ai/dox (1,368 stars em July 2026) é um framework para manter atualizada uma árvore de arquivos AGENTS.md. Ele não disponibiliza nenhum pacote nem runtime. Você copia o conteúdo do arquivo AGENTS.md dele para o seu próprio arquivo AGENTS.md na raiz, e essa é a instalação. Para um projeto que já existe, diga ao seu agente:

Initialize DOX tree for this project now.

O agente então cria os arquivos AGENTS.md filhos e seus índices, percorre essa árvore antes de editar qualquer coisa e atualiza a documentação afetada depois que uma alteração é aplicada. A premissa é que a documentação mantida por um agente como consequência do trabalho dele permanece correta, enquanto a documentação atualizada manualmente por uma pessoa não permanece.

HUMAN.md: a mesma técnica aplicada a você

Intuition-Lab/personal-model (1,260 estrelas em julho de 2026) aplica o padrão a uma pessoa, e não a um repositório. O projeto define seu HUMAN.md como o resultado do sistema, e não como um arquivo que você digita: "um modelo vivo do que importa agora, de como você costuma decidir e de para onde sua atenção está se direcionando". Ele é executado localmente no macOS 13 ou posterior, coleta atividades depois que você concede permissão ao macOS e expõe o resultado a agentes por meio do MCP (model context protocol). O caminho curto de instalação é:

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

Você não precisa de nada disso para obter a maior parte do benefício. Um HUMAN.md escrito manualmente tem cerca de vinte linhas: sua função, seu fuso horário, a stack que você realmente usa, as decisões que já tomou e não quer reabrir e o nível de explicação que deseja receber. Ele evita as mesmas explicações repetidas que um arquivo de projeto evita, mas em uma camada acima.

Um cuidado: 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 em um CLAUDE.local.md ignorado pelo git na raiz do projeto. Esse arquivo é carregado junto com o arquivo versionado e recebe o mesmo tratamento.

Um modelo inicial que você pode copiar

Ele é curto de propósito. Exclua as seções que não se aplicam e evite adicionar seções que você 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 a informação e depois corrija-a no próprio arquivo. O sinal para adicionar uma linha é você ter digitado a mesma correção duas vezes no chat. Essa única regra mantém o arquivo útil e impede que ele cresça até se tornar um documento que ninguém lê, nem mesmo as máquinas. Quando estiver estável, ele acompanha o repositório. Isso é mais importante quando o agent é executado em outro lugar que não seja seu laptop: executar um coding agent no seu próprio servidor explica essa configuração.

FAQ

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

Eles representam a mesma ideia em dois nomes de arquivo. O Claude Code lê CLAUDE.md e ignora AGENTS.md, a menos que você os conecte. Mantenha um arquivo como fonte de verdade e vincule o outro a ele, seja com uma linha contendo @AGENTS.md no início do seu CLAUDE.md, seja com ln -s AGENTS.md CLAUDE.md. Duas cópias completas mantidas separadamente ficarão diferentes em menos de um mês.

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

Não. O conteúdo é fornecido como contexto. Portanto, o modelo o lê e geralmente o segue, mas nada impede uma ação que o contradiga. Instruções vagas são seguidas com menos confiabilidade, e dois arquivos com orientações opostas deixam o agente escolher um deles arbitrariamente. Para uma regra que deve ser aplicada sempre, use um hook ou uma regra de permissão. Esses mecanismos são impostos pelo cliente, independentemente da decisão do modelo.

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

Sim, para tudo que for verdadeiro sobre o projeto: comandos de build, estrutura e convenções. Esse é o objetivo do arquivo, pois os agentes dos seus colegas começarão com o mesmo contexto que o seu. Qualquer informação pessoal ou específica de uma máquina deve ficar em um arquivo separado, ignorado pelo git. As credenciais não devem ficar em nenhum dos dois.

O que é HUMAN.md e preciso de um?

HUMAN.md é um perfil legível por máquina de uma pessoa, e não de um projeto. Ele contém sua função, suas restrições e as decisões que você já definiu, para que não sejam reabertas em cada sessão. Você não precisa de nenhuma ferramenta para começar: vinte linhas escritas manualmente no seu arquivo de instruções no nível do usuário fornecem a maior parte do benefício. Trate-o como dado pessoal e não o inclua em nenhum repositório que você publicar.