We just want to make it possible to work with the same instructions in our codebase across Claude, Cursor, Pi, Copilot, Codex, and the rest without having that knowledge duplicated everywhere. Additionally, we want to support custom instructions per user, extending the shared defaults. If one colleague wants to try <a href="https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md" target="_blank" rel="noopener nofollow">Karpathy’s CLAUDE.md</a>, and another wants the linter to run after every edit, that should just work.
I would have assumed this was a solved problem by now. Follow a standard or import a library, done.
It’s not.
<h2>Introducing AGENTS.md (I guess)</h2>
The closest thing to a shared standard, where you can put instructions for your codebase, is <code>AGENTS.md</code>. Most coding agents will load and follow an <code>AGENTS.md</code>, except, of course, Claude Code. 🙄
Anyway, we got that sorted as well, because Claude Code allows you to import other instructions which will automatically be inlined with an <code>@</code> command, so now our <code>CLAUDE.md</code> just looks like this:
<pre><code>@AGENTS.md
</code></pre>
<h2>Local Instructions Are Broken</h2>
Now that we have one central file for all coding agents, we want the devs to be able to have their own instructions as well. And the first thing we found that works really well is <code>CLAUDE.local.md</code>. Add it to the <code>.gitignore</code> file and you are good to go, but you guessed it from the name already: this only works for Claude again. So we looked up if you can have an <code>AGENTS.local.md</code>, and it turns out that you sadly cannot.
So now our private setups involve creating instruction files like this:
<ul>
<li><code>CLAUDE.local.md</code></li>
<li><code>.cursor/rules/*.local.mdc</code></li>
<li><code>~/.codex/AGENTS.md</code></li>
<li><code>~/.pi/agent/AGENTS.md</code></li>
<li><code>~/.gemini/GEMINI.md</code></li>
</ul>
These all do roughly the same thing, but in slightly different ways, in slightly different places. Some will apply globally to all projects the dev has on their machine, as they are placed as children of their home directory, while others will not.
<h2>Conclusion</h2>
This setup sucks. There’s no real standard. No clean abstraction. Just a set of conventions that you have to piece together yourself.
Also, there’s surprisingly little discussion about this. Try searching for it and you mostly find surface-level setup guides or AI-generated content that doesn’t go beyond “create an AGENTS.md”.
So I’m curious:
How are you solving this?

Fabian Letsch

Managing coding agent instructions across multiple tools (Claude Code, Cursor, Copilot, Codex, Gemini, Pi) in a shared codebase is surprisingly unsolved. AGENTS.md is the closest thing to a standard, but Claude Code doesn't support it natively — requiring a workaround using its @-import syntax. Per-user local instruction files also lack a unified standard, forcing developers to maintain separate files in different locations for each tool. The post calls out the fragmentation and lack of community discussion around this problem, ending with an open question about how others are handling it.

Many Coding Agents. One Codebase. How?

A very real problem indeed. Even I am wondering why there is no standard yet.
What I have done is create a folder at the root level of the repo, which contains instructions divided into multiple files. Then, using markdown links linked those instruction files to coding agent-specific instruction files. It kinda works.

We made a “docs” folder, that contains all kind of informations related to the project, like <a href="http://architecture.md" target="_blank" rel="noopener nofollow">architecture.md</a> , <a href="http://rules.md" target="_blank" rel="noopener nofollow">rules.md</a>. The main <a href="http://AGENTS.md" target="_blank" rel="noopener nofollow">AGENTS.md</a>/CLAUDE.md just reference them with a small explanation like:
<code>docs/architecture.md - read this when...</code>
The real pain is that, as you said, there is no real standard yet, so we are not sure how much time and effort to put into this…sad.

We need ask AI about this situation

We need the equivalent of <code>.editorconfig</code> for AI agents. Shared defaults, local overrides, predictable behavior across tools.

A very important issue has been raised. Until AGENTs standardize a common API, there will be confusion. Personally, I collect a set of prompts in the “_prompts” folder (sys, rols, tsks, schms…).