Why I Switched from CLAUDE.md to AGENTS.md (and What Changed in My Agent Output)

Running three coding agents in rotation is the default in my workflow now. Claude Code for the longer reasoning tasks, Codex for fast iteration, Cursor when I am inside an IDE and want inline completions. They share the same repo, the same git history, the same client context. What they did not share, for the longest time, was the same instructions.

A CLAUDE.md file in the root of every project felt like the right answer when I was running one agent. The day I noticed Codex pushing a commit that violated a rule clearly written in CLAUDE.md, I realized the obvious thing I had been ignoring. Codex does not read files called CLAUDE.md. None of the non-Claude agents do. Every other agent on my machine was working in the same repo, blind to half my conventions.

So I switched to AGENTS.md. I want to be precise about what changed, because the rename was the cheap part. The real lift was rewriting what I put inside the file. Here is how I did it and what behavior shifted in the agents once I did.

The day rules in CLAUDE.md stopped being enough

The trigger was not one dramatic incident. It was a slow pattern. A Codex run committing snake_case where the project used camelCase. A Cursor completion pulling in a dependency the repo had explicitly banned. A vibe-coded branch that broke a code-style convention I had documented carefully in a CLAUDE.md file three folders deep.

Each violation was traceable. I had written the rule, I knew where the rule lived and the agent that broke it had no instruction to read that file. CLAUDE.md was a contract with exactly one party. The rest of my toolchain had never signed it.

My first fix was naive. I copied CLAUDE.md to AGENTS.md and let both files exist side by side. That made the agents stop colliding within an hour. It also revealed that the contents I had been writing were Claude-shaped, not agent-shaped, and the rewrite that followed mattered more than the rename.

What AGENTS.md actually is

AGENTS.md is a tool-neutral filename for agent operating instructions, the way .editorconfig is editor-neutral and Dockerfile is runtime-neutral. OpenAI's Codex CLI reads it by default. Cursor supports it. Several agent frameworks pick it up automatically. The point is not branding. The point is that any agent landing in your repo finds one canonical document instead of guessing whether to read CLAUDE.md, .cursorrules, INSTRUCTIONS.md or just the README.

CLAUDE.md still has a place, but a narrower one. Claude Code has specific runtime concepts that no other agent shares. Slash commands, hooks, skills, settings.json bindings. Those are Claude-runtime guidance, not project context. I keep them in CLAUDE.md. Everything an agent needs to do work in this codebase, regardless of which agent runtime is hosting it, goes in AGENTS.md.

What I rewrote inside the file

The original CLAUDE.md read like a request. "Please use single quotes." "When you use your TaskCreate tool, please update tasks promptly." It assumed a specific agent identity and addressed it conversationally.

The new AGENTS.md reads like config. Sections, not paragraphs. Declarative rules, not requests. Each rule short enough that no agent can interpret around it. The structure I now use in every AGENTS.md, in order:

• Environment: OS, shell, package managers, runtime versions
• Workspace Layout: what lives where, which folders are active projects, which are archived
• Editor Configuration: formatter, linter, autofix-on-save settings
• Code Style: explicit and short, e.g. single quotes, trailing commas, 2-space indent, prefer type over interface
• Tooling Conventions: which package manager to prefer when lockfiles disagree
• Common Commands: the handful of commands the agent will probably need
• Domain-Specific Instructions: anything project-specific that is not standard: vault paths, wallet locations, client-side conventions
• Writing Style: for content tasks: no em dashes, no Oxford comma, etc.
• Operating Rules: the numbered list of things to always do and never do, with one-line reasons

The one-line reason matters more than I expected. "Never amend a published commit" is followed by agents who do not know why. "Never amend a published commit because rewriting shared history breaks teammates' working trees" is followed by agents who can then judge edge cases. The reason is what makes a rule survive context the rule did not anticipate.

