Konstantin Semenenko
July 6, 2026
4
minutes read
AGENTS.md is a file in your repository that tells AI coding agents how to work in that specific codebase: its rules, conventions, architecture, and verification steps. Think of it as a README written for the agent instead of the human. An agent reads it before editing code, so instead of guessing your conventions, it follows them. When a mistake recurs, you write the fix into AGENTS.md and no agent repeats it, which is how a codebase teaches the agents that work in it.
AGENTS.md is a plain-text file that lives in your repository and tells AI coding agents the rules of your codebase: how it is structured, what conventions to follow, how to run and test changes, and what "done" means. It is a README aimed at the agent rather than the human. The reason it matters is simple: an agent with no rules invents its own, and an agent that reads AGENTS.md before editing follows yours instead. That single difference is what separates an agent that fits your codebase from one that fights it.
We build with AI agents on every project, and AGENTS.md is the mechanism that makes their output predictable. This explains what goes in the file, why agents follow it, and how it turns a codebase into something that teaches every agent that touches it.
AGENTS.md is a governance file: a Markdown document at the root of a repo that an AI coding agent reads before it changes anything. It carries the context an agent needs to work correctly in that specific project, the architecture, the coding rules, the testing approach, the maintainability limits, and the workflow for non-trivial tasks. Where a README explains the project to a new human engineer, AGENTS.md explains it to a new agent, in the detail an agent needs to not go wrong.
The format is deliberately simple, because it has to be read and followed by a machine on every task. It is not configuration or code. It is instructions, written plainly, that define how work happens in this repository. An agent loads it, and its behavior is now shaped by your rules instead of its defaults.
An AI agent generates the most statistically probable code for a request, which by definition is the generic answer, not the answer your codebase wants. Without a rule that says "we use vertical-slice architecture" or "integration tests decide what ships," the agent has no reason to know either, so it does the average thing and you get output that looks fine and violates every convention you hold. AGENTS.md removes the guessing by stating the rules explicitly, so the agent has something concrete to follow instead of a prior to fall back on.
This is why the file is read before every edit, not once at setup. An agent has no persistent memory of your project between tasks, so the rules have to be present in context each time it works. Loading AGENTS.md at the start of each task is what makes the rules apply every time rather than sometimes. The file is the agent's working memory of how your codebase does things.
The contents vary by project, but the useful ones cluster into a few categories. In our framework a typical AGENTS.md carries:
The point of writing these down is that a rule in the file is a rule the agent applies. A rule in your head is a rule the agent breaks.
A single file works for a single project, but real solutions have many. AGENTS.md handles this with precedence: a root AGENTS.md governs the whole solution, and multi-project solutions add local AGENTS.md files at project roots that refine the root rules for their part of the system. An agent reads the root file and the relevant local file before editing, so it gets both the solution-wide rules and the project-specific ones.
This layering matters because a monorepo with one flat rulebook either drowns every project in irrelevant rules or waters the rules down to uselessness. Root plus local keeps the global rules global and lets each project tighten what it needs, so the agent working in one service follows that service's specifics without losing the rules that apply everywhere.
The most valuable thing AGENTS.md enables is durable learning. In most agent workflows the same mistake recurs forever, because nothing captures the correction. With AGENTS.md, the discipline is that if a mistake happens twice, the rule goes into the file, so no agent makes it a third time. Each correction becomes a permanent part of how the codebase is worked, not a note that gets lost when the session ends.
Over time this turns the repo into a teacher. Every agent that touches the codebase reads the accumulated rules, which means the project gets more reliable to work in as it ages, instead of less. That is the opposite of the usual pattern, where institutional knowledge lives in a few people's heads and evaporates when they leave. In AGENTS.md, the knowledge lives in the repo and applies to everyone, human or agent.
AGENTS.md is one of three things that make AI agents reliable, alongside repo-native context and verification that actually gates what ships. On its own, a rules file is necessary but not sufficient: rules without enforcement are suggestions, which is why AGENTS.md pairs with tests and quality gates that make the rules real. We wrote about how those pieces fit together in inside MCAF, the framework where AGENTS.md is the instruction layer.
The takeaway for anyone building with agents: if your AI-generated code keeps violating your conventions, the missing piece is usually that the conventions were never written where the agent could read them. AGENTS.md is where they go.
What is AGENTS.md? A Markdown file in a repository that tells AI coding agents the rules, conventions, architecture, and verification steps of that codebase. Agents read it before editing code, so they follow your project's rules instead of generic defaults.
How is AGENTS.md different from a README? A README explains a project to a human engineer. AGENTS.md explains it to an AI agent, in the detail an agent needs to work correctly, architecture rules, coding standards, maintainability limits, and how to verify a change is done.
Do AI agents actually read AGENTS.md? Yes. In a framework that uses it, agents read the root and any relevant local AGENTS.md before editing code, on every task, because an agent has no memory of the project between sessions, so the rules must be in context each time.
What should go in AGENTS.md? Architecture rules, coding standards, numeric maintainability limits, verification rules (which tests and gates decide what ships), and the workflow for non-trivial tasks. Anything an agent needs to work correctly in the repo belongs there.
How does AGENTS.md help agents improve over time? When the same mistake recurs, you write the fix into AGENTS.md so no agent repeats it. Each correction becomes a durable rule, so the codebase gets more reliable to work in as its rulebook grows.
If you want AI agents building on your codebase with rules they actually follow, setting up that governance is part of how our AI Dev Team work ships production code.
