One codebase, every coding agent, no shared standard

Our team uses a mix of Claude Code, Cursor, Copilot, Codex, Pi, and a few others. We just want one place to write down how AI agents should work in our codebase. Coding conventions, "run the linter after every edit," "don't touch the migrations folder," that kind of thing. Plus a way for individual devs to layer their own preferences on top, so one colleague can try Karpathy's CLAUDE.md and another can have the linter fire after every edit, without either of them stepping on the team config.

I assumed this was a solved problem by now. Pick a standard, drop in a file, done.

Reader, it is not.

#AGENTS.md, sort of

The closest thing to a shared standard is AGENTS.md. Most coding agents will pick it up and follow it. Cursor, Codex, Copilot, Pi, Gemini.

Most. Not Claude Code, of course. Claude Code wants its own file: CLAUDE.md.

The workaround is genuinely fine, to be fair. Claude Code supports @-imports, so your CLAUDE.md can be exactly one line:

@AGENTS.md

Both worlds now load the same instructions. We're one yak shave deep and shared config works. Acceptable.

#Personal instructions, on the other hand

The harder part is per-developer config. The stuff you don't commit. Personal aliases, experimental rules, that one colleague's preferred prompt style. None of it belongs in the shared file.

For Claude Code this is easy: CLAUDE.local.md, add it to .gitignore, done.

You can guess where this is going. AGENTS.local.md is not a thing. So if you want personal instructions that work across agents, you're now juggling:

CLAUDE.local.md              # project-scope, Claude Code only
.cursor/rules/*.local.mdc    # project-scope, Cursor only
~/.codex/AGENTS.md           # global, Codex only
~/.pi/agent/AGENTS.md        # global, Pi only
~/.gemini/GEMINI.md          # global, Gemini only

Same idea, five places, three different scopes (project, global, or wherever-this-tool-decided), no overlap between them. Change your mind about one preference and you're updating it in five files. Forget one and your agents disagree with each other mid-task.

#So what is this, really

It's conventions stacked on conventions. No real standard, no clean way to layer shared and personal config, no abstraction over where each agent looks for what. Every new agent adds another path to remember.

The strange part is how little discussion there is about it. Search around and you mostly find surface-level setup guides or AI-slop posts that don't go past "create an AGENTS.md."

I can think of two ways this gets better. Someone writes a small CLI that owns all of these files and syncs them from one source of truth. Or AGENTS.md actually wins as a standard and the holdouts adopt it, including a local-override variant.

Curious how others are dealing with this. Are you just eating the duplication, or have you found something cleaner?

— Bassam