
What is AGENTS.md?
AGENTS.md is a regular Markdown file, placed at the root of a project (and can be in subdirectories), containing instructions for AI programming agents: what the project does, what commands to run for testing, code conventions, what not to do. The standard agents.md page (read on 03/11/2026) calls this the "README for agents". What makes AGENTS.md worth using is that many tools read the same file: OpenAI's Codex, Cursor, Gemini CLI, GitHub Copilot coding agent, Claude Code and dozens of other tools. This post does not promise that AGENTS.md makes agents always compliant: the file is context, not an enforcement mechanism, and OPCAIOS has no metrics on the level of improvement. The post includes: how Codex loads AGENTS.md by tier, when Claude Code reads it, how Cursor supports it, what to write, a short template, and how OPCAIOS maintains a single source of truth for multiple agents.

AGENTS.md by tier and tools reading it together. Diagram: OPCAIOS.
What standard is AGENTS.md and which tools support it?
AGENTS.md is an open format, not owned by any company. According to the agents.md page (read on 03/11/2026), the format is currently managed by the Agentic AI Foundation under the Linux Foundation, and the page lists over 60,000 open-source projects using it. Tools listed on the page include OpenAI Codex, Google Jules, Gemini CLI, Cursor, GitHub Copilot coding agent, VS Code, JetBrains Junie, Devin, Windsurf, Aider, Zed, Warp and many other tools. The standard has no required fields, no frontmatter needed. The most important rule is when there are multiple nested files, the file closest to the file being edited takes priority, and direct instructions from the user in the chat box override everything. Claude Code is not in the list I read, but Claude Code's own documentation has a section on AGENTS.md (see section below).
In what order does Codex read AGENTS.md?
Codex reads AGENTS.md in two tiers: user tier then project tier, and joins them into a single instruction chain each time it runs. According to the AGENTS.md page in Codex documentation (developers.openai.com redirects to learn.chatgpt.com/docs/agent-configuration/agents-md, read on 03/11/2026), the specific order is:
- User tier: Codex looks in the Codex home directory, default
~/.codexunless you set theCODEX_HOMEvariable. If there isAGENTS.override.mdthen use that file, otherwise useAGENTS.md. At this tier only the first non-empty file is taken. - Project tier: Codex starts at the project root (usually Git root) then descends into each directory down to the current directory.
- One file maximum per directory: in turn try
AGENTS.override.md, thenAGENTS.md, then fallback names declared in config. - Join from top down: files are concatenated from root down, separated by blank lines. Files closer to the current directory come later, so they override general instructions above.
- Empty files are skipped.
The chain is built once each time Codex runs: after editing AGENTS.md you must restart Codex.
When do I use AGENTS.override.md?
AGENTS.override.md is used when you need to completely replace the same-tier file without deleting the original file. Example scenario: the payments directory needs entirely different rules; placing AGENTS.override.md there makes Codex use it instead of AGENTS.md in that location.
What is the size limit and what are fallback file names?
Codex stops adding files when total size reaches project_doc_max_bytes, default 32 KiB according to documentation read on 03/11/2026. The documentation suggests two approaches when exceeded: increase the limit, or split instructions down into subdirectories. If a project already has a guide file with a different name, declare project_doc_fallback_filenames in ~/.codex/config.toml (documentation example: TEAM_GUIDE.md). To find out which files Codex loaded, the documentation suggests asking Codex directly to list the instruction sources. Details on config.toml are in the post Codex's config.toml.
When does Claude Code read AGENTS.md?
Claude Code reads AGENTS.md when the project has no CLAUDE.md. According to Claude Code's "How Claude remembers your project" page (read on 03/11/2026): if the working directory and parent directories only have AGENTS.md, Claude uses AGENTS.md; if both CLAUDE.md or CLAUDE.local.md exist, by default only CLAUDE.md is read; if CLAUDE.md imports AGENTS.md with the line @AGENTS.md, both are loaded. For how to set up CLAUDE.md and import syntax, see the What is CLAUDE.md post.
How does Cursor support AGENTS.md?
Cursor supports AGENTS.md at the project root and in subdirectories. According to the Rules page in Cursor documentation (cursor.com/docs/context/rules, read on 03/11/2026), AGENTS.md is plain Markdown, needs no metadata, and is presented as an alternative to .cursor/rules for simple cases. Files in subdirectories apply automatically when working with files in that directory, are merged with parent directory instructions, and more specific instructions take priority. The documentation does not clearly state whether AGENTS.md ranks above or below rules in .cursor/rules. Markdown files usually placed in .cursor/rules are ignored. OPCAIOS does not use Cursor daily so has not self-verified this behavior; see also What is Cursor.
What should I write in AGENTS.md?
AGENTS.md should contain things the agent cannot guess from code and will need in every session. The agents.md page suggests these groups: project overview, build and test commands, code conventions, how to test, security notes, commit or pull request rules, deployment steps. The priority order we suggest:
- Exact commands: install, test run, build. According to agents.md, the agent will try to run test commands written there and fix errors before finishing work.
- Boundaries: directories, auto-generated files, real data must not be touched.
- Custom conventions: naming, reply language, commit format.
- Session start and end workflow: which files to read first, where to write logs.
- Security: do not write API keys, passwords, server addresses into AGENTS.md because the file is usually committed to the repository. See 5 rules for data security when using AI.
Do not write: descriptions of each file, long documentation for people, vague instructions like "write clean code".
Short AGENTS.md template for solo workers
Below is a template written by OPCAIOS for illustration, not an actual file from any project; replace commands and paths to match your project:
# Guide for agents
## Project
Online course sales site, Next.js + Postgres. Code in src/, migrations in db/.
## Commands
- Install: npm install
- Test run: npm run dev
- Check before finishing work: npm run lint && npm test
## Rules
- Reply in Vietnamese, concise.
- Do not edit files in db/migrations that have run; create a new migration.
- Do not commit .env file or API keys.
- Commit only files you have edited.
## End of session
- Write one line summary to docs/NHAT_KY.md.
Each line is one thing to check.
How do you keep one source of truth for many agents?
One source of truth means common rules are written only in AGENTS.md, while files specific to each tool only point to it and add their own parts. When using Codex, Claude Code, and another agent in parallel on the same repository, a practical approach has four steps:
- Write common rules (commands, boundaries, session workflow) in AGENTS.md at the repository root.
- Create CLAUDE.md with only the line
@AGENTS.mdand a few things specific to Claude Code. - Keep personal habits (language, reply tone) in each tool's user-level file, for example
~/.codex/AGENTS.mdfor Codex. - When editing rules, only edit AGENTS.md, then restart the session.
When two files conflict, it is hard to guess which one the agent follows, so do not copy a rule into many files. When many sessions edit one repository, read also multiple AI sessions editing one project and using Codex and Claude Code at the same time.
OPCAIOS's Experience
I use Codex CLI, the Codex desktop application, Claude Code, and Google Antigravity in parallel on my main workstation; I don't use Cursor daily. My current file organization approach (checked on 03/11/2026):
- One shared AGENTS.md for all agents in the user's home directory and in my Obsidian notes repository: the reading order of documents at session start, writing to the shared status file and daily log at session end, and no leaving junk files.
- One user-level AGENTS.md for Codex in Codex's home directory, equivalent to Claude Code's user-level file: respond in Vietnamese, read documents in order, write daily log at session end.
- Each session commits only its own files, because multiple sessions share one repository and Git index; squash commits easily drag in files from other sessions.
- Some projects are only edited on one specific machine. There's a real reason: once an agent deployed from a Windows machine and left over 1,500 files marked as "changed" just because of different line endings.
What I don't have yet: a measurement of how much better agents follow guidelines when AGENTS.md is present, and I haven't verified how Cursor reads files myself. I still need someone to review the final result; see I let AI agents build and run my website: 10 real lessons.
Frequently Asked Questions
Does AGENTS.md have to be in the project root?
Not required, but the project root is where most tools look first. Codex also reads files in subdirectories along the path from the repository root to the working directory, and user-level files in ~/.codex. Cursor reads from both root and subdirectories. For small projects, one file in root is enough; for multi-area projects, you may need additional files for each area.
How is AGENTS.md different from README.md?
README is written for people: introduction, how to install, how to contribute. AGENTS.md is written for agents: the exact commands to run, boundaries you can't cross, local conventions, details that would clutter README if included. The agents.md page recommends separating the two so README stays clean. You shouldn't copy README wholesale into AGENTS.md, but having a few overlapping lines like install commands is fine.
How long should AGENTS.md be?
Codex by default only reads a total of 32 KiB from the AGENTS.md string, according to documentation read on 03/11/2026; anything beyond that won't be added. Beyond technical limits, the longer the file, the easier important rules get lost. Keep the root file short, each line is something you can verify, and move details for each area down into AGENTS.md files in their subdirectories.
Does using both CLAUDE.md and AGENTS.md cause conflicts?
Possibly, if you copy the same rule into both files and then edit them differently. According to Claude Code documentation, when CLAUDE.md exists, Claude Code by default only reads CLAUDE.md, so rules that are only in AGENTS.md will be missed. Safe approach: put shared rules in AGENTS.md, have CLAUDE.md contain only @AGENTS.md and Claude Code-specific content. Edit in one place, all agents see it.
Should I put API keys or passwords in AGENTS.md?
No. AGENTS.md is typically committed to the repository and loaded into the AI model's context, so anything in it is considered potentially exposed. Write the environment variable name instead of the value, for example "key read from the service's environment variable", and keep the actual value in a .env file outside the repository. If you want guidance on setting up instruction files for multiple agents based on your actual project, see AI Application Training Course from OPCAIOS.
Source: agents.md; Codex documentation, AGENTS.md page (developers.openai.com redirects to learn.chatgpt.com/docs/agent-configuration/agents-md); Claude Code documentation, "How Claude remembers your project" page (code.claude.com/docs/en/memory); Cursor documentation, Rules page (cursor.com/docs/context/rules); read on 03/11/2026. List of supporting tools, the figure of 60,000 projects, and the 32 KiB limit are from those pages and may change with updates; AGENTS.md behavior in Cursor has not been self-verified by OPCAIOS. The experience is OPCAIOS's.
Translated from Vietnamese with AI. Read the original.
Want to apply this in your business?
Book a free 30-minute call (Vietnam time, in English or Vietnamese).
