Developers are increasingly using AI coding assistants to work with your API, and AGENTS.md is one of the clearest ways to steer whether those tools get accurate context or have to guess. Done well, an AGENTS.md file can meaningfully cut AI-generated errors and wasted token usage. Done poorly, it will likely do the opposite.
If you're not already writing AGENTS.md files for your API's repository, now's the time. Get it right, and these files set AI-first developers up for success when using your API. This article covers what to put in an AGENTS.md file, how to maintain it, and how ReadMe's AI features work alongside it.
TL;DR
- AGENTS.md is a plain Markdown file that tells AI coding tools, such as Copilot, Cursor, and Codex, how to work with your project.
- Most AI coding tools read AGENTS.md files automatically at the start of a session, though exactly when and how varies by tool.
- API doc teams rely on AGENTS.md files to give AI agents accurate integration context, instead of guessing at your auth pattern or reaching for a dead endpoint.
What Is AGENTS.md?
AGENTS.md is a plain Markdown file that gives AI coding agents the context they need to work with your project.
It works much like a README.md file does for humans in that it acts as a "welcome to this project" context. But while humans need architectural details and conceptual explanations, AI agents need exact commands, file paths, naming conventions, and rules to follow.
As an open, cross-platform standard, AGENTS.md belongs to no single vendor. It's used by more than 60,000 open-source projects and is now stewarded by the Agentic AI Foundation under the Linux Foundation, co-founded by OpenAI, Anthropic, and Block. With that many competing vendors behind one format, it's positioned to outlast the vendor-specific files it's meant to replace.
How Does AGENTS.md Work?
In the simplest setup, an AGENTS.md file sits in the root of a repository, and an AI agent reads it before starting on a task.
Say you open a coding assistant connected to your API's repository and ask it to add a new endpoint. Here's what happens before any code gets written:
- You ask it to add a new endpoint.
- The agent looks for an AGENTS.md file in the repository root.
- It reads the file into context: build commands, naming conventions, authentication patterns, anything the team has documented.
- It combines that with your request, using the file to fill in what was not said in the prompt. If you asked for "a new endpoint" without specifying the auth pattern, the file tells the agent which one to use.
- It starts the task. If anything in your prompt conflicts with the file (say, you explicitly ask it to skip a convention), your instruction wins.
This is roughly how a single AGENTS.md file works. Larger projects rarely stop at one file, though, and different tools handle multiple files in their own ways.
A monorepo might have a payments service, a frontend, and a backend, each with different build commands, conventions, or rules. Rather than cramming all of that into a single root file, teams can add an AGENTS.md inside each subdirectory. Agents automatically find and read the file closest to whatever they're working on, and that file takes precedence over the broader instructions in the root file. OpenAI's own Codex repository takes this approach, using dozens of separate AGENTS.md files, one for each service and package.
Exactly when a tool loads these files varies. Codex builds its full instruction chain at the start of each run, combining the root file with any nested overrides in order. Other tools load a directory's file only once the agent moves into that directory, rather than all at once at the start.
One thing stays consistent across tools: explicit instructions typed into the chat or prompt always override whatever AGENTS.md says. The file sets the defaults. It doesn't lock the agent in.
Why API Documentation Teams Should Write an AGENTS.md File
Without an AGENTS.md file to reference, the AI agent has to reverse-engineer your conventions from whatever code it finds in the repo, instead of your API documentation. This educated guess can produce hallucinated endpoints, wrong auth headers, and outdated error-handling patterns.
When a developer's AI assistant has an accurate AGENTS.md file to reference, code samples are of better quality and come together faster. It cuts down the back-and-forth of "why isn't this working?" That's the kind of experience that makes developers more likely to stick with your API.
Does AGENTS.md Actually Help?
Whether AGENTS.md helps depends on the file. Augment Code found that a single AGENTS.md file isn't uniformly good or bad; it depends on the file and the task. The clearest failure mode was overexplanation: a file documenting a full-service topology caused an agent handling a two-line config change to read 12 unrelated documentation files and ship an incomplete fix. Files in the 100 to 150 line range, paired with a few focused reference documents, delivered the most consistent gains. Past that length, the benefits reversed.
Academic research backs up the risk of getting it wrong. LLM-generated AGENTS.md files reduced task success rates by about 3% compared to no file at all. Human-written files improved success by about 4%, but still raised inference costs by up to 19%.
Cost isn't always the tradeoff, though. A separate 2026 study of 124 pull requests found that simply having an AGENTS.md file cut median runtime by 28.6% and token use by 16.6%, with task completion holding steady.
The numbers don't fully agree, partly because each study measured something different. But they converge on the same point: a poorly scoped or auto-generated file can actively hurt, and a lean, well-scoped one tends to help. The question isn't whether to write an AGENTS.md file. It's how to write a good one.
What to Put in Your API Docs AGENTS.md
A good AGENTS.md file can make a positive difference, but how can you ensure you're meeting the requirements? As a whole, aim for something in the 100 to 150 line range. Longer than that, and the file starts working against you. Here's what to include to get started.
What Your API Does
First and foremost, explain in plain language what your API is for, the problem it solves, and the type of app that would most likely integrate it. Without it, the agent has to guess at the purpose, leading to mismatched suggestions and wrong-scope changes.
Keep this section factual and avoid marketing copy. You’re not selling the AI agent on the API, just framing it properly.
Compare these two descriptions:
"Our best-in-class API empowers developers to seamlessly unlock powerful payment experiences."
"This API processes payments for e-commerce checkouts. It handles one-time charges, subscriptions, and refunds. Typical integrations are web and mobile storefronts."
The second version tells the agent what to actually do with the API. The first tells it nothing it can act on, just filler that eats into the context budget without adding signal. Aim for two to three sentences. If you can't describe what your API does in that space, the description is trying to do too much.
How Authentication Works
Authentication is the top place where an AI coding assistant can hallucinate incorrect instructions because every API handles it a bit differently. Be sure to share the explicit authentication pattern, including API keys, OAuth2, bearer tokens, and whatever else you use. Include the exact header name and format.
For example:
Authentication: Bearer token in the Authorization header.
Authorization: Bearer YOUR_API_KEY
Keys are scoped per environment. Use test keys (prefixedsk_test_) in development and live keys (prefixedsk_live_) in production.
Notice this isn't prose explaining authentication. It's the exact header, syntax, and naming convention the agent can copy directly into code. That's the format this whole section should take: a snippet, not a paragraph.
This is also where developers find credentials, so link to your auth docs.
Where the Authoritative Docs Live
Augment Code research found AGENTS.md reference links are followed in over 90% of sessions, making this one of the most reliable ways to get an agent to open the right document instead of guessing.
In your AGENTS.md file, consider including links to:
- Your OpenAPI spec
- Your developer hub or documentation site
- Any other reference files the agent might need, such as changelogs or migration guides
Write these as direct links the agent can follow, not descriptions of where things live:
OpenAPI spec:
https://docs.yourapi.com/openapi.json
Full API reference:https://yourcompany.readme.io
Without this information, the AI might not be able to find the documents on its own or might find an outdated cached version instead.
Common Errors and Their Fixes
AI agents need parameters of what not to do, but you can’t simply give them a warning; they also need a paired action. For example, instead of saying “Don’t use v1 endpoints,” say “Don’t use v1 endpoints. All production traffic uses v2 at /api/v2.”
The Augment Code research showed that warning-only lists caused agents to over-explore and underperform. Limit your list to just five to eight of the most common, experienced errors with clear directions on what to do instead. Make it more like a heads-up sheet than an error library.
Conventions and Constraints to Know Upfront
This section is where you put rate limits, pagination patterns, required headers, and naming conventions, but there's one important caveat: only include details the AI cannot reliably infer from your code.
A simple test: an agent can read a function and see how it's written. What it can't do is read your mind. It doesn't know why you made a choice, or what you strictly forbid. That's the line. If the answer is visible in the code itself, leave it out. If it's a reason, a rule, or a constraint that exists only in your team's head, it belongs here.
Here are some examples of what you should (or should not) include in your AGENTS.md file:
| Include | Exclude |
|---|---|
| "Rate limit is 100 requests per minute per API key, enforced at the gateway." | A description of how rate limiting is implemented in code the agent can already read. |
| "Never paginate using offset. All list endpoints use cursor-based pagination for consistency with downstream caching." | A walkthrough of what pagination is or how the current endpoint handles it. |
| "All resource names use snake_case, except for webhook event types, which use dot notation for legacy reasons." | A general naming convention that the agent could infer by reading two or three existing endpoints. |
If this section grows too large, the agent over-reads and prioritizes irrelevant instructions, driving up response time and token usage. Keeping it to details that genuinely can't be inferred is what keeps that risk down.
How to Keep Your AGENTS.md File Maintained
The ETH Zurich findings emphasize that you should never let AI write the file without human supervision. That’s a firm and necessary starting point, and if you begin there, maintenance will be much more effective.
Once the file is created:
- Version it with your code, and treat it like any other documentation artifact (instead of a set-and-forget file).
- Don’t let AGENTS.md get stale. If it references deprecated endpoints, it will misdirect AI tools and cause them to build incorrect implementations.
- Watch for signals in AI-generated outputs. If you see AI-generated code quality drift or require repeated corrections, AGENTS.md likely needs updating.
- Keep AGENTS.md short on purpose. If it grows past the 100 to 150 line range, push those details into linked reference files instead.
A well-maintained AGENTS.md keeps your repo's side of the equation solid. The other half is making sure your published documentation is just as easy for AI tools to find and trust.
Optimize Your Docs for AI With ReadMe
AGENTS.md covers your repository. Everything you publish beyond it, your API reference, guides, and changelogs, needs the same AI-readiness.
ReadMe is the documentation platform that covers that half, built for publishing API docs that both developers and AI tools can use. With it, AI tools get accurate, current context about your API instead of having to guess, which means fewer failed API calls and faster integrations. You also get visibility into what developers are asking, so you can close gaps before they become support tickets.
Here's how:
- ReadMe's MCP server connects AI coding assistants directly to your documentation in real time, so they work from the current version instead of a stale cache and can find what they need without leaving the IDE.
- LLMs.txt is a configuration file ReadMe generates automatically at your docs root. It tells AI how your documentation is organized and where to find the current version, cutting hallucinations from outdated information, with no maintenance required beyond a toggle.
- Ask AI puts an AI assistant inside your docs hub, answering developer questions from your actual content instead of general training data, updated every two hours and linked back to source pages.
Book a demo today to see how ReadMe can help you create AI-enabled API documentation.
FAQs
Where does AGENTS.md go in a project?
Place the AGENTS.md file in the root of the repo. You can add subdirectory files for area-specific guidance. Those only apply within that folder.
What's the difference between AGENTS.md and CLAUDE.md?
AGENTS.md is a cross-platform open standard file used by over 20 well-known tools. CLAUDE.md is a Claude Code-specific version with additional features like auto-memory and path-scoped rules. The latter is needed because Claude Code doesn't natively read AGENTS.md.
How do AI coding assistants use my ReadMe docs?
They access them via the MCP server connection, which is a real-time search, page retrieval, and endpoint lookup through natural language in the IDE. Without MCP, the AI works from whatever it has from training, which may be outdated.