I also deleted a lot. Tutorial prose, encouraging language, anything that read as advice rather than constraint. Agents do not need encouragement. They need constraints they cannot route around.

What measurably changed

I want to be careful here. I do not run a dashboard counting rule violations per session, so I will not pretend to. What I do have is the qualitative experience of running three agents on the same codebase for months, and the difference is concrete enough to name.

• Same rules respected by every agent. Claude Code, Codex and Cursor now produce code that respects the same conventions in the same repo. Before the switch, does it follow the style guide depended on which agent you asked.
• Onboarding a new agent dropped from a setup task to no task at all. I added a fourth agent to my rotation recently. The configuration step was zero. The AGENTS.md file in the repo did the work that used to take me an hour of writing tool-specific config.
• Convention drift between sessions disappeared. When the agents disagreed on style before, the drift came from agents working off different context. Now they work off the same context and the disagreements are about reasoning, not conventions.

The honest pattern is this. I cannot prove the agents are individually smarter after the switch. I can show that they are now consistent with each other, and consistency was the bug I had been failing to solve.

Where CLAUDE.md still earns its keep

The split rule I now apply is simple. Project context and conventions go in AGENTS.md. Tool-specific runtime guidance stays in CLAUDE.md.

That means CLAUDE.md in my repos is now short. A few paragraphs on Claude Code's specific behaviors: how to invoke skills, which hooks fire when, how settings.json overrides interact with project state. Anything a Codex agent has no business reading. AGENTS.md is now the long file, the operating manual, the document every agent should treat as the source of truth for how do we build in this repo.

If your AGENTS.md and CLAUDE.md have the same content with just a different filename, you have not finished the job. The point of the split is that each file means something different. Project rules go in the tool-neutral one. Tool quirks go in the tool-specific one.

The bigger pattern this fits into

Every coding tool spent the past two years inventing its own filename for stuff the AI should know about this repo. Cursor had .cursorrules. Aider had its own conventions. Claude Code shipped CLAUDE.md. Continue had a different format again. Now the ecosystem is converging on AGENTS.md, the same way JavaScript bundlers eventually converged on package.json after years of each one inventing its own manifest format.

This is the boring senior-dev play. When the ecosystem is converging on a standard, adopt the standard. Stop maintaining tool-specific config files for every new agent your team adds to the rotation. AGENTS.md is not the most exciting convention to land in. It is just the one that survives the next tool you onboard.

It also reframes how I treat these files. Agent instruction files are now a first-class engineering artifact in my repos, not a personal preference dump. They are infrastructure-as-code for the agents working in the project. They get reviewed in PRs. They get versioned. They get refactored when a rule turns out to be wrong.

Conclusion

Renaming CLAUDE.md to AGENTS.md was the cheap fix. Rewriting what was inside the file, separating project context from tool quirks, switching from request-style prose to config-style declarations, was the actual work. The combination is what made my agents start agreeing with each other instead of fighting over conventions in every pull request.

If you are running more than one coding agent in rotation, this is the smallest workflow change with the biggest behavioral payoff I have made in the past year. Start with the rename. Spend the afternoon on the rewrite. The next agent you add to your stack will thank you by behaving like the others on day one.

If you want the full structure I run in production, including the operating rules and the writing-style rules I have refined across client projects, that is the kind of senior-dev AI workflow content I unpack inside The Agentic Architect Lab on Skool. Senior Dev Energy + AI Speed = Ship More Together.

Sources

• OpenAI Codex CLI: supports reading AGENTS.md from the project root by default. See the Codex CLI documentation for the current behavior.
• Cursor: added AGENTS.md support alongside the older .cursorrules convention. See the Cursor changelog for the version where it landed.
• Personal AGENTS.md files: ~/AGENTS.md and per-project AGENTS.md files in client repos, referenced throughout the post.
• Multi-agent convention discussions: see agentsmd.dev and the open-source community write-ups on agent instruction file conventions for context on the convergence story.