Do you write an AGENTS.md?

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.

Why use 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)

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.

Example: SSW Clean Architecture

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.

✅ Figure: Good example - Providing clear, actionable context for AI agents

For more details, you can view the full AGENTS.md file on GitHub

How to implement it

1. Create the file: Add AGENTS.md to the root of your repository.
2. Keep it updated: As your project evolves, ensure the instructions in AGENTS.md remain accurate.
3. ✅ Done! As AGENTS.md is a common standard, agents should automatically look for this if it exists.

How will it handle my massive monorepo?

Place another AGENTS.md file inside each package. Agents will automatically read the nearest file in the directory tree, so the closest one takes precedence and every subproject can have its own instructions.

The "root" AGENTS.md file in this case should contain only high-level instructions for what each package is for, and what the overall architecture is, as the detailed instructions will be in the package-specific AGENTS.md files.

├── AGENTS.md - 5000 lines of instructions for every package
├── packages
│   ├── app1
│   └── app2
└── ...

❌ Figure: Bad example - A single, overloaded AGENTS.md for the entire monorepo

├── AGENTS.md - High-level architecture overview
├── packages
│   ├── app1
│   │   └── AGENTS.md - Instructions for app1 only
│   ├── app2
│   │   └── AGENTS.md - Instructions for app2 only
│   └── ...

✅ Figure: Good example - Scoped AGENTS.md files provide targeted agent instructions per subproject