What is AGENTS.md?
Engineering culture and software practice
AGENTS.md is a convention in which a software project keeps a plain-text file named AGENTS.md at the top of its code repository, giving AI coding agents the instructions a human contributor would get on their first day: how to build and test the software, what conventions to follow, and what not to touch. It was released by OpenAI in August 2025, adopted across many tools within months, and placed under the Linux Foundation's Agentic AI Foundation in December 2025.
What this means
AGENTS.md is a note to the machine. When an AI coding agent starts work on a project, it has none of the tribal knowledge a new human colleague would pick up: how to run the tests, which folder does what, which parts are fragile. AGENTS.md writes that down in one predictable place so the agent can read it before it starts.
The name is literal. It is a file called AGENTS.md, sitting at the root of the code, written in plain text. Think of it as the README that projects have long kept for human readers, but aimed at AI agents instead.
The value is that it turns knowledge that used to live in people's heads into a maintained, reviewable document. Because it is a file in the repository, it is versioned, it shows up in reviews, and anyone, including an auditor or a new member of staff, can read what the agents have been told.
Why it matters
If you have ever wondered why an AI agent keeps making the same mistake in your codebase, the usual reason is that nobody told it the rule. AGENTS.md is where that rule goes. Writing the instruction once, in the open, is more reliable than correcting the agent in conversation over and over.
For governance, the openness is the point. The instructions given to automated tools become visible artefacts: versioned, reviewed and diffable like any other code. That is a real improvement over instructions buried in individual chat sessions, because an auditor or a new hire can see exactly what the agents are guided to do.
There is a business lesson beyond code. The same idea applies to any repeated AI-assisted work: a written brief that every run starts from, kept current and reviewed, beats re-explaining the task each time. AGENTS.md is a concrete example of instructions as a maintained asset.
As of September 2026 it is worth being clear-eyed. AGENTS.md is a convention, not an enforced standard, its instructions are advice a model may or may not follow, and independent research on whether such files actually improve results is mixed.
How it works
Where the term came from
The convention grew out of OpenAI's coding agent, Codex, which needed a predictable place to find project-specific instructions. OpenAI released AGENTS.md in August 2025 as a lightweight file designed to sit alongside the README. A near-identical predecessor, a singular AGENT.md proposed by the Amp team in May 2025, was folded into the plural AGENTS.md convention, and the shared home at the agents.md website consolidated it. Within months it was read by coding agents from many different companies. The Linux Foundation reports the format adopted by more than 60,000 open-source projects and agent frameworks, including Amp, Codex, Cursor, Devin, Factory, Gemini CLI, GitHub Copilot, Jules and VS Code.
On 9 December 2025 the Linux Foundation announced the Agentic AI Foundation, a neutral governance body, and OpenAI donated AGENTS.md to it, alongside the Model Context Protocol contributed by Anthropic and the goose framework contributed by Block. That move matters because a convention whose whole value depends on many rival tools honouring it the same way is safer under neutral stewardship than under one company's control. Verify the current stewardship on the foundation's own site; as of the date this article was checked it sits with the Agentic AI Foundation under the Linux Foundation.
Related conventions predate it: the README file that explains a project to humans, editor configuration files that set formatting, and the older idea of a contributing guide for new collaborators. AGENTS.md is that family of ideas pointed at AI agents.
What the file contains, and what it must not
A useful AGENTS.md tells an agent the things you would tell a new teammate: how to build and test the software, the conventions to follow, the commands that matter, and the parts of the codebase to leave alone, ideally with the reason why. It should stay tight; sprawling files are less reliably followed. Crucially, it must not contain secrets such as passwords or keys, because it is a visible, shared file, and it must not contain workarounds that defeat security controls. It is guidance, not a vault.
Ownership and review
Because it is code, it should be owned and reviewed like code. Someone is responsible for keeping it accurate; changes go through the normal review process; and it is version-controlled so its history is visible. This is what distinguishes a living instruction file from a stale one that quietly misleads every agent that reads it.
The security angle
An instruction file is an attack surface. If an untrusted contributor can edit AGENTS.md, they can attempt to steer agents toward unsafe behaviour, so changes to it should be reviewed with the same care as changes to code, and edit rights should be controlled. Described defensively, the lesson is simple: treat the file as trusted only to the extent that its edit history is trusted. This is a recognised concern in public guidance on the secure use of AI coding agents.
The limits
AGENTS.md is a convention, not a guarantee. Support varies between tools, the instructions are advice a model may ignore rather than rules it must obey, and independent studies through 2026 have reached mixed conclusions on whether such files improve results, with some finding efficiency gains and others finding little or negative effect. It is a useful habit, not a control you can rely on.
Examples
A software team of eight keeps finding that its AI agent formats code the wrong way and edits a fragile module it should leave alone. They add an AGENTS.md that states the formatting rule and marks the module as off-limits, with a short reason. The repeated mistakes largely stop, and the instruction is now visible to every new starter as well as every agent.
A retailer's small in-house team is preparing for an audit of how it uses AI tools. Because their agent instructions live in AGENTS.md under version control, they can show the auditor exactly what the agents were told and when it changed, rather than trying to reconstruct guidance from scattered chat logs. The openness turns a governance headache into a document they can hand over.
A charity with no engineers borrows the idea for non-code work. They keep a short written brief that every AI-assisted task starts from: the tone to use, the facts that must be right, the things never to claim. It is not an AGENTS.md file, but it is the same principle, one maintained, reviewable instruction that every run begins with.
Common misunderstandings
The first misunderstanding is that AGENTS.md is the same as a system prompt. It is not. A system prompt is instruction given to a model at the session level; AGENTS.md is a repository-level file, versioned and reviewed like code, that persists across sessions and tools. Unlike a system prompt, its whole point is to be an open, maintained artefact in the project rather than a setting inside one conversation.
The second is that it is an enforced standard. It is a convention. Tools choose whether and how to read it, and the instructions are advice, not rules a model is guaranteed to obey.
The third is that more detail is always better. Overloaded files are followed less reliably, and some research suggests bloated instructions can even hurt. A tight file beats an exhaustive one.
The fourth is that it is a safe place for configuration such as keys. It is not. It is a visible, shared file, so secrets must never go in it, and it must not encode workarounds for security controls.
The fifth is that once written it looks after itself. Like any documentation, it rots. A stale AGENTS.md misleads every agent that reads it, so it needs an owner and regular review.
Risks and boundaries
This is a recent convention, released in 2025, and its usage and governance are still settling as of September 2026; this article was written in that month. Stewardship moved to the Agentic AI Foundation under the Linux Foundation in December 2025, and anyone relying on it should confirm the current position on the foundation's own site.
The main boundaries are these. AGENTS.md is not a security control; it is guidance a model may or may not follow, and it becomes a risk if untrusted people can edit it. It is not a standard with guaranteed support; adoption and behaviour vary by tool. And the evidence that it improves results is genuinely mixed, so it should be treated as a sensible habit that also needs testing and review, not as a setting that makes AI agents reliable on its own. The folklore that a good instruction file tames an agent outruns what the research currently shows.
What to do next
If your teams use AI coding agents, ask whether the instructions those agents follow are written down in the open and version-controlled, or scattered across private chats. The former is auditable; the latter is not.
Set two firm rules for any such file: no secrets in it, and no instructions that work around security controls. Review changes to it as carefully as you review code, and control who can edit it.
Give it an owner and a review cadence, so it stays accurate as the project changes. Treat a neglected instruction file as a liability, because a confident but wrong instruction is worse than none.
Borrow the idea beyond code. For any repeated AI-assisted work, keep a single maintained brief that every run starts from, reviewed and current, rather than re-explaining the task each time.
FAQs
What is AGENTS.md in plain terms?
A plain-text file at the top of a code project that tells AI coding agents how to build and test it, what conventions to follow and what to leave alone.
Who created it and when?
OpenAI released it in August 2025, growing it out of its Codex coding agent. It was adopted across many tools within months.
Who governs it now?
In December 2025 it was placed under the Agentic AI Foundation, a neutral body under the Linux Foundation. Confirm the current position on the foundation's own site.
How is it different from a system prompt?
A system prompt is session-level instruction to a model. AGENTS.md is a repository file, versioned and reviewed like code, that persists across sessions and tools.
Should we put configuration or keys in it?
No. It is a visible, shared file, so secrets must never go in it, and it must not contain workarounds for security controls.
Does AGENTS.md guarantee the agent behaves?
No. It is a convention offering advice a model may ignore, tool support varies, and research on whether it improves results is mixed.
Can we use the idea for non-code work?
Yes. Keep one maintained brief that every AI-assisted task starts from. It is the same principle applied outside a code repository.