28 July 2026

Your AI coding rules are context, not configuration

The argument about which file your rules go in is basically settled. That was the easy half of the problem, and solving it changed less than people expected.

For about two years, every AI coding tool shipped its own way of remembering your project's conventions. Claude Code read CLAUDE.md. Cursor read .cursorrules. Copilot read .github/copilot-instructions.md. Codex read AGENTS.md. Same idea, same markdown, four filenames, and a lot of copy-paste for anyone whose team used more than one tool.

That part is now mostly fixed, and it's worth being precise about how.

AGENTS.md won

In December 2025 the Linux Foundation announced the Agentic AI Foundation, and AGENTS.md was one of its founding project contributions — donated by OpenAI, alongside Anthropic's Model Context Protocol and Block's goose. The co-founding organisations were Anthropic, Block and OpenAI, joined at launch by AWS, Bloomberg, Cloudflare, Google and Microsoft.

So the format has neutral governance now, which is the thing that usually decides these arguments. The AGENTS.md site lists more than 60,000 open-source projects using the file, and names two dozen tools that read it natively — Codex, Cursor, Copilot's coding agent, Gemini CLI, Windsurf, Zed, Aider, Devin, Junie, Warp, VS Code and others.

One notable absence from that list is Claude Code. Anthropic's documentation is blunt about it:

The recommended fix is a one-line bridge — put @AGENTS.md at the top of a CLAUDE.md, or symlink one to the other:

ln -s AGENTS.md CLAUDE.md

It works, and it takes ten seconds. It's still a small joke on everyone that the company which co-founded the foundation stewarding AGENTS.md ships the one major agent that doesn't read it. But a symlink is not a real problem. Here's the real one.

Every one of these files is a suggestion

Read what the tools actually say these files do. Cursor's documentation explains that when a rule applies, "rule contents are included at the start of the model context." Anthropic's is even more direct — Claude "treats them as context, not enforced configuration," and the troubleshooting section adds that CLAUDE.md "is delivered as a user message after the system prompt, not as part of the system prompt itself," so "there's no guarantee of strict compliance."

That is not a bug, and it isn't a criticism of either tool. It's what a rules file is. You are not configuring a program. You are adding text to a prompt and hoping a language model weights it correctly against everything else in the window.

Which means the interesting question was never which file. It's what happens when the model reads your rule and doesn't follow it.

How often does that happen?

More often than the tooling discourse admits. AgentIF, a benchmark built from 50 real-world agentic applications, is the most direct measurement we found. Its instructions average 1,723 words and 11.9 constraints each — roughly the shape of a real rules file plus a real task.

The headline result: the best model tested followed fewer than 30% of instructions completely. Per-model instruction success rates were 29.0% for GPT-4o, 27.2% for o1-mini and 25.7% for Qwen3-32B. Measured per individual constraint rather than per instruction the numbers are better — around 58–60% — but the categories that matter most for coding agents are the weakest: tool constraints landed around 20–26%, and conditional constraints ("if X, then do Y") around 40–45%.

Two honest caveats. Those models are from 2025 and current ones do better. And a benchmark is not your repository. Treat the numbers as direction, not as a score for the agent you ran this morning — the direction being that partial compliance is normal, and gets worse exactly where instructions become conditional or involve tools.

Which matches what using these tools feels like. The rule was in the file. The agent read the file. It followed four of your five rules, and the one it dropped was the conditional one.

Anthropic's own answer is: stop asking the model

The most useful sentence in Claude Code's memory documentation is the one that tells you when to give up on rules files entirely:

Elsewhere it repeats the split plainly: settings are "enforced by the client regardless of what Claude decides to do," while CLAUDE.md "shapes Claude's behavior but is not a hard enforcement layer."

That's the whole thing in two lines. There are two categories — things you'd like the agent to do, and things that must be true whether or not the agent cooperates — and a markdown file can only ever serve the first. If it must be true, something outside the model has to check it.

What this means if you use more than one agent

Adopt AGENTS.md. It's the closest thing to a standard, it has neutral governance, and the Claude Code bridge is a symlink. That's genuinely solved, and you should take the free win.

Then be clear-eyed about what you've won: your rules now reach every agent. Nothing about that makes any agent follow them. Distribution and enforcement are separate problems, and the industry has been loudly solving the easy one.

For the second problem the options are narrower. You can write hooks, which work but are per-tool, per-vendor, and something you have to maintain. You can review every diff yourself, which is what most people do and is exactly the tax that made agents feel less useful than promised. Or you can have something check the work afterwards, against the same rules, independently of the agent that did it.

That last one is what we're building, and it's the reason Super Terminal's reviewer is a different vendor's model from the one that wrote the code. Not because a second model is smarter — because a checker that shares the first model's blind spots and the first model's reading of your rules isn't much of a check. An agent marking its own homework is exactly the pattern the numbers above should make you suspicious of.

The rules file question is answered. Put your rules in AGENTS.md. Then assume nobody read them, and build accordingly.