[FEATURE REQUEST] Allow making `CLAUDE.md` configurable

Supporting multiple guideline documents could also be convenient, for instance to separate coding standards from lifecycle procedures.

It would be nice if agents.md became the standard. There are lots of agents now, and as you point out, the number of config files is getting out of hand.

Codex uses AGENTS.md. For those of us who use various AI tools it would be extremely helpful to consolidate on one file with product-agnostic naming

AGENTS.md has become a standard. Cursor now uses it too. CLAUDE.md should definitely be moved to AGENTS.md as they serve exactly the same purpose.

I create an AGENTS.md and symlink it to CLAUDE.md and .github/copilot-instructions.md. You can't do anything about GitHub's bad choices, but the CLAUDE.md step should definitely be removed.

Cursor now uses it too

Can you provide a link to docs?
I was not familiar with this and can't find any documentation on it.

Can you provide a link to docs? I was not familiar with this and can't find any documentation on it.

Apparently not. All I can tell you is that in my Cursor thought process with Claude 4 Thinking, it checks AGENTS.md very early, including if it doesn't exist. And that has to be Cursor itself, because otherwise it would be CLAUDE.md.

I have no references to AGENTS.md anywhere in my rules (in fact, when I saw it check it, it didn't even exist).

Frankly, I don't care which file we standardise on, as long as we standardise on one. AGENTS.md is the only option which aims to be agnostic of the system reading it.

Looks like opencode supports AGENTS.md.
Gemini defaults to GEMINI.md but the name is configurable to AGENTS.md

Here's the corresponding issue for Gemini - raised internally by Googlers prior to launch. Disappointingly it was closed on the basis that it's configurable. There's also a popular discussion.

I think the gemini approach is good: using a .claude/settings.json with a parameter to specify the path (directory + filename) of the EGO file.

personally I create _docs folder with a llm.md as EGO file and all the other md documentation around

+1 on this feature request—making CLAUDE.md configurable would greatly improve flexibility and reduce duplication, especially as developers increasingly use multiple AI coding agents.

To build on this, I strongly support adopting the Agent Rules standard, which proposes a unified AGENTS.md file in the project root for natural language guidelines that can be shared across tools. This minimalist spec, inspired by SemVer, EditorConfig, and Conventional Commits, allows agents like Claude Code to incorporate rules without tool-specific silos. For instance, it's already natively supported in OpenAI's Codex CLI and easily configurable in Aider (via the --conventions-file AGENTS.md flag or .aider.conf.yml).

Benefits include:

• Interoperability: Define rules once (e.g., coding styles, security practices) and reuse them seamlessly across agents like Claude, Aider, Cline, or GitHub Copilot.
• Scalability: Avoids the proliferation of files (e.g., no need for separate CLAUDE.md, CONVENTIONS.md, etc.), aligning with your point about leveraging existing human docs like README.
• Community Momentum: Early adopters like Aider show how simple config tweaks enable this, fostering a more cohesive ecosystem without breaking existing setups.

For the full spec and examples, check out https://agent-rules.org/. Implementing support for AGENTS.md (e.g., as a fallback or configurable option alongside CLAUDE.md) would be a low-effort way to enhance Claude Code's usability—happy to discuss or contribute if helpful!

(Disclaimer: I am the maintainer of https://agent-rules.org/)

(Disclaimer: I am the maintainer of agent-rules.org)

I love that you've tried to formally standardise this. It would be great for all manner of reasons.

In addition, having a standardised format would mean the agent could more effectively use the rules file, and actually maintain attention to the rules throughout the conversation without throwing away too many tokens. And it would let us avoid horrible XML; Markdown rules are much more sensible.

Is the spec open-sourced anywhere? I might try writing a formalised structure for AGENTS.md in addition to specifying the filename, and dropping a PR.

But to sum up @sgryphon - great project, 10/10, no notes.

Please tag me by username in any reply, so it's properly surfaced.

@sgryphon Never mind, I've found the repo and forked it. I'll have a look at writing something when I get the chance. It'll need some editing - I've never written standards before, though I've read plenty of RFCs so the use of SHOULD etc is familiar (and that was a good addition).

I've based the standard on editorconfig / conventional commits / semver, and tried to deliberately keep it as lightweight as possible so that it can be supported by pretty much any tool in parallel with whatever more complicated specific rule / actions system they want.

I think it's good to have a variety of different more advanced approaches, but it is annoying when a tool uses the wrong testing tool or something, because it doesn't know the very basics. Currently I see teams using a variety of different editors and other tools, and I think agents will be similar.

The hard part is actually picking/agreeing on the standard. AGENTS.md is a generic name, and already used by two tools - ChatGPT Codex (small now, but arguable ChatGPT is big) changed from a custom name to a generic name, so they kind of picked it. Only one tool (OpenCode) I think supports it natively, but there have been dicussions in Gemini who decided to make it configurable, so it is usable but not the default (but that's an easy thing to fix). Aider is also configurable.

So, having 4 usable tools (2 requiring config) is better than any other file name, so I went with that (but open to reasonable argument).

Any thoughts from Anthropic on this?

To build on this, I strongly support adopting the Agent Rules standard, which proposes a unified AGENTS.md file in the project root for natural language guidelines that can be shared across tools. This minimalist spec, inspired by SemVer, EditorConfig, and Conventional Commits, allows agents like Claude Code to incorporate rules without tool-specific silos. For instance, it's already natively supported in OpenAI's Codex CLI and easily configurable in Aider (via the --conventions-file AGENTS.md flag or .aider.conf.yml).

-1 for this from my understanding of the current Agent Rules Standard.

The agent rules standard appears to specify a single AGENTS.md file at the root of the project.

I'm not opposed to the name AGENTS.md, but as a heavy utilizer of hierarchical CLAUDE.md files I would not want to give up that capability.

I'm not opposed to the name AGENTS.md, but as a heavy utilizer of hierarchical CLAUDE.md files I would not want to give up that capability.

Legit criticism, but something I feel would be better served by a PR to the fledgling standard.

The agent rules standard appears to specify a _single_ AGENTS.md file at the root of the project.

The minimum requirements to comply with the standard is, yes, a single AGENTS.md file at the root.

Many people also rely on Claude actions, or Roo Code modes, or metadata / file glob filters (cursor/ continue.dev).

Adding one extra standard context file doesn't take away or prevent using all those competing alternative approaches.

Some of the tools that already support AGENTS.md do in fact support hierachical files, i.e. looking in the current folder and the project root.

While having multiple files may be essential for some projects, for many others a single file will suffice.

So, for version 1.0 of the standard I think it better to simply require support of a single root file. Almost every current tool out there should be able to add support for that with a trivial change.

Maybe a v2.0 can have additional requirements, possibly forcing some tools a choice between staying at v1, or adding the ability to load hiearchical files and also support v2.

This is how the new Gemini CLI solved this issue, just by adding this key to .gemimi/settings.local to give any name to the context file:

{
"contextFileName": "MY_NAME.md"
}

It's elegant, it's simple, it just works.
In my case, hironically, I actually gave Gemini CLI my CLAUDE.md as context file, because Claude Code cannot accept any other filename, and I wanted to have a unified context file for my repo.

AGENTS.md is now supported by even more, including several major systems: OpenAI Codex (default), Github Copilot (fallback), and Google Gemini (configurable).

It is also supported by at least: Aider, Factory AI, Kilo Code, OpenCode, Phoenix, and Roo Code.

A note for those of us who do the symlink dance:

Make .github/copilot-instructions.md your canonical file. Copilot (even locally) can't resolve symlinks. Symlink CLAUDE.md and AGENTS.md to .github/copilot-instructions.md as I'm yet to find a tool which uses them which has issues with the symlinks.

Also explain the symlink structure in your context file, so that the model doesn't get horribly confused when updating documentation. Claude Code doesn't really suffer from this, but other tools definitely do.

Make .github/copilot-instructions.md your canonical file.

Why? AGENTS.md is now supported by Github Copilot (as it is by OpenAI Codex and Google Gemini). Claude is one of the remaining major tools that doesn't support it yet (except via a symlink).

But having Claude natively support it (or even a configurable file like Gemini) would be better.

@sgryphon Can you verify this with documentation? I'd love to be able to throw away one of my symlinks.

@sgryphon Can you verify this with documentation? I'd love to be able to throw away one of my symlinks.

Yep. I reference the specific docs on https://agent-rules.org/ as I discover them.

https://docs.github.com/en/enterprise-cloud@latest/copilot/tutorials/coding-agent/get-the-best-results#adding-custom-instructions-to-your-repository

... But I just checked it, and it's not there.

Because the doco was changed 20 hours ago (see deleted line 119):

https://github.com/github/docs/commit/16236c34e0a292dbb6767c9d35c8caab853f856e#diff-17599f3681411e871642d08199431a61de0dba3ba7dd6a472e91e895699609dbL119

So that means either they changed their mind, or the doco might have been wrong. Either way it's not clear now if Github Copilot supports fallback or not.

So that means either they changed their mind, or the doco might have been wrong. Either way it's not clear now if Github Copilot supports fallback or not.

@sgryphon Piss. Round and round we go. Thanks for the spot even if it did turn out to be reversed.

Yeah, after finding the reference, I feel like it's a bit of a rug pull ... but maybe it was unintentional and they were just cleaning up /moving doco around and it got a missed. I raised an issue in theirs docs repo, and tagged some of the users involved, to see if I can get a clear answer.

I might also do some testing to see what works.

Abide by https://agents.md/

AMP has changed to use AGENTS.md, and Cursor is listed as supporting the standard (although I haven't found the documentation to support that).

That makes 12 tools now supporting it (not counting Github Copilot). The agents.md website lists 6, and I have a PR raised with the other 6 with confirmed support.

It would be great to be able to add Claude to that list.

As ever, +1.

And though I can't share documentation either, I can confirm from experience that Cursor checks AGENTS.md very early in a thread.

Thank you for the suggestion! You can @-import any file from your project or user CLAUDE.md to help you organize the instructions you send to claude

That really doesn't feel like it resolves the issue

@levpopov Yeah. This was about changing the context file name to match everything else, not setting up imports.

We either need a statement that CLAUDE.md is WONTFIX, or we need to talk about changing the context file name.

Thank you - definitely open to more feedback here. @-import'ing agents.md (or README.md, etc), from CLAUDE.md would let you avoid any duplication/instruction drift. In other words, your CLAUDE.md becomes a single line with the import statement. Curious - could you elaborate why .claude/settings.json configuration would be preferable to you?

@levpopov: @philip-updoc's response here https://github.com/anthropics/claude-code/issues/995#issuecomment-3215405049 echos my concerns:

The problem for our team is that we're forced to create a Claude-specific CLAUDE.md all over the place. It would be one thing if this was a dotfile, but it's an uppercased, non-dot file that appears all over the place. This becomes more problematic because different people use different agents/editors, each with their own configuration file, meaning many of our directories are now filled with CLAUDE.md, AGENTS.md, .cursorrules, etc. We're using the import mechanism to consolidate the underlying definitions but the file pollution is the concern here. I hope that makes sense!

It also feels like your using my projects to advertise your product (that I'm paying to use), which leaves a bit of a bad taste in the mouth.

@levpopov I think you're missing the gist of this thread - that CLAUDE.md should become AGENTS.md as used by myriad other tools. I'm not sure where you got .claude/settings.json from.

We either need a statement that CLAUDE.md is WONTFIX

This is my impression also. An import is not the same as changing the default file.

@levpopov Is there a reason behind not changing this?

In addition to all the other good reasons: this gives OpenAI excuse to keep your company's name off the AGENTS.md page, because while you pioneered the idea, there's currently no way to support it in your tool. I'm not sure your marketing team would thank you for that.

If you want to keep using CLAUDE.md as default, and deviate from what is becoming a standard, up to you 🤷🏻‍♂️

But I see no reason why you shouldn't make it configurable.

ie: OpenCode let you add this "instructions": ["CLAUDE.md"], to their ~/.config/opencode/opencode.json so you can add as many other locations as you want.

I hope AGENTS.md will be the only one used.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.