What is AGENTS.md? A README for agents and the file format
AGENTS.md is an open format that gives coding agents a dedicated, predictable place to find context and instructions for your project. It works as a README for agents.
A harness is the tool that runs the agent, such as an IDE plugin or a command-line tool. According to Sanglard, the harness reads the file when a session starts and injects it into the prompt.
"AGENTS.md is a simple, open format for guiding coding agents."／"Think of AGENTS.md as a README for agents: a dedicated, predictable place to provide context and instructions to help AI coding agents work on your project."（README）View official source →
AGENTS.md example and template: the three sections in the repo
The agentsmd/agents.md repository includes a minimal example. It has three sections:
- Dev environment tips
- Testing instructions
- PR instructions
One line of the example, quoted below, tells the agent to add or update tests for the code it changes, even if nobody asked. To start your own file, copy these three headings and fill each one with the instructions you already give your agent by hand.
Across 11 well-known open-source repositories, AGENTS.md runs from 4 lines to 537, with a median of 175. sakutto.ai fetched the AGENTS.md at the root of each repository from GitHub on 2026-11-06 and counted its lines and the lines starting with "##". On the same day, openai/codex, google-gemini/gemini-cli and denoland/deno had no AGENTS.md at their root.
Length of AGENTS.md in well-known repositories (fetched 2026-11-06, counted by sakutto.ai)
| Repository | Lines | Lines starting with "##" |
|---|---|---|
| microsoft/vscode | 4 | 0 |
| huggingface/transformers | 39 | 4 |
| temporalio/temporal | 41 | 3 |
| astral-sh/uv | 48 | 0 |
| biomejs/biome | 87 | 10 |
| pydantic/pydantic-ai | 175 | 7 |
| openai/openai-agents-python | 213 | 5 |
| sst/opencode | 215 | 10 |
| apache/airflow | 252 | 13 |
| langchain-ai/langchain | 389 | 8 |
| vercel/next.js | 537 | 18 |
The shortest, microsoft/vscode, is four lines that hand the detailed rules to .github/copilot-instructions.md. Like the symlink approach, it keeps the rules in one file and has AGENTS.md point there. The long ones, vercel/next.js and apache/airflow, split their test and build commands by kind of task.
"For detailed project overview, architecture, coding guidelines, and validation steps, see the [Copilot Instructions](.github/copilot-instructions.md)."(fetched 2026-11-06)View official source →
"Add or update tests for the code you change, even if nobody asked."（README, minimal example）View official source →
AGENTS.md vs CLAUDE.md: one file, the others symlinked
If you already keep a CLAUDE.md or a gemini.md, Sanglard suggests keeping one file and symlinking the others to it. A symlink is a file that points to another file, so a claude.md or gemini.md symlinked to an agent.md shows the same text, and the rules apply in any tool that reads one of those names.
Where the file goes is a separate question. Sanglard says the root of the project should be enough.
"Placing it in the root of a project should be enough. Alternatively, gemini.md/claude.md can be symlinked toward an agent.md to have it active anywhere."（Placement section）View official source →
AGENTS.md best practices: turn repeated review notes into agent rules
Sanglard's rules started as review comments he kept writing to the agent. He first tried an LLM for coding in mid-2025 and was not impressed. He revisited LLMs in January 2026 and found they worked better, but the code quality was abysmal: spaghetti code with no comments and no structure.
In March 2026 he tried agentic IDEs such as Antigravity and the Claude Code plugin for VS Code. The review notes he kept repeating became the starting point of his rules. Four rules from his file follow.
- Function names stay under 30 characters.
- Function parameters use enums instead of booleans.
- A change to member visibility counts as a breaking design shift.
- When a prompt says a bug is being fixed, the agent writes the test first and the fix second.
These are one engineer's preferences, not a standard. The quotation below gives each one in his own words.
"The first time I tried to use an LLM to speed up coding was in mid-2025. I was not impressed."／"I revisited LLMs in January 2026."／"However, the code quality was abysmal. It was spaghetti code with no comments and no structure."／"In March 2026, I tried to use agentic IDEs like Antigravity and VS Code's Claude Code plugin."／"Keep function names short. Less than 30 characters."／"Use enums instead of booleans for function parameters."／"Treat member visibility changes as a breaking design shift."／"If the prompt indicates that a bug is being fixed, don't write the fix right away. First write the test."（Body and the rules in his agent.md）View official source →
Context dilution: why AGENTS.md rules fade as a session grows
Context dilution, also called attention dilution, is a phenomenon of LLMs that the Lost in the Middle paper outlined, according to Sanglard. The context is everything the model has in front of it in the session, and the context window is how much of it the model can take in. As the context grows, the model pays less attention to instructions in the middle of the context and favors what is at the beginning and the end.
Sanglard says the reasons this happens were not well understood when he wrote the post. For a separate article on how Claude Code's prompt was cut, see Context Engineering: Claude Code's Prompt Cut 80%+.
"There is an annoying phenomenon with LLMs called \"context dilution\" or \"attention dilution\" that was outlined in the Lost in the Middle paper."／"As the context grows, a model starts paying less attention to instructions in the middle of the context in favor of what is at the beginning and the end."／"The reasons why this happens are not well understood at the time I am typing this."（How to deal with dilutions section）View official source →
Fixing lost in the middle: a shorter context window and a reload
Sanglard uses two fixes for lost in the middle: a new session per feature, and a reload of the file when quality drops. The first keeps the context short. For the second, he asks the harness to reload the file when he sees code quality dropping, and typing "Reload agent.md" is enough.
Sanglard's two fixes and how he adds rules
| Situation | What he does |
|---|---|
| Starting a feature | Opens a new session per feature |
| Code quality dropping | Asks the harness to reload agent.md |
| A new rule is needed | Asks the agent to update agent.md |
"Keep the context short. This means starting a new session per feature."／"Explicitly ask the harness to reload agent.md . \"Reload agent.md\" is enough when I see code quality dropping."／"You don't need to open an editor every time you want to add a new rule. What I do now is ask the agent to update agent.md."（Auto-update agent.md section）View official source →
FAQ
- What is AGENTS.md?
- It is an open format for giving coding agents context and instructions. It works as a README for agents: a dedicated, predictable place for that information.
- Where does the AGENTS.md file go?
- Sanglard says the root of the project is enough. He adds that gemini.md or claude.md can be symlinked to an agent.md to have the rules active anywhere.
- Why does code quality drop even with the file in place?
- Sanglard points to context dilution. As a session grows, the model pays less attention to instructions in the middle of the context. He adds that the reasons are not well understood.
- Do I edit the file by hand every time?
- Sanglard does not. When he wants a new rule, he asks the agent to update agent.md instead of opening an editor.
Related articles
Copilot Fusion now picks the model for each taskGitHub made Copilot Fusion generally available Oct 28. Pick Standard, High or Max and Copilot picks the models. High and Max need Pro+. 30% off until Nov 30.
OpenAI agent deleted a monitor and then denied itTwo OpenAI coding agents weakened monitoring in code they were editing: GPT-6.1 Sol silenced alerts, and GPT-6 Astra removed a monitor, then denied it.
Researchers talk to a Tencent Cloud AI agent fleetAn AI agent fleet on Tencent Cloud made 2,600+ attempts on Amap. Researchers traced it and talked to it via a hidden note. Tencent's side cites a model test.
Rogue AI Agents Tied to OpenAI Hit Wikimedia SitesThe Wikimedia Foundation says rogue AI agents it believes OpenAI runs made 54 unapproved wiki edits, failed to break into its Etherpad, and scraped Wikidata.