AGENTS.md: One Config File to Rule All Your AI Coding Agents

· 8 min read en · #ai#developer-tools#workflow#agents

Your team uses different AI coding tools. One developer loves Claude Code. Another swears by Cursor. Someone else won’t shut up about GitHub Copilot.

That’s fine. Use whatever makes you productive.

But here’s the thing nobody warned us about: every AI was writing code differently. And it was slowly turning our codebase into a mess.

We Moved Faster — In Three Different Directions

We’re a frontend team building with React, Next.js, and Tailwind CSS. When we started using AI coding agents, the speed boost was real. Pull requests flying in, features shipping ahead of schedule. We felt unstoppable.

Then we started reviewing the code.

The developer on Claude Code? Server Components everywhere — even in places where we needed client-side interactivity. The Cursor user? CSS modules all over the place, despite our team agreeing on Tailwind months ago. And Copilot was happily sprinkling any types like confetti.

Three developers. Three AI tools. Three completely different codebases emerging inside the same repo.

Why This Happens

Each AI coding tool reads its own config file:

So unless every developer on your team carefully maintains every config file for every tool — and keeps them perfectly in sync — you end up with inconsistent rules. Or worse, no rules at all. The AI just guesses based on whatever patterns it sees.

Sound familiar?

This Problem Isn’t New. The Solution Shouldn’t Be Either.

Think about it. We solved this exact problem years ago with linters and formatters. Nobody maintains a separate ESLint config per editor. You write one .eslintrc, commit it, and every developer gets the same rules regardless of whether they use VS Code, WebStorm, or Vim.

We needed the same thing for AI coding agents.

Enter AGENTS.md

AGENTS.md is an open standard — created by OpenAI in August 2025 and later contributed to the Agentic AI Foundation under the Linux Foundation. Anthropic, Google, Microsoft, and others are platinum members of the foundation.

The concept is dead simple: one Markdown file at the root of your project that tells every AI coding agent how your team writes code.

Here’s what ours looks like:

# Project: My Awesome App

## Tech Stack
- Framework: Next.js 15 (App Router)
- Language: TypeScript (strict mode)
- Styling: Tailwind CSS

## Patterns We Follow
- Server Components by default, Client Components only when needed
- Zod for all runtime validation
- Error boundaries at route level

## Patterns We Avoid
- `any` type — always define proper types
- Direct database calls in components — use server actions
- CSS modules — we use Tailwind exclusively
- Don't add new dependencies without team discussion

## Build & Test
- `npm run dev` — start dev server
- `npm run test` — run tests
- `npm run lint` — lint check

Nothing fancy. No YAML frontmatter. No special syntax. Just plain Markdown that both humans and AI agents can read.

Most Tools Already Support It

Here’s the part that surprised me: you probably don’t need to do much setup.

Cursor, GitHub Copilot, Gemini CLI, and OpenAI Codex all read AGENTS.md natively. Drop the file in your project root, and they pick it up automatically.

The one exception? Claude Code. It still reads CLAUDE.md instead. But there’s a one-line fix — create a symlink:

ln -s AGENTS.md CLAUDE.md

Now Claude Code opens CLAUDE.md, follows the symlink, and reads your AGENTS.md. Same file. Same rules. Every tool on the same page.

Fair question. Think of it as a shortcut — like the ones you create on your desktop. The shortcut isn’t the actual file. It just points to it.

So when Claude Code looks for CLAUDE.md, it finds the symlink and reads AGENTS.md instead. You only edit one file. The shortcut stays in sync automatically.

And again — this is only needed for Claude Code. Cursor, Copilot, and the others read AGENTS.md directly.

What Actually Belongs in This File?

After a few months of using this approach, here’s what we’ve found matters most:

Your tech stack. Framework, language, styling approach. This alone prevents half the bad suggestions. When the AI knows you’re on Tailwind, it stops suggesting CSS modules.

Your patterns. The conventions your team follows. “Use Server Components by default.” “Always validate with Zod.” “Error boundaries go at the route level.” Be specific about how your team does things.

Your anti-patterns. This one surprised me — telling the AI what NOT to do is often more effective than telling it what to do. Every time someone on your team catches the AI doing something wrong, add it here. The list grows organically and gets more useful over time.

Build and test commands. So the AI can verify its own work. If it can run npm run test after making changes, it catches its own mistakes before you have to.

File structure. Where things go in your project. Which folders are for what. This helps the AI put new code in the right place.

What Your Project Looks Like

project-root/
├── AGENTS.md      # ← The one file you actually edit
├── CLAUDE.md      # ← Symlink to AGENTS.md (for Claude Code)
└── src/
    └── ...

That’s it. Cursor, Copilot, and Codex read AGENTS.md directly. Claude Code reads it through the symlink. No other config files to maintain.

For monorepos, you can add nested AGENTS.md files in sub-packages:

packages/
├── frontend/
│   └── AGENTS.md    # Frontend-specific rules
└── backend/
    └── AGENTS.md    # Backend-specific rules

The parent AGENTS.md covers shared rules. The nested ones add package-specific conventions.

What We Learned After Using This for Months

Treat it like code. Put AGENTS.md in version control. Review changes in PRs. When someone discovers a new anti-pattern, they open a PR to add it. This file is a living document — it gets better every week.

Start small. Our first version was maybe 15 lines. Tech stack, five key patterns, build commands. That’s enough. You don’t need a perfect config on day one. Let it grow based on what the AI keeps getting wrong.

Explain the “why.” Instead of “use Server Components,” write “use Server Components by default because we want to minimize client-side JavaScript.” AI agents make better decisions when they understand the reasoning behind a rule, not just the rule itself.

Keep it short. Everything in this file takes up space in the AI’s context window. We try to stay under 100 lines. If you need more, consider splitting into nested files for different packages instead of one massive root file.

Migrating Existing Rules

If you’ve already set up rules in Cursor or Copilot and want to consolidate them, there’s a CLI called rule-porter that converts between formats:

npx rule-porter --to agents-md
npx rule-porter --to claude-md
npx rule-porter --to copilot

It reads your existing rules and outputs them in the target format. Useful for migration. If you’re starting fresh, you don’t need it — just write the AGENTS.md from scratch.

The Honest Truth

This isn’t magic. The AI will still make mistakes. It’ll still occasionally ignore your rules or do something unexpected.

But the difference between “AI with shared project context” and “AI guessing blindly” is massive. Before AGENTS.md, we were spending hours every week fixing inconsistent AI-generated code. Now we spend minutes.

The tool your team uses doesn’t matter nearly as much as the instructions you give it. One shared config file. 30 minutes to set up. Every developer gets consistent, project-aware AI suggestions regardless of which tool they prefer.

Create an AGENTS.md, add a symlink for Claude Code, commit it, and move on. It’s the highest-leverage thing you can do for your AI-assisted workflow today.

References & Further Reading

← Back to all posts