CLAUDE.md vs AGENTS.md — The Two Files That Make AI Actually Understand Your Project

I'll be honest — the first few times I used Claude Code, I kept repeating myself.

"This project uses FastAPI." "Don't touch the /generated folder." "Run pytest not python test.py."

Every new session. Same instructions. Like onboarding the same intern from scratch every single morning.

Then I found out there's a file you can just... put in your project. And the AI reads it before doing anything. And I felt slightly embarrassed for not knowing sooner.

That file is either a CLAUDE.md or an AGENTS.md. And if you're using any AI coding tool and you haven't set one up yet — this blog is for you.

---

What Are These Files, Actually?

Both are plain Markdown files you drop in the root of your project. When an AI coding assistant starts working in your repo, it reads this file first — before touching any code.

Think of it as the README you write for the AI instead of for humans. Except this one actually gets read every single time.

Without it, the AI is guessing. With it, the AI behaves like someone who already did the onboarding — knows the stack, knows the rules, knows what not to touch.

---

The Actual Difference

CLAUDE.md is Claude-specific. Claude Code and other Anthropic tools look for this file by default. If you're exclusively in the Claude ecosystem, this is your file.

AGENTS.md is a shared cross-tool standard. It works with Claude, OpenAI Codex, Cursor, Aider, Jules, and most modern AI coding tools. Over 20,000 open-source projects already use it as of 2026.

The mental model that clicked for me:

CLAUDE.md  →  a note addressed to one specific person
AGENTS.md  →  a note pinned on the fridge anyone can read

Same content. Different audience.

---

Why Both Exist (A Quick History)

Early on, every AI tool invented its own instruction file. Claude had CLAUDE.md. Cursor had .cursorrules. GitHub Copilot had its own thing. If you used more than one tool, you were maintaining three files that said the same thing.

The AI dev community eventually got tired of this and agreed on AGENTS.md as a common standard. One file, any tool. That's the idea.

---

What Goes Inside

Both files use plain Markdown. A solid one has these sections:

Project overview — one paragraph, what does this project do and what's the stack.

Setup commands — how to install and run it. The AI will actually use these.

Code style rules — your preferences. Tabs vs spaces, async/await vs promises, component size limits, whatever matters to you.

Testing instructions — which command to run, when to run it.

Folder structure — a quick map of where things live. Especially useful in monorepos.

Hard rules — the non-negotiables. "Never edit /generated." "Don't commit .env." "Add a comment whenever you write a workaround."

Here's a real-world minimal example:

# My FastAPI Project

REST API for a task management app. Built with FastAPI + PostgreSQL + SQLAlchemy.

## Setup
- `pip install -r requirements.txt`
- `uvicorn main:app --reload` to start the dev server

## Testing
- Run `pytest` before committing. Always.

## Code Style
- Type hints on all functions, no exceptions
- Keep route handlers thin — business logic goes in services/
- Use async functions for all DB operations

## Don'ts
- Never edit files in /migrations manually
- Never commit .env — use .env.example as reference

That's it. Short, useful, never ignored.

---

Which One Should You Use?

If you only use Claude Code → create a CLAUDE.md. It's what Claude looks for natively and gives the most reliable behavior.

If you use multiple AI tools or want to future-proof your setup → use AGENTS.md. It works everywhere.

If you want the best of both without maintaining two files — here's the setup I'd recommend:

Step 1: Create AGENTS.md with all your actual instructions.

Step 2: Create a CLAUDE.md with just one line:

See @AGENTS.md for project instructions.

Claude reads the pointer, follows it to AGENTS.md, picks up everything. Every other tool reads AGENTS.md directly. You only maintain one real file. No duplication, no drift.

---

Where to Put It

Root of your project. That's the default and it covers everything.

For bigger projects — monorepos especially — you can put smaller instruction files inside subfolders. The AI combines instructions from the root file and the subfolder file when working in that subdirectory. Useful when your frontend and backend have genuinely different rules.

---

The Mistake I See Beginners Make

Writing a 300-line instruction file and wondering why the AI still makes the same mistakes.

Longer isn't better here. A file that's too long wastes tokens on every request and buries the important rules in noise. The AI might miss the critical "never edit /generated" rule because it's buried after 200 lines of project history.

Keep it tight. If a rule isn't important enough to say in one line, it probably doesn't belong in the file.

---

The Right Mental Model

Ask yourself: if a new developer joined my team tomorrow, what would they absolutely need to know in their first hour to not break anything?

That's your file. Not the full architecture doc. Not the design decisions from 2022. Just the essentials for not making expensive mistakes on day one.

Write it for that person. The AI will benefit from exactly the same clarity.

---

Key Takeaways

• CLAUDE.md is Claude-specific; AGENTS.md is a cross-tool standard supported by 20,000+ projects
• Both are plain Markdown files placed in your project root — the AI reads them before doing anything
• The best setup: full instructions in AGENTS.md, a one-line CLAUDE.md pointing to it
• Keep the file short and focused — long files bury important rules and waste tokens
• Treat it as onboarding for a new teammate, not a comprehensive technical document
• Update it whenever the AI keeps making the same mistake — that's the signal something's missing

---

If you're building with Claude Code or any AI coding tool and haven't set this up yet — spend 10 minutes on it. Future you will notice the difference.