AGENTS.md: One File for All Agents

AGENTs.md - one file, work across many agents

AI Coding Agents are everywhere now.

Some live in the terminal, some work inside your IDE. Whatever the setup, every developer is using one today.

Codex CLI, Claude Code, Gemini CLI, Cline, Cursor, Copilot. The list goes on.

If you’ve used any of these coding agents, you might know they work best when they have the right context and clear instructions. The context and guidance come from their config files.

But each coding agent has its own config file. That creates a few problems when you switch between coding agents or work in teams that use different agents.

The solution? A single file - AGENTS.md. An open standard that serves as a common config file for all coding agents.

Before we dive in, here’s what we’ll cover in this post:

1. What is AGENTS.md

2. Why AGENTS.md

3. What goes inside AGENTS.md

4. Coding Agents and their native config files

5. Bridging AGENTS.md with Coding Agents

1. What is AGENTS.md

AGENTS.md is an open format, for guiding coding agents. A single place where AI coding agents can get the context and instructions, they need for your project.

README.md is for developers, AGENTS.md is for coding agents.

Most modern agents can already detect and read AGENTS.md automatically.

It is now used by more than 40K open-source projects and supported by tools like Codex, Cursor, Gemini CLI, Factory, Amp, and many others.

2. Why AGENTS.md

The Discussion

Developers have already started asking for AGENTS.md support.

In a GitHub discussion for Claude Code, user requested for AGENTS.md support. Similarly, Cline users raised a GitHub issue asking for AGENTS.md support. Because several major tools had already adopted it.

The Reason

Since every coding agent follows its own config file, it becomes difficult when you switch tools or work in a team using different agents.

The Issue

Here is what usually happens,

1. When you switch to another coding agent, you need to create a new file for it.

2. If you clone a repo that already has a .cursor/rules file, you need to add a CLAUDE.md or another file for your own agent.

3. If you are working in a team, everyone ends up creating a different file for the same project.

4. You end up maintaining multiple files that all describe the same project.

The Solution

That is why many coding agents have started adopting AGENTS.md. Instead of many files with different names, you maintain one common file that works across tools.

3. What Goes Inside AGENTS.md

AGENTS.md isn't something completely new. It contains the same project knowledge that you'd put in any agent config file.

What we saw above is a general structure. Along with common instructions, you can also include project-specific rules and details.

Project Rules the Agent Should Know

Your Agent might understand the code, but not the business rules behind it. Add them in AGENTS.md so the agent knows how your system should behave.

## Domain Rules
- Admins can edit, not delete published content
- Orders auto-lock 2 hours after creation
- Free users get 3 exports per month
- Webhooks retry 3 times then dead letter

Architecture Decisions

Add the architecture choices you’ve already made. So, your Agent knows what to follow and doesn’t suggest things you’ve already decided.

## Architecture Decisions
- PostgreSQL: We need ACID for payments
- Redis: Session storage, not business data
- TypeScript: Catch bugs before users do
- Microservices: Deploy teams independently

Team Rules the Agent Should Follow

Every team has its own way of working. The senior developers know it, but new members and your AI won’t. Add these rules in AGENTS.md so the agent follows the same team practices.

## Team Conventions
- API errors include requestId for support
- Never show stack traces to users
- All forms validate on blur, not submit
- Cache config data, not user data

API Details the Agent Should Know

Docs are helpful, but APIs often behave differently in real use. Add these notes in AGENTS.md so your agent understands how the APIs actually behave in your project.

## API Integration Details
- Stripe: Retry anything, it's idempotent
- SendGrid: Rate limits hard, queue your emails
- S3: Takes time to be consistent, verify uploads
- Analytics: Fire and forget, don't block users

Common Issues

Every project runs into the same issues more than once. Add the ones you’ve already fixed, so you don’t waste time fixing them again.

## Common Issues
- Slow app? Check user file uploads
- Auth failing? Redis probably died
- Deploy stuck? Environment variables changed
- Memory leak? Background jobs not cleaning up

Start Small, Grow Smart

Start simple and keep improving it as your project grows. Whenever your team or AI learns something new, add it here.

Over time, AGENTS.md becomes your project’s memory. New developer joins? They understand the project right away. Switch to a different coding agent? Still gets the same context and writes the same quality code.

4. Coding Agents and their native config files

It’s important to know each coding agent’s native config file. If an agent doesn’t support AGENTS.md yet, you’ll know where to link AGENTS.md so the agent can read it.

• Claude Code uses CLAUDE.md

• Cursor uses .cursor/rules/rules.mdc

• Windsurf uses .windsurf/rules/rules.md

• GitHub Copilot reads from .github/copilot-instructions.md

• Cline uses .clinerules/rules.md

• Gemini CLI uses Gemini.md

5. Bridging AGENTS.md with Coding Agents

Some agents, such as Claude Code and Cline don’t officially support it yet. But they can still read AGENTS.md if it’s present in your project. I tested this and it works fine in most cases.

But for safer compatibility, let’s use symbolic linking. This method makes sure every agent reads from the same source without breaking its own setup.

1. Using Symbolic Linking

Make your coding agent read AGENTS.md directly by linking it like this.

# Claude Code
ln -s AGENTS.md CLAUDE.md

# Cline
ln -s AGENTS.md .clinerules/rules.md

# Cursor
ln -s AGENTS.md .cursor/rules/rules.md

# Windsurf
ln -s AGENTS.md .windsurf/rules/rules.md

# GitHub Copilot
ln -s AGENTS.md .github/copilot-instructions.md

Your tools keep working. But now they all read from the same source.

2. Using Import Inside Config Files

You can also import AGENTS.md directly inside the agent’s config file. For example, if you are using Claude Code, add this in your CLAUDE.md file.

# In ./CLAUDE.md
@AGENTS.md

This makes Claude Code read everything from AGENTS.md as its main project context. It keeps your setup simple and avoids repeating the same instructions across files.

What’s Next

Coding agents have started to follow a common standard.

Think of a future where every repo has an AGENTS.md file and every coding agent reads from the same source.

For now, we use symbolic linking or import methods to make AGENTS.md work with existing agents. It’s a simple bridge that keeps everything compatible. But this will evolve.

Soon, new agents may start looking for AGENTS.md by default.

Happy Learning!