Choose other name for "CLAUDE.md"?

I would love to see this to avoid the proliferation of agent specific files in each of my projects. It would be awesome to see some cross-agent agreement on files that are read.

This doesn't directly address your issue's title, but as of v0.2.107, "CLAUDE.md files can now import other files. Add @path/to/file.md to ./CLAUDE.md to load additional files on launch". Does this feature address your needs?

@dicksontsai thank you, but not really. The idea is that in this fast-changing AI landscape we're constantly trying different AI coding tools. General sense is to start treating AI agents as humans that need clear explanation of the design choices, etc. So making design documents / style guidelines / instructions makes sense in general, regardless of what tool is used. And idea is to work on these documents that can be used by any of the AI coding tools. Being forced to include file CLAUDE.md into the codebase just feels very wrong and if this behaviour will be picked up by other agents, then codebase will quickly be filled with <YET_ANOTHER_AI_AGENT.md> files.

It would be great if Anthropic leads here with some standards for AI-oriented project documentation, but ultimately the choice of the filename should be in the developers' hands.

I regularly use both Claude and Cursor.
A standardized agent documentation format/structure would be nice to avoid CLAUDE.md vs cursor rules duplication

This doesn't directly address your issue's title, but as of v0.2.107, "CLAUDE.md files can now import other files. Add @path/to/file.md to ./CLAUDE.md to load additional files on launch". Does this feature address your needs?

but at least it would limit the Claude.md file to @ai.md

One thing to consider is that there isn't necessarily a single CLAUDE.md in a repo.

As noted in the best practices doc you can have hierarchical CLAUDE.md files:

<img width="730" alt="Image" src="https://github.com/user-attachments/assets/830aa848-e5a0-42a7-b5b3-fb1914f4a568" />

One thing to consider is that there isn't necessarily a single CLAUDE.md in a repo.

Sure but they all could be configurable as to what name you use. agent.md ai.md bobsyouruncle.stuff

I'm trying claude code today, but for me that's already a reason to no keep using it. No way I'm going to add files with different names with the same content for each AI tool I want to use. That should be configurable and not trying to vendor lock people. We already know where this kind of things leads, and it's never in customer interest.

As a work-around, it seems that e.g. this works ok:

ln -s .rules CLAUDE.md

As a work-around, it seems that e.g. this works ok: ln -s .rules CLAUDE.md

Then CLAUDE.md needs to be added to .gitignore, and this is not always possible as it must pass code review. Imagine I work on any big open source project, and I want to modify .gitignore because of this. Imagine I work on Gnome, and I ask them to place CLAUDE.md or to add it to gitignore in this repo https://github.com/GNOME/gnome-desktop. I see 0% chance they agree.

The more feasible workaround is to have a parent directory for each repo just to keep CLAUDE.md there, and this is soooo inconvenient to dig through additional directories just to keep one file there.

If README file is well written, it might be a good case to point claude to use it instead of CLAUDE.md, and README does not need to be gitignored.

There are often files like CODE-STYLE.md which also could serve the needed role.

@kneczaj you could use .git/info/exclude instead of .gitignore. See https://git-scm.com/docs/gitignore

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 would be perfect and is what Codex CLI uses.

AGENTS.md would be perfect and is what Codex CLI uses.

It's also becoming a standard as per #1091 and https://agent-rules.org/

But yes, we should have _both_:

• a standardized default which all agents use, and
• the ability to configure it.

Better, abide by https://agents.md

Our recommendation for this is to use imports to configure Claude Code memory. You can put "Read @AGENTS.md for more info" in the CLAUDE.md to configure Claude Code.

@rboyce-ant 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!

@rboyce-ant Imports seem to be problematic, see https://github.com/anthropics/claude-code/issues/3377

What is the rrationale behind not allowing to make this configurable?
Related: https://github.com/anthropics/claude-code/issues/1091#issuecomment-3215229395

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.