AGENTS.md: how to guide agents in the repository

The file AGENTS.md solves part of that problem. It stores instructions the agent should read in the project context, such as test commands, architecture patterns, security limits and review criteria.

In this article you will see:

• What to put in a AGENTS.md and what to leave out.
• How to organize global, project and folder specific rules.
• How to validate if the agent actually loaded the instructions.
• How to combine the file with human review and multiple agents.

O que é AGENTS.md e quando usar

AGENTS.md is a guidance file for programming agents. Codex documentation describes a chain of global and project specific instructions, read before work starts. GitHub also documents the file as a way to give repository context to Copilot during a review.

Use the file to record decisions the agent must always respect. Examples: how to install dependencies, which tests to run, where the important modules live, which files must not be changed and which checks are mandatory before opening a pull request.

Do not turn the file into a copy of the README. The README explains the project to people. AGENTS.md should answer what an agent needs to know to act safely and deliver a reviewable change.

Crie o arquivo na raiz do repositório

Start at the Git root, so the guidance applies to the whole project. In the integrated terminal of VS Code, confirm the current directory and create the file:

$ git rev-parse --show-toplevel
$ touch AGENTS.md
$ code AGENTS.md

In PowerShell, the equivalent creation is:

PS> git rev-parse --show-toplevel
PS> New-Item AGENTS.md -ItemType File
PS> code AGENTS.md

Use a short and operational structure. An initial example can be:

# Regras do repositório

## Antes de editar
* Leia o README e os arquivos de configuração do pacote.
* Explique o plano antes de alterar mais de um módulo.

## Testes
* Rode o lint depois de mudar JavaScript ou TypeScript.
* Rode a suíte relacionada antes de abrir o pull request.

## Limites
* Não altere segredos, arquivos de produção ou migrações sem explicar o impacto.
* Não adicione dependências sem justificar a necessidade.

Replace the examples with the real commands from your project. A vague rule, like "write good code", hardly helps. An observable rule, like "run pnpm test --filter api when you change services/api", gives the agent an action that can be checked.

Organize camadas sem criar conflitos

Current Codex documentation allows combining global instructions with project files and more specific rules in subfolders. A file close to the directory where the agent works can complement or replace a general guidance.

Use the root for rules shared by the whole team. Place service instructions in a AGENTS.md inside that folder. When you need a temporary override, use AGENTS.override.md and remove the file after the task.

Avoid duplicating the same rule in five places. Duplication creates contradictions and makes it hard to discover which instruction won. Prefer this order:

• security and quality rules at the root;
• domain rules inside the service;
• local exceptions only when they are really necessary.

Codex also documents a size limit for the instruction set. If the file gets too large, split the content by directory and remove explanations that do not change an agent decision.

Diferencie AGENTS.md, CLAUDE.md e regras do editor

Not every agent reads the same file names. Codex and GitHub Copilot document AGENTS.md; Claude Code documents CLAUDE.md for memory and project instructions. This does not mean one file automatically replaces the other.

If your team uses different tools, keep a short source of common rules and make small adaptations for each tool. Do not copy huge instructions without checking the documented behavior of each agent.

The most important rule is to declare what was actually verified. If a tool does not recognize AGENTS.md, say so in its specific file. A similar name is not proof of compatibility.

Validate loading before trusting the file

After saving the file, open a new agent session. Sessions already open may have loaded old instructions, so restarting avoids a false positive.

Ask the agent to list the instruction sources it found. In Codex, the documentation itself uses a summary request to confirm that the global file was loaded:

$ codex --ask-for-approval never "Resuma as instruções carregadas antes de propor qualquer mudança."

Then compare the response with the actual file content. If a rule does not appear, check the folder where the command was run, the exact file name and if there is a AGENTS.override.md changing the order.

Also do a practical validation. Ask for a task that requires a test command and check if the agent mentions it in the plan. The file being present in Git does not guarantee the agent read the correct content.

Combine instructions with review and squads

AGENTS.md reduces repeated context, but does not replace branch, diff, test or human review. Use the file to explain the pattern and use Git to prove what changed.

If you are still building this flow, see the guide to AI agents for programming with review. For a larger project, the article on building a system with AI using Codex helps break deliveries into smaller parts.

When multiple agents work on the same project, the file can serve as a common contract. One agent plans, another implements and another reviews, each with the same set of limits. In bridgecode, this division makes sense when you want to track different roles in parallel, keeping the final decision with a person.

Frequently asked questions about AGENTS.md

Does the file need to contain all team rules?

No. Put only guidelines that change agent decisions, verifiable commands, security limits and review criteria. Extensive documentation should stay in its own files.