Do you write an AGENTS.md?
Loading last updated info...
AI coding assistants like Cursor and GitHub Copilot are incredibly powerful, but they work best when they understand your project's specific architecture, coding standards, and common tasks. Without this context, they may suggest patterns that don't align with your codebase.
AGENTS.mdis an agreed-upon standard between all the big AI players, replacing things like .cursorrules and copilot_instructions.md.
What goes into an AGENTS.md?
An AGENTS.md file acts as a "manual" for AI agents. It provides a centralized place to define:
- ✅ Architecture overview - Explain the tech stack and how different layers interact
- ✅ Coding standards - Define naming conventions, preferred libraries, and patterns
- ✅ Common commands - List frequently used scripts for building, testing, and linting
- ✅ Key patterns - Provide code examples for common tasks (e.g. adding a new API endpoint)
- ✅ Links to documentation - Reference ADRs, design docs, or wikis rather than duplicating content (e.g.
See /docs/adr/001-authentication.md for auth patterns) - ❌ Secrets - Never put API keys, secrets, or sensitive internal information, it's committed to source control
By providing this information, you ensure that the AI's suggestions are consistent with your project's existing structure, reducing the need for manual corrections.
Tip: If you find AI repeatedly doing the wrong thing, ask the AI to update the AGENTS.md with the preferred way to do something!
Example
A great example of this in practice is the SSW Clean Architecture template. Its AGENTS.md file provides clear instructions on everything from the dependency flow to specific MediatR patterns.
The AGENTS.md in SSW Clean Architecture includes:
- Architecture overview: - Explaining the WebApi → Application → Domain flow
- Key patterns - Clear C# examples for Commands, Queries, and Domain Events
- EF migrations - The exact commands to use for database changes
✅ Figure: Good example - Providing clear, actionable context for AI agents
For more details, you can view the full AGENTS.md file on GitHub
As your project grows, so will your AGENTS.md. Read on to learn how to tackle the scaling problem.
Even better: multiple AGENTS.md
You might be thinking: “Wait.. I have a massive monorepo. There's no way it's efficient to capture all that information in one file, and feed it into the AI in one go…”
Correct. It's unwise to waste precious space in the context window, but dumping in the entire AGENTS.md if only 5% of it is useful.
This is where hierarchy comes in. As per the standard, Agents will prioritise the nearest AGENTS.md file, while also injecting all parent AGENTS.md in its path.
Figure: If working in `repo/apps/web-app/src`, the highlighted AGENTS.md are used
In the case of conflicting or more specific instructions, the closest AGENTS.md file in whichever directory the Agent works in will take precedence. This means every subfolder can have its own instructions, without sacrificing detail.
The "root" AGENTS.md file in this case should contain only high-level instructions for what each package is for, what the overall architecture is, and how to run the whole application, as the detailed instructions will be in the package-specific AGENTS.md files.
Multiple AGENTS.md is particularly useful for architectures like Modular Monoliths, where you can place AGENTS.md inside each module.
├── AGENTS.md - 5000 lines of instructions for API, API tests, Frontend, frontend tests, etc...├── src│ ├── frontend│ └── backend└── ...
❌ Figure: Bad example - A single, overloaded AGENTS.md for the entire monorepo
├── AGENTS.md - High-level architecture overview├── src│ ├── frontend│ │ └── AGENTS.md - Instructions for frontend only│ ├── backend│ │ ├── AGENTS.md - Instructions for backend only│ │ ├── tests│ │ │ └── AGENTS.md - Instructions for backend testing only│ │ └── ...... ...
✅ Figure: Good example - Scoped AGENTS.md files provide targeted agent instructions per subproject
You could also have a separate AGENTS.md for your tests!
Writing tips
- Be concise - Put the most important rules first; long files may be truncated
- Use imperative language - "Use X" not "You should consider using X"
- Show, don't tell - Specific code examples beat vague descriptions
- Avoid duplication - Don't repeat what's in linter configs or
.editorconfig - Keep it current - Outdated instructions are worse than none
How to install
🦕 Manually
- Create the file: Add
AGENTS.mdto the root of your repository. - Keep it updated: As your project evolves, ensure the instructions in
AGENTS.mdremain accurate. - ✅ Done! As
AGENTS.mdis a common standard, agents should automatically look for this if it exists.
❌ Figure: Bad example - Creating it without AI assistance
Paste a prompt
If your AI-IDE or CLI tool doesn't support this yet, you can use the prompt from the GitHub docs (and rename “copilot-instructions.md” to “AGENTS.md”
https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions
🙂 Figure: OK example - Paste the prompt
⭐ AI Enabled (Recommended)
Most AI IDE or CLI tools provide a way to generate this documentation, e.g. in OpenCode, you can run
/init
Which will automatically setup AGENTS.md.
✅ Figure: Good example - Using AI to install
Tip: To let your Agent maintain the documentation, add something like this to the AGENTS.md: "Ensure you keep AGENTS.md up to date if any changes to the codebase necessitates it."