The idea

You ask a coding tool to fix a failing test. It can see the task, but it may not know where this project keeps production code, which check is appropriate, or which files must not be edited. Repeating those details in every prompt is tedious and inconsistent.

An AGENTS.md file is a Markdown file in a project that gives a coding agent local working guidance. In the documented Codex workflow, it can contain navigation notes, coding conventions, and commands for running or testing code. OpenAI describes AGENTS.md as a project-near instruction file for these kinds of details.

Think of it as a written working agreement for an agent, not as a specification of what the software must do. It can make recurring project knowledge available in a visible, version-controlled place. Your prompt still states the goal of the current task.

Plain English: AGENTS.md is a short file that tells a coding agent, “Here is how this project is organized and checked.” It does not replace telling the agent what you want changed.

For Codex, an AGENTS.md file applies to the directory tree below the directory where it lives. Codex looks for these files from the recognized project root to the current working directory and assembles the instructions in that order. A file in a deeper folder can provide more specific guidance for that folder. This discovery and assembly behavior is documented in the official Codex repository.

There is an important ordering rule. More specific, deeper AGENTS.md guidance wins when AGENTS.md files conflict. But direct system, developer, and user instructions have higher instruction precedence than AGENTS.md. The official Codex prompt documents both parts of this order. So a project file is durable guidance, not an unbreakable policy.

A small example

Example — hypothetical repository layout. A team has a repository with src/ for production code and docs/ for generated documentation. They add this small file at the repository root:

# Project guidance

- Put production code in `src/`.
- Run `npm test` after changing application code.
- Do not edit generated files in `docs/`.

This is not an official required template. It illustrates the documented kinds of content: code organization, conventions, and commands to run or test. Codex documentation names these as appropriate AGENTS.md information.

Now imagine src/payments/ has unusual test setup. That folder could contain another AGENTS.md with one narrow instruction, such as which payment test command to use. In Codex, that deeper file can override a conflicting root rule for its own subtree. Keep the root file about repository-wide facts; put exceptions close to the code they describe.

Try it

Take five minutes and make a draft AGENTS.md for one repository. Do not try to document everything.

  1. Write one structural fact that you have verified, such as the location of application code.
  2. Add one command that you actually use to test or check the relevant area.
  3. Add one boundary, such as a generated directory that should not be edited.
  4. Read each line and remove anything that is vague, obsolete, or only relevant to a rare task.

Then use a concrete prompt alongside it: “Fix the failing validation test in src/ and report which test you ran.” This combines durable local context with a clear immediate task. It also gives you a simple way to check whether the file helps: inspect the changes and run the stated checks yourself.

Watch out

Do not treat AGENTS.md as proof that generated code is correct or safe. OpenAI advises human validation of generated code; review the diff, test output, and any side effects. OpenAI’s Codex introduction makes that need explicit.

Avoid turning the file into a long handbook. OpenAI recommends reviewing AGENTS.md regularly and removing stale or unnecessary guidance because it is considered during repository work and overly long instructions consume context. OpenAI Developers explains this maintenance concern.

Finally, this lesson describes documented Codex behavior, not a universal standard for all AI coding tools. Check each tool’s documentation before assuming it reads AGENTS.md or applies the same hierarchy.