AGENTS.md vs CLAUDE.md: Which One Should You Use?

You've got a CLAUDE.md in one client repo. A .cursorrules file in another. A copilot-instructions.md you copy-pasted eight months ago and never touched again. None of them agree with each other.

That's normal life for a freelancer or small agency working across several client codebases and several AI tools. This week it got a little simpler. As of September 18, 2026, Claude Code reads AGENTS.md too — the same file Cursor and GitHub Copilot already read. So here's the real question: AGENTS.md vs CLAUDE.md, which one should your repos actually use? There's a precedence rule buried in the release notes that decides the answer, and we'll get to it in a minute.

What Changed on September 18, 2026

Claude Code's changelog entry for version 2.1.277 is short. It says: "Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead." You can switch this off, or change which file wins, under "Project instructions" in /config. It isn't live yet on Bedrock, Vertex, or Foundry.

On its own, that's a small update. Here's why it matters more than it looks: AGENTS.md is an open, tool-agnostic file format. The project's own site says over 60,000 open-source repos already use it. More than 25 coding tools read it, including OpenAI Codex, Google Jules, Cursor, Devin, and now Claude Code.

For one developer on one project, that's trivia. For someone shipping ten client sites a year — each one maybe built with a different AI tool, depending on what the client's team already uses — it's the gap between one config file per project and three.

Does Claude Code Read AGENTS.md?

Yes, but only if there's no CLAUDE.md already in that project. If a repo has both files, Claude Code reads CLAUDE.md and skips AGENTS.md completely. AGENTS.md only kicks in as a backup, for a project that never had a CLAUDE.md in the first place.

That one rule is worth remembering. Adding an AGENTS.md to a project that already has a CLAUDE.md does nothing by default. Your CLAUDE.md still wins. You'd have to delete it, or point Claude Code at AGENTS.md by hand from /config.

There's a bigger question we haven't answered yet: what do the other tools you use do with this same file. That part decides whether switching is even worth it.

AGENTS.md vs CLAUDE.md: What Happens When a Repo Has Both

Here's the precedence, laid out plainly:

CLAUDE.md isn't going away. It isn't even being pushed aside. It's just no longer the only file Claude Code looks for. If your CLAUDE.md already works, nothing breaks. But if you're starting a new client repo, and you want one file that Claude Code, Cursor, and Copilot can all read with zero extra setup, AGENTS.md is now the safer pick.

How Cursor, GitHub Copilot, and Codex Handle the Same File

This is the part that actually helps if you work across tools, not just inside one.

Cursor treats AGENTS.md much like a Project Rule. It also reads nested AGENTS.md files per folder — a frontend/AGENTS.md and a backend/AGENTS.md can hold different instructions, and the more specific file wins in that folder. That's worth knowing if Cursor's recent ownership change has you thinking twice about building your whole workflow around one vendor's format.

GitHub Copilot, OpenAI Codex, and Google Jules all read a root-level AGENTS.md by default, the same way they read a README for humans. None of them need special syntax. It's just markdown, split into whatever headings fit your project: build steps, test steps, coding rules, deployment notes.

The upshot: one well-written AGENTS.md at your project root now covers most tools you or a client's other developers will touch. CLAUDE.md is the one exception, and only when it's already there.

What Actually Goes In an AGENTS.md File

Keep it plain and specific. The tools reading it don't want prose. They want commands and boundaries.

A useful AGENTS.md for client work usually covers:

• The exact commands to run (npm run dev, npm run build, npm test), not a description of them

• The framework and version in use, so an agent doesn't suggest code from a different major version

• Where build output lives, and whether it's safe to edit by hand

• Any folder the agent should never touch without asking first

• How to run the test suite before calling a change finished

Those last two points matter more than they look. An agent that doesn't know a folder is off-limits will happily "clean up" it during an unrelated task. There's one line, in particular, that most AGENTS.md files are still missing.

The One Line You Should Never Leave Out

If you deliver client work with any build-time protection step — a signing step, a license check, an encryption pass before deployment — write it into AGENTS.md under a heading like "Never modify without asking." An agent refactoring your build script has no way to know that step matters unless you say so in plain words.

This is the same habit behind protecting your code as a freelancer more broadly. The protection only holds if nothing downstream strips it out later, including an AI agent making a "helpful" change months after delivery. If you run a kill switch on delivered projects, that step needs its own do-not-touch line. To an agent skimming a next build script, it can look like dead code someone forgot to delete.

At DevAegis, that's the whole idea: the protection has to survive everyone who touches the code after you, human or not, right up until the invoice clears. An AGENTS.md that spells out your protection step, next to a devaegis.com setup that doesn't rely on a client remembering to leave it alone, covers both sides of that risk.

Which One Should You Actually Use?

If every project you touch only ever runs through Claude Code, CLAUDE.md still works exactly like it did last week. Nothing forces a change.

If you don't control which AI tool a client's team uses — and most freelancers and small agencies don't, project to project — default new repos to AGENTS.md instead. More tools read it out of the box, it's plain markdown with no required structure, and Claude Code picks it up on its own as long as you don't also add a CLAUDE.md.

One thing to do this week: open your three or four busiest client repos and check which config file each one actually has. If you find three different formats across three repos, that's the one worth fixing first.

Frequently Asked Questions

Does Claude Code read AGENTS.md? Yes. As of version 2.1.277 (September 18, 2026), Claude Code reads AGENTS.md in any project with no CLAUDE.md file. If a project has both, CLAUDE.md wins and AGENTS.md is skipped entirely.

What is AGENTS.md used for? AGENTS.md is an open markdown file in a project's root, or its subfolders, that gives AI coding agents context a README isn't built to carry: build commands, test steps, coding rules, and things the agent should never touch. Over 25 tools read it, including Cursor, GitHub Copilot, OpenAI Codex, and Google Jules.

Should I use AGENTS.md or CLAUDE.md for a new project? If the project will only ever run through Claude Code, CLAUDE.md still works fine. If you or a client's team might use Cursor, Copilot, or Codex on the same repo, AGENTS.md is the safer default, since it's the one file nearly every current AI coding tool reads without extra setup.

Can a project have both AGENTS.md and CLAUDE.md? Yes, but Claude Code will only read CLAUDE.md in that case, and it ignores AGENTS.md entirely. Tools like Cursor, Copilot, and Codex still read AGENTS.md either way, whether or not a CLAUDE.md sits in the same repo.

Want your delivered work to stay yours until it's paid for? See how DevAegis protects client deliverables — no change to how you build, just a kill switch that only you control.