Short instruction card above a laptop, illustrating AGENTS.md vs CLAUDE.md files
Geeky

AGENTS.md vs CLAUDE.md: Do AI Coding Instructions Work?

Every project I start gets a CLAUDE.md file, and right next to it, an AGENTS.md symlink pointing at it. I do this even when Claude Code is the only agent that will ever touch the code. It takes ten seconds, and I never have to wonder which tool read which file.

So for me, AGENTS.md vs CLAUDE.md was never about picking one. The better question is whether either of them does anything useful. Researchers at ETH Zurich tested exactly that this year, and the answer is less flattering than the advice you’ll find in every agent’s docs.

What AGENTS.md and CLAUDE.md actually are

One notebook with two labels, like a CLAUDE.md symlinked to AGENTS.md

Both are plain Markdown files that live in your project folder. A coding agent reads them at the start of a session so it knows what it can’t guess from the code: which command runs the tests, what it must never touch, which conventions your project follows. Think of them as onboarding notes for a very fast new hire who forgets everything when the session ends.

The real difference is the name. CLAUDE.md is Anthropic’s file for Claude Code. AGENTS.md started at OpenAI, which contributed it to the Agentic AI Foundation under the Linux Foundation in December 2025, alongside Anthropic and Block. It’s now the shared format most coding agents read.

For a long time, Claude Code was the holdout. That changed on September 18, 2026, when version 2.1.277 added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead, and you can change that under “Project instructions” in /config. Google’s Antigravity reads AGENTS.md and GEMINI.md, plus a .agents/rules/ folder for extra rule files.

One file, two names

That’s why my symlink habit still holds up. A symlink is a file-system shortcut: two names, one actual file. Claude Code finds CLAUDE.md, other agents find AGENTS.md, and the two can never drift apart because there’s nothing to keep in sync.

Symlinks can be awkward on Windows. There, Anthropic’s memory docs suggest a CLAUDE.md that imports the shared file with a single @AGENTS.md line. That also leaves room for a few Claude-only instructions underneath.

What the research says about AGENTS.md vs CLAUDE.md

The ETH Zurich paper, Evaluating AGENTS.md, ran coding agents on real GitHub issues with and without context files. The files didn’t generally improve task success. They also raised inference cost, the money you pay for the model’s processing, by more than 20% on average. That held across models, agents, and both AI-generated and developer-written files.

The detail most headlines skipped: the agents followed the instructions well. They just didn’t solve more tasks because of them. Repository overviews, the “here’s how the project is laid out” sections, didn’t help at all. The authors’ conclusion is that these files earn their place when they describe non-standard practices, the things an agent can’t work out on its own.

A smaller study tells a different story. Researchers measuring AGENTS.md and agent efficiency ran agents on 124 pull requests across 10 repositories. With an AGENTS.md present, median runtime dropped by 28.64% and output tokens (the chunks of text the model generates, which you pay for) by 16.58%, with comparable task completion.

How can both be true? My reading is that it depends on what’s in the file. A line like “run tests with pnpm test, never the full e2e suite” saves the agent from discovering that the slow way. A page describing your folder structure sends it reading things it would have found anyway, and you pay for every detour. The two studies used different repositories and different files, so take that as my interpretation, not a proven explanation.

Agents follow the file, until they don’t

There’s one rule I put in every instruction file: don’t commit or push anything until I say so. Almost every agent I’ve used reads that the way I mean it. It asks me, or it waits for my command, every time.

Gemini 3 Pro used to be the exception. It asked for permission once per session, and after I said yes, it treated that as a green light for the rest of the session. The rule was sitting right there in my GEMINI.md or AGENTS.md. The model simply read “ask me” as “ask me once.”

That’s the weakness of every one of these files. Anthropic says it plainly: Claude treats CLAUDE.md as “context, not enforced configuration.” The file even reaches the model as a user message after the system prompt, not as part of the system prompt itself. It’s a strong suggestion, and a model can interpret a suggestion creatively.

So anything that must happen every time can’t live only in Markdown. Anthropic’s advice is to make it a hook instead, a shell command that runs at a fixed point, like before every commit, regardless of what Claude decides. For my commit rule, the real lock is a permission rule that forces the agent to ask before every git commit and git push. Claude Code, Codex, and Antigravity each have their own way to set that up. I still keep the line in the instruction file, because it explains what I want. It just isn’t my only defense anymore.

What belongs in the file, and what doesn’t

Long document beside a short note, showing why AI coding instructions should stay short

I start every project with /init, Claude Code’s command that scans the repo and writes a first CLAUDE.md. That’s an AI-generated file, the exact kind the ETH study found unhelpful, so I treat it as a draft. I describe the stack, add a few rules about what’s allowed and what isn’t, and change the file when the project needs it. I don’t have a template I paste into every repo.

The habit that helps most comes after a coding session. I run /revise-claude-md from Anthropic’s CLAUDE.md Management plugin, which looks back at the session and proposes changes as a diff that only applies with my approval. I don’t accept everything. The suggestions I usually keep tell Claude to skip a process it wasted time on during the session. Those lines save tokens in every session after that.

Here’s what I think earns a place in the file:

  • Commands the agent can’t guess: how to run tests, lint, and build, and which ones are slow.
  • Hard rules: don’t commit or push, don’t touch generated files.
  • Conventions that break the defaults: anything your project does differently from what the framework expects.
  • Known dead ends: “don’t try X, it fails because of Y.”

And what doesn’t:

  • A tour of the folders. The agent can list files on its own.
  • Your README. AGENTS.md is not your README.md. It has one precise job, and repeating the README just burns tokens.
  • Style rules your linter already enforces.

Keep it short, too. Anthropic recommends staying under 200 lines per CLAUDE.md, because longer files take up more of the model’s working memory and get followed less reliably. Every line is read at the start of every session, which makes every line a small tax you pay forever.

Pro Tip: Before adding a line, ask whether the agent would get this wrong without it. If the answer is no, the line costs you tokens and gives you nothing.

Keep it short and lock what matters

So, do AI coding instructions actually work? Yes, at the one job they’re good at: telling a capable agent the few things it can’t figure out on its own. They don’t make a model smarter, and they don’t enforce anything. The ETH numbers are a fair warning for anyone running a 400-line file that /init generated on day one and nobody touched since.

As for AGENTS.md vs CLAUDE.md, the choice matters less every month. Make one of them the real file, point the other at it, and spend your effort keeping it short. And if a rule truly can’t be broken, don’t write it in Markdown and hope. Lock it in the agent’s permissions.

Keep reading about: AIComputersGoogleOpen sourceProgramming

Related

Leave a comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.