AGENTS.md: How to Write, Structure and Maintain It for Coding Agents
AGENTS.md is the file coding agents read before they touch your code, and it is now supported by most major tools. This guide covers everything about it in one place: what it is, how to structure it, how nested files work across directories, what business rules and coding standards to include, and how to prune and improve it over time.
Drop a capable coding agent into your repository and it can write excellent code, yet it has no idea how your particular project works: your build command, your test runner, your conventions or the parts of the codebase it should never touch. An agents.md file fixes that with a plain markdown briefing. Below you will find what the file is, what to put in it, how tools like Cursor use it, and how it compares to claude.md, gemini.md and Cursor rules, the formats it has largely replaced as the standard.
Table of Contents
What an agents.md file is
An agents.md file is a markdown document placed in your repository that explains the project to any coding agent working in it. It typically lists how to build and test the code, the conventions to follow, the frameworks in use, key architectural decisions and anything else an agent needs to be effective.
When an agent starts working, it reads this file and loads that guidance into its context. It is essentially a briefing document written for an AI collaborator rather than a human one. Simple in form, it carries a lot of weight across a whole project.
Why coding agents need it
A model only knows what is in its input context, and it cannot infer your team’s private conventions from the code alone. Left to guess, it uses the wrong build command, invents a testing style you do not use, or edits files that are off limits. That guessing is where the frustration of inconsistent results comes from. It is the difference between an agent that fits your project and one that fights it.
The agents.md file removes the guesswork by stating the rules up front, so the agent starts informed instead of improvising. Without it, you re-explain your project in every prompt and the agent still forgets between sessions. With it, the essential context is loaded automatically from the first step, which is why practical guides like the one on how to build an AGENTS.md treat it as foundational.
What to put inside an agents.md file
A good agents.md is concrete and practical. Name the exact commands to build, test and lint, so the agent runs the right ones rather than plausible guesses. State conventions such as how to handle errors, how to structure new code, and what to escape or validate.
Flag the landmines too: directories never to edit, generated files the agent should leave alone, and secrets it must never commit. Each line saves the agent from a mistake it would otherwise make on your specific codebase. The best entries are the ones that prevent a specific mistake you have already seen. Write down what you keep having to correct.
Keep it short and high-signal
Because the file loads on every request, its length is a recurring cost against the agent’s context window. A bloated agents.md crowds out room for the actual task and buries its own important lines, so lean beats comprehensive. Every line should earn its place by changing what the agent does, the same reason focused context matters throughout context engineering for coding agents.
How Cursor uses agents.md for vibe coding
Vibe coding in Cursor works well until the agent starts using the wrong patterns, running the wrong commands, or ignoring conventions you never told it about. The fix is not more careful prompting on every request but a file that briefs the agent once. Cursor’s agent cannot read your mind or your team’s unwritten rules. Cursor’s agent reads the relevant project files as part of its context on each task, so the guidance in your agents.md shapes how it writes code, which commands it runs and what it avoids, without you pasting conventions into every prompt.
Set it once, and it works on every request. That automatic loading is what makes the guidance reliable, and it fits the way an agent already works inside your editor or terminal. For anyone doing real work with vibe coding, the result is fewer corrections and more first-try successes.
Consistent results and a file that lives with the code
One underrated benefit is consistency. When the rules live in a shared file, every agent run and every team member gets the same guidance, so behavior stops depending on who is driving or how a prompt happened to be phrased. That turns agent work from a gamble into something predictable, and the file becomes a shared contract for how the project is worked on.
Because it is just a file in the repository, an agents.md travels with the project. It goes through version control, gets reviewed in pull requests and changes as conventions change, so the guidance stays current instead of being trapped in someone’s personal prompt or memory.
Treat it as a living file. When you notice the agent repeating a mistake, add a rule against it, and when conventions change, update it. Over time it accumulates the hard-won lessons of your project, and each correction you encode is a mistake you never have to fix again.
claude.md, gemini.md and Cursor rules: the same idea under different names
The concept was popularized under a vendor-specific name before it became a standard. Anthropic’s Claude Code introduced claude.md as a place to hand the agent durable project context, and it caught on fast because it so obviously worked. Its success proved that a simple markdown briefing dramatically improves agent behavior.
Success bred imitation, and imitation bred fragmentation. Google leaned toward gemini.md, Cursor had its rules files, and other tools added their own variants. They all did the same job in incompatible ways, so a team using several tools ended up maintaining claude.md, a Cursor rules file and more, all describing the same project and all able to drift out of sync. The differences were in naming and which tool reads which file, not in purpose.
How agents.md became the open standard
The resolution came through a shared specification rather than one vendor winning. The AGENTS.md standard was formalized as an open specification in 2025, led by OpenAI with participation from Google, Cursor and others, and later donated to a neutral foundation. By late 2025 tens of thousands of open-source projects had adopted it and dozens of tools supported reading it, so one file can now brief many different agents.
When rival companies collaborate on a format, as they did through the Agentic AI Foundation, they are treating it as shared infrastructure rather than a competitive edge. An open specification, neutral governance, broad tool support and a large base of projects are what make a standard de facto rather than merely proposed.
When an industry moves from many competing formats to one shared standard, that convergence is a stronger signal than any single product announcement, and following it is a reliable way to cut through the hype.
Moving from vendor files to agents.md
You do not have to abandon the older files overnight. Many tools still read their own format, and some read both their native file and agents.md, so the transition can be gradual. A common bridge is to keep a single source of truth in agents.md and point the vendor-specific file at it, which avoids duplicate content without breaking tools that have not caught up.
For a new project, start with agents.md as your primary context file. It is the format most likely to be read by the tools you use now and the ones you adopt later, which protects your effort from tool churn.
Content matters more than the file name
The format is a container, and the value is in the context you put inside it. A great claude.md beats an empty agents.md every time. Whichever file you use, the real work is context engineering: choosing the high-signal guidance an agent needs, which pays off far more than tweaking individual prompts. A short, accurate file takes minutes to write and pays for itself the first time an agent uses the right test command without being told.
How to Structure an agents.md File for Claude Code, Cursor and GitHub Copilot
An agents.md file gives a coding agent the project context it needs, but a badly structured one gets skimmed or misread. This guide shows how to structure the file so Claude Code, Cursor and GitHub Copilot actually follow it: what to put first, how to write commands and conventions, and what a full-stack project needs on top, from per-half rules to the API contract and a build order.
Keep the file short and lead with essentials
Brevity is the most important structural rule. A long file dilutes the important instructions and eats the context window, so a focused page of what actually matters beats an exhaustive manual, which ties into why less context often works better. If a detail is obvious from the code or rarely relevant, leave it out.
Order matters too. Put the build and test commands, the language and framework, and the hard constraints at the top, where the agent is most likely to weight them. A critical rule buried at the bottom risks being missed. Front-loading your non-negotiables is a simple way to raise compliance, and short is not lazy, it is what makes the file effective.
Describe the stack and project structure
State plainly what the project is built with. For a full-stack app that might mean naming FastAPI for the back-end, React or Next.js for the front-end, the database and any key libraries, so the agent does not reach for the wrong technologies. An agent that knows your stack generates fitting code from the first line. Spell out the technologies plainly, since a clear statement of the stack is the foundation of the whole file.
Then map the layout: tell the agent where the backend and frontend folders are and where routes, models and components live, so new code lands in the right place instead of being scattered. A short structure map is what keeps a project tidy as the agent builds it out.
List the exact commands
A dedicated commands section is often the single most useful part of the file. Tell the agent exactly how to install, build, test and run the project, one command per purpose, so it can run them directly and verify its own work. Without them, agents guess or invent commands that do not exist, which is a common failure. In a full-stack project, list the commands separately for the back-end and the front-end. Concrete commands turn the agent from a guesser into a doer, and nothing improves results faster than telling it exactly how to run your project.
Write conventions as concrete rules
Conventions work best as specifics, not adjectives. Instead of asking for clean code, name the formatter, the naming style, the folder layout, the patterns you use and the ones you ban. Concrete rules are checkable and get applied consistently, while vague values get ignored, which is why this section shapes how well your agents.md guides Cursor.
Set conventions for each half of a full-stack app
A full-stack project spans two different worlds, often in different languages, so give the back-end its own rules for style, error handling and patterns and the front-end its own rules for component structure, naming and styling. Per-half conventions keep the agent consistent across both sides and the codebase coherent.
Document the API contract between front-end and back-end
The two halves of a full-stack app connect through an API, so the file should describe that seam. Note how the front-end should call the back-end: the base URL, the endpoint conventions and the data format. This prevents the classic mismatch where the front-end expects one shape and the back-end returns another. A clear API convention is what holds the app together as the agent builds both sides.
Suggest a build order
For a multi-part build, a stated sequence helps. Indicate that the agent should build the back-end and its API first, then the front-end against it, then connect them, so it works through ordered steps instead of attempting everything at once. This is closely related to writing a good project-planning prompt.
What Is an agents.md File and Why Is It Critical for Effective Context Engineering With Coding Agents?
If context engineering is the craft of controlling what a model sees, then the agents.md file is one of its most powerful instruments. It is a small markdown file, but it does something no prompt can: it supplies the right context automatically, on every run, without you lifting a finger. That makes it the backbone of serious context work with coding agents. Understanding its role in the discipline, not just its format, is what turns it from a nice-to-have into a core tool.
It is a context engineering tool, not just a config file
It is easy to see agents.md as mere configuration, but it is really an act of context engineering. Every line in it is a deliberate choice about what an agent should know before it starts working. You are not configuring a tool so much as designing the context a model will reason from. Seen that way, writing a good agents.md is the same skill as curating any other input a model receives. The file is where context engineering becomes concrete and durable.
Context engineering needs a persistent home
Most context is fleeting, assembled fresh for each call and gone afterward, as anyone who understands the agent input context knows. The problem is that the same essential facts, your build command, your conventions, your no-go zones, are needed on every single run. Retyping them into each prompt is wasteful and error-prone, and relying on the agent to remember them is impossible since it does not. The agents.md file solves this by giving that recurring context a permanent home. It is the durable layer beneath the ephemeral context of each session.
It encodes the highest-value context
What belongs in an agents.md is precisely the context an agent cannot figure out on its own. The exact commands, the team conventions, the architectural decisions, and the traps are all things no amount of reading the code will reliably reveal. This is the highest-value context there is, because it is both essential and impossible to infer. Concentrating it in one file means the agent gets the most important guidance first and every time. You are front-loading the context that matters most and would otherwise be missing.
It is different from ad-hoc prompting
This is a fundamentally different approach from pasting context into a prompt each time. As the basics of what an agents.md file is make clear, the guidance lives with the project rather than in your head or your clipboard. Ad-hoc prompting is inconsistent, since every person and every session provides context differently. A shared file makes the context uniform, versioned, and reviewable, which prompting can never be. The move from prompting the context to encoding it is a genuine step up in discipline.
Every token in it must earn its place
Because the file is loaded into the context on every run, its length is not free. It draws from the same finite budget as everything else, which means a bloated agents.md actively crowds out room for the task, echoing why less context often produces better results. The goal is maximum signal in minimum space, every line justified by a mistake it prevents. A tight, high-signal file beats a long, comprehensive one that no one maintains. Treat its word count as a cost you are spending on every single call.
How Do You Structure a Hierarchy of agents.md Files Across Project Directories for Optimal AI Agent Performance?
A single agents.md at the root of a small project is perfect. Scale the project up, though, and that one file faces an impossible choice: stay short and become too generic, or cover everything and become a bloated wall the agent has to wade through. The answer is not one big file but a hierarchy of smaller ones, placed where they are relevant. Structuring that hierarchy well is what keeps context sharp as a codebase grows.
Why one file stops scaling
The core tension is that different parts of a large codebase need different guidance. Your frontend has conventions your backend does not share, and a payments module has rules a marketing page never touches. Cramming all of that into one root file means every agent, working anywhere, reads context that is mostly irrelevant to its task. That violates the principle that less, well-targeted context beats more. A single file cannot be both complete and focused once a project is large enough.
The hierarchy mirrors the directories
The clean solution follows the shape of the project itself. You place a general agents.md at the root and additional, more specific ones inside the subdirectories that need them, so the guidance lives next to the code it describes. An agent working in a given folder picks up the context relevant to that folder, not the whole project. This mirrors how developers already think, with shared conventions at the top and local rules where they apply. The directory tree becomes the map for the context tree.
General at the root, specific in the branches
The division of labor between levels is intuitive once you see it. The root file holds what is true everywhere: the overall architecture, the universal conventions, the shared build and test approach. The nested files hold what is true only locally: the quirks of a module, the rules of a service, the patterns of a particular layer. Each level answers a different scope of question, which keeps every file focused. General guidance flows down, and specific guidance stays put.
How agents combine the levels
Tools that support this read the relevant files based on where the agent is working. When an agent operates in a subdirectory, it typically loads the root file plus the more specific ones along the path, combining broad and local context. The nearer, more specific file usually takes precedence when guidance overlaps, just as local rules override global ones in most systems. This layering means an agent always gets the general picture plus the local detail. The agent assembles exactly the context that its current location calls for.
Keep each file to its scope
The discipline that makes a hierarchy work is keeping each file in its lane. A root file should not contain module-specific trivia, and a module file should not restate the universal conventions already covered above it. Duplication across levels is the enemy, because it bloats context and creates two places to update. Each fact should live at exactly one level, the broadest one where it is true. Clean separation of scope is what keeps the whole hierarchy lean.
How Do You Prune and Maintain Your agents.md to Keep Every Token Working Hard Inside a Limited Context Size?
An agents.md file is not a document you write once and forget. Because it loads into the context on every single run, every line in it is a recurring cost, paid on every task the agent touches. Left unattended, these files only grow, accumulating stale advice and redundant lines until they are more overhead than help. Keeping one lean and current is an ongoing discipline, and it is what separates a file that helps from one that quietly hurts.
Why maintenance is not optional
The stakes are higher than they look because of how the file is used. It sits inside a limited context window, competing for space with the actual task, so every wasted token is stolen from the work. A bloated file also buries its own important lines, making the agent less likely to act on them. And a stale line does not just waste space, it actively misleads an agent that trusts it. Maintenance is what keeps all three of these failure modes at bay.
Every line must still earn its place
The test for keeping a line is the same as for adding one: does it change what the agent does? Over time, files fill with lines that no longer matter, advice for code that was deleted, or guidance the model now handles fine on its own. Auditing against this test, and cutting anything that fails it, is the core of pruning. This is the same principle that less context produces better results, applied to the file itself. If removing a line would not change the agent’s behavior, remove it.
Prune stale content first
The most dangerous content is not the useless line but the wrong one. When conventions change, commands get renamed, or architecture is refactored, the agents.md often lags behind, and the agent follows the outdated guidance with full confidence. Hunting down and fixing stale entries is the highest-priority maintenance, because wrong context is worse than missing context. Reviewing the file whenever the underlying reality changes keeps it honest. Stale guidance is a bug in your context, and it deserves the same urgency as a bug in code.
Cut redundancy ruthlessly
Files also bloat through repetition. The same rule gets stated in two places, or guidance that lives in a nested file gets duplicated at the root, which wastes space and creates two things to update. Keeping each fact in exactly one place, the approach that makes a hierarchy of agents.md files work, keeps the whole thing lean. When you find the same guidance twice, delete one copy and trust the other. Redundancy is silent bloat that maintenance should hunt down.
Tighten wording
Beyond removing lines, you can shrink the ones you keep. Verbose explanations can usually be compressed to a crisp directive without losing meaning, since the agent needs the rule, not the essay around it. Replacing a paragraph with a single clear sentence reclaims tokens for the task while keeping the guidance intact. This kind of editing treats the file as prose to be tightened, not just a list to be trimmed. Concision is a form of pruning that keeps content while cutting cost. A sentence you can shorten without losing meaning was too long to begin with.
How Can You Iteratively Improve Your agents.md to Get Better Results From AI-Assisted Code Generation?
The first version of your agents.md file is a starting point, not a finished product. The real value comes from improving it over time, treating each mistake the agent makes as feedback about what the file is missing. Done well, this turns a decent file into an increasingly powerful one that makes AI-assisted code generation more reliable with every iteration. Understanding this improvement loop is what separates a static config from a living asset.
Start small and grow it
You do not need a perfect agents.md on day one, and trying to write one is a mistake. Begin with the essentials, the build and test commands and a few key conventions, and let the file grow as you discover what the agent actually needs, which is the spirit of the agents.md standard. A short file you refine beats a long one you guessed at. Starting small keeps the file honest, containing only rules you know matter. Grow it from real experience, not speculation.
Treat mistakes as signals
The engine of improvement is paying attention when the agent gets something wrong. Every time it uses the wrong command, ignores a convention, or edits something it should not have, that error is a precise clue about a gap in your file. Instead of just fixing the immediate problem, ask what rule would have prevented it. This reframes frustration as useful information. Each mistake tells you exactly what your agents.md is missing.
Add a rule for each recurring error
When you notice the agent repeating a particular mistake, the fix is to encode a rule against it. Writing a clear instruction into the file, once, stops that error from recurring on every future task, which is a permanent win from a one-time effort. Over many iterations, these accumulated rules become a dense set of guardrails tuned to your exact project. This is how an agent gets steadily more reliable without the model changing at all. Turn each repeated mistake into a rule you never fight again.
Be specific in what you add
The rules you add work best when they are concrete. A vague addition like write better code does nothing, while a specific one like always use the existing error handler in utils changes behavior. Each rule should target an actual mistake with a clear, checkable instruction. Specificity is what makes the difference between a file that guides and a file that merely reassures. Add rules that would visibly change what the agent does.
Prune as you add
Improvement is not only addition, since a file that only grows eventually bloats. As you add rules, remove ones that no longer apply, whether because the code changed or the model now handles that case on its own, keeping the file lean. This balance echoes why less context often produces better results, since a bloated file buries its own important lines. Improving your agents.md means editing it, not just appending to it. Add and trim in the same breath.
How Do You Write Clear Business Requirements and Coding Standards for an AI Coding Agent?
An AI coding agent is only as good as the instructions you give it, and it will faithfully build what you specified rather than what you had in mind. This makes two kinds of writing suddenly high-value: business requirements that say what to build, and coding standards that say how to build it. Get these clear and the agent produces the right thing consistently, while leave them vague and it confidently produces the wrong thing. Learning to write both well is one of the most leveraged skills in AI-assisted development.
Why specification matters more with agents
With a human developer, unwritten context and shared judgment fill the gaps in a loose spec, but an agent has neither, which is stressed in guides to building effective agents. It cannot ask the clarifying questions a colleague would, or it asks and then guesses anyway, so ambiguity turns directly into wrong output. This means the precision that was optional with people becomes essential with agents. The spec is not a formality, it is the actual input that determines the result. Vague in, wrong out.
Start with clear business requirements
Business requirements describe what the software should do from the user’s point of view. Write them concretely: state exactly what the feature does, who uses it, what inputs and outputs are involved, and what counts as success. Avoid fuzzy words like fast or user-friendly in favor of specific, checkable statements. A requirement the agent can build against is one that leaves little room for interpretation. Precision here is what keeps the agent aimed at the right target.
Make success measurable
The most useful requirements define done in a way you can verify. Instead of saying the search should work, say the search returns matching items within a set time and handles an empty query gracefully, so both you and the agent know when the job is complete. Measurable requirements double as a checklist for reviewing the output. They also let tests confirm the result automatically. When success is concrete, both building and verifying get easier.
Describe the why, not just the what
A little context about purpose helps the agent make better choices. When it understands why a feature exists and who it serves, it fills small gaps in a way that fits your intent rather than guessing randomly. You do not need an essay, just a sentence of intent alongside each requirement. This helps the agent behave more like a thoughtful collaborator than a literal machine. Purpose guides the judgment calls a strict spec cannot cover.
Coding standards say how to build
Where requirements say what, coding standards say how. These are your conventions: naming, structure, error handling, testing expectations, security practices, and the patterns your codebase follows. Writing them down means the agent produces code that fits your project instead of its own default style. Without standards, an agent builds correct-but-alien code that is a chore to maintain. Standards are what make agent output feel like it belongs in your codebase.
Common questions
What is the difference between agents.md and claude.md?
Both are markdown files that brief a coding agent on your project. claude.md was Anthropic’s vendor-specific version that popularized the idea, while agents.md is the open, cross-tool standard formalized in 2025 that generalizes the same concept.
What should you put in an agents.md file?
Exact build, test and lint commands, coding conventions, key architectural decisions, and warnings such as directories never to edit or secrets never to commit. Keep it concrete and short, since it loads on every request.
Do you still need claude.md or Cursor rules if you have agents.md?
Not necessarily. Many tools now read agents.md and some read both, so a common approach is to keep one source of truth in agents.md and point vendor-specific files at it.
Does Cursor read the agents.md file automatically?
Yes. Cursor’s agent loads the relevant project files into its context on each task, so the rules in agents.md shape its code, commands and no-go zones without you repeating them in every prompt.
Should you update agents.md over time?
Yes, it is a living file. Add a rule whenever the agent repeats a mistake and update it when conventions change, so the agent becomes steadily more reliable.
What should a full-stack agents.md include for GitHub Copilot?
The stack, the project structure, exact install, run, build and test commands for each half, concrete conventions for the back-end and front-end, the API contract that connects them, targeted do’s and don’ts and a sensible build order.
Why document the API contract in agents.md?
Because the front-end and back-end connect through the API. Noting the base URL, endpoint conventions and data format prevents the mismatch where the front-end expects one shape and the back-end returns another.
How do you know if the agent follows your agents.md?
Run a real task and watch its behavior. If a rule is ignored, make it shorter, move it higher or state it more concretely, then test again.
Related Articles
If you enjoyed reading this, then please explore our other articles below:
More Articles
If you enjoyed reading this, then please explore our other articles below:



2019-2026 ©