AGENTS.md

What it is and who is behind it

A README is written for people. AGENTS.md is a separate, predictable place for the instructions an AI coding agent needs: which commands install dependencies, how to run the tests, what code style to follow, and what not to touch. It is plain Markdown with no required fields or schema.

The format came out of collaboration between teams at OpenAI (Codex), Amp, Google (Jules), Cursor and Factory, and is now stewarded by the Agentic AI Foundation under the Linux Foundation. The site reports more than 60,000 open-source projects using it, and the specification repository on GitHub had about 24,500 stars as of September 2026.

What to put in the file

The site suggests sections along these lines, and you only need the ones that apply:

• A short project overview
• Setup, build and test commands, written exactly as they should be run
• Code style rules (formatter, lint settings, naming conventions)
• Testing instructions, including how to run a single test
• Security considerations and files that must not be edited
• Commit message and pull request conventions
• Deployment notes

Agents will try to run the test commands you list, so make sure they work on a clean checkout.

How it works in a monorepo

You can place additional AGENTS.md files in subdirectories. An agent reads the nearest file in the directory tree, so a package-level file overrides the root one for work inside that package. OpenAI's own main repository uses dozens of these nested files. This lets a frontend package and a backend service each describe their own commands without one giant file.

Writing one that actually helps

• Start with the commands. The biggest win is an agent running the right test command instead of guessing.
• Be specific and short. "Use pnpm, not npm" beats a paragraph about package managers.
• Record the traps: generated files, slow tests to skip locally, environment variables needed.
• Treat it as living documentation and update it when an agent makes the same mistake twice.
• If a tool you use expects its own file (Claude Code reads CLAUDE.md, for example), check whether it can also read AGENTS.md or point one file at the other rather than maintaining two copies.

Why it matters for students and junior engineers

Writing a good AGENTS.md is the same skill as writing good onboarding docs: knowing what a newcomer needs to be productive. Adding one to your portfolio projects makes them easier for agents and people to work on, and shows reviewers that you think about the developer experience of your code.

Common questions

Is there a required format? No. It is standard Markdown with no required fields. Use whatever headings make sense for your project.

Do I still need a README? Yes. The README is for people; AGENTS.md holds the extra detail agents need, which would clutter a README.

What if two files conflict? The file closest to the code being edited wins, and an explicit instruction from the user in the chat overrides both.

Should I commit it? Yes. It belongs in version control so every contributor, human or agent, gets the same instructions.

Best for: anyone using AI coding agents on a real repository, from a solo side project to a large monorepo.