Feature Request: Support AGENTS.md.

The naming, "agents.md" a bit confusing given subagents are defined as "agents."

Feature Request: Support AGENTS.md as a Fallback for Enhanced Interoperability

Is this a bug report or a feature request?
This is a feature request.

Problem Statement

Claude Code's CLAUDE.md memory system is a powerful feature for providing project-specific context. However, as the AI agent ecosystem matures, a simple open standard, AGENTS.md, is gaining significant traction. It's used by over 20,000 open-source projects and supported by a growing number of AI coding tools.

Currently, if a developer using Claude Code clones a repository that provides an AGENTS.md file, that context is ignored. The developer must manually create a CLAUDE.md file and duplicate the instructions, creating unnecessary friction and a missed opportunity for Claude Code to be instantly effective on a new project.

Proposed Solution

I propose that Claude Code adopt a dual-file approach that prioritizes its native format while gracefully falling back to the open standard. This would offer full backward compatibility while dramatically improving interoperability.

The lookup logic would be as follows:

1. Check for CLAUDE.md First: When claude is launched in a project directory, it first searches for a CLAUDE.md file.
2. If CLAUDE.md is found: Load its contents into context and stop. The AGENTS.md file is ignored. This ensures that projects optimized for Claude Code continue to work exactly as expected, with their specific instructions taking precedence.
3. If CLAUDE.md is NOT found: Proceed to check for an AGENTS.md file in the same directory.
4. If AGENTS.md is found: Load its contents into context. This provides a robust baseline of instructions for projects that follow the open standard.
5. (Optional Suggestion): Upon loading AGENTS.md, Claude could provide a subtle one-time message to inform the user:

> AGENTS.md found and loaded. For instructions tailored specifically to Claude Code, you can create a CLAUDE.md file.

This simple, non-breaking change would make Claude Code a better citizen in the broader AI development ecosystem.

Detailed Breakdown of the Dual Approach

This system creates a clear and logical hierarchy for agent instructions.

Primary Source: CLAUDE.md (Claude-Specific)

• Role: This remains the primary, native instruction file for Claude Code.
• Content: It is the ideal place for instructions that leverage Claude Code's unique features, such as invoking specific sub-agents, configuring MCP servers, or defining complex, multi-step workflows with Claude-specific slash commands.
• Precedence: Its presence overrides AGENTS.md, guaranteeing that Claude-tailored instructions are always followed.

Secondary Source: AGENTS.md (General Standard)

• Role: This acts as a universal fallback, providing essential, agent-agnostic context.
• Content: It typically contains general setup commands (pnpm install), testing instructions (pnpm test), and code style guidelines that are useful for any coding agent.
• Benefit: It allows Claude Code to have immediate, zero-configuration context on tens of thousands of projects without requiring any action from the user or the project maintainer.

Use Cases and Benefits

1. Seamless Onboarding to Open-Source Projects:

• Current: A developer clones apache/airflow, sees an AGENTS.md, and has to manually create CLAUDE.md to make Claude Code aware of the build steps.
• Proposed: The developer clones the repo and runs claude. The tool automatically finds and loads AGENTS.md. The developer can immediately ask, "Run the tests for the core package," and Claude knows what to do.

1. Improved Interoperability in Mixed-Tool Teams:

• Current: A team uses multiple AI agents. They must either maintain separate instruction files (AGENTS.md, CLAUDE.md, etc.) or accept that some agents will lack context.
• Proposed: The team maintains a single AGENTS.md as a source of truth for all agents. Claude Code can use this shared file, and if the team later decides to add Claude-specific optimizations, they can simply add a CLAUDE.md file without breaking the setup for other tools.

1. Full Backward Compatibility:

• This change is entirely non-breaking. Any project that currently uses CLAUDE.md will continue to function exactly as it does today, as CLAUDE.md is always checked first.

By implementing this dual approach, you would significantly lower the barrier to using Claude Code effectively on a vast number of existing projects, reinforce its position as a collaborative tool, and embrace the benefits of an open standard without sacrificing the power of its native features.

Thank you for considering this proposal.

https://agents.md

https://github.com/openai/agents.md

_A simple, open format for guiding coding agents, used by over 20k open-source projects._

Does anybody have any workarounds in the meantime? I find myself duplicating the contents of CLAUDE.md/AGENTS.md and cursor rules just so I can have consistent memory as I move across tools.

Hey, I totally agree this would be a great feature to have. I've run into the same issue trying to keep agent instructions consistent between Claude Code, Cursor, and a few other tools that are starting to adopt AGENTS.md.

In the meantime, I've found a pretty good workaround using Claude Code's import functionality. The CLAUDE.md file can actually import other files.

You can just create a CLAUDE.md in your project root with this single line:

# In ./CLAUDE.md
@AGENTS.md

This tells Claude Code to load the full contents of your AGENTS.md file as part of its memory. It effectively treats AGENTS.md as its primary instruction set for the project.

This way, you can maintain AGENTS.md as the single source of truth and you don't have to duplicate any instructions.

Hope this helps you out until there's official support for the standard

Another workaround (that works on macos and linux at least) is to create symbolic link CLAUDE.md that refers to AGENTS.md using ln command. @Zerquix18 @coygeek

If you want a more fluid experience and to achieve consistency (consistency refers to being able to access the AGENTS.md in each directory in repo), you can use hooks to automatically add all AGENTS.md files in the repository to the context at each Session Start.

.claude/settings.json

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/append_agentsmd_context.sh"
          }
        ]
      }
    ]
  }
}

hooks/append_agentsmd_context.md

#!/bin/bash

# Find all AGENTS.md files in current directory and subdirectories
# This is a temporay solution for case that Claude Code not satisfies with AGENTS.md usage case. 
echo "=== AGENTS.md Files Found ==="
find "$CLAUDE_PROJECT_DIR" -name "AGENTS.md" -type f | while read -r file; do
    echo "--- File: $file ---"
    cat "$file"
    echo ""
done

@coygeek @parfenovvs

Note that VS Code is working on this too for Copilot. It's on their Aug milestone.

Using the hook @DylanLIiii created, I changed $CLAUDE_PROJECT_DIR to ~ and saved these for the user so I don't have to add this to each project.

Without this standard, we had to create a LLMs.md and a bunch of symlinks in the Apache Superset repo for CLAUDE.md, GEMINI.md, and whatever Cursor and other tools expect. Ideally CLAUDE.md would be for Claude Code specific rules like "always use {claude-specific thing}!". Seems precedence in context injection should be AGENTS.md first and CLAUDE.md next, so it goes general-to-specific in the context window.

Also note that you probably don't want to repeat yourself here and burn context, so Claude Code should probably tell the user if/when the context is duplicated across AGENTS.md and CLAUDE.md ...

Ideally /initwould ask where you want to store the output and be smart and not duplicating info when AGENTS.md is present...

Also the # shortcut (for memory) probably need to ask you whether you want to add in AGENTS.md if/when present.

I hope the team won't ignore it and adopt it ASAP to show the will to make the right decisions rather than ones that benefit the business. It is a small issue, but because of that it is telling.

I did notice this when I added a memory this morning. I am using a _CLAUDE.md_ that simply @ includes _AGENTS.md_ at the project level.

<img width="528" height="182" alt="Image" src="https://github.com/user-attachments/assets/911a9538-d067-44d1-9df5-a9b51f36f18a" />

Another workaround ... is to create symbolic link CLAUDE.md that refers to AGENTS.md using ln command.

That may not work if the AGENTS.md file references other MD files via @ and CLAUDE.md and AGENTS.md are not at the same level in the file system

I don't see why not adopt the generic AGENTS.md file like all other tools in the market are doing. I really hope it's not a case of NIH that's blocking its adoption.

+1

Please stop these idiotic +1 comments which spam everyone that is subscribed to the thread for actual news.

Just put your vote on the thumb up in the parent post, like 181 other people before you. Thanks!

+2

any updates? I would love to have it!

It would be great if agent developers could agree on a common standard for this. And I think Claude Code could be a pioneer by implementing this.

This is very much needed

It would be great if agent developers could agree on a common standard for this. And I think Claude Code could be a pioneer by implementing this.

Except for Claude Code I can't think of a single agent I have installed that doesn't support AGENTS.md at this point, hardly a pioneer at this point. It's getting old that it doesn't support it out of the box or allows me to override it with a setting or command line argument (i.e without using the @AGENTS.md hack).

This works, without messing up the memory feature (@AGENTS.md as CLAUDE.md content body would).

ln -s AGENTS.md CLAUDE.md
# bonus:
# ln -s AGENTS.md GEMINI.md

It's really bad idea to name it as AGENTS.md, it cause me to have hallucinate this is a project-level agent.

However, it's not, it's just a context markdown. it's conflicting with how claude code is naming sub-agents.

I am curious how claude code would respond to this request. but I know what claude code does now make sense.

insane that i've memorized ln -s AGENTS.md CLAUDE.md,
that's free rent in my head for a command that should've probably been a feature a couple of weeks ago.

maybe this is actually a really complex feature and i just don't get it, but i'm not sure why this isn't at least optional through an _⋆˙⟡ environment variable ✧˖°._

maybe this is actually a really complex feature and i just don't get it, but i'm not sure why this isn't at least optional through an ⋆˙⟡ environment variable ✧˖°.

It's very likely a business driven decision not to support this. CLAUDE.md serves as a network effect every time someone opens a github repo and sees it. It's the same thing with claude code attribution in your commit history.

It also subliminally pressures other developers on your team to use claude code over whatever other tool they might otherwise want to use, if they see CLAUDE.md present already.

This is a competitive advantage for anthropic, which I doubt they'll give up voluntarily, even if it makes the experience worse for their customers.

I hope they prove me wrong.

In my repo I've added: sync-claude-md.sh

#!/usr/bin/env bash
#USAGE: symlinks CLAUDE.md to AGENTS.md all over the codebase

set -euo pipefail

# Recursively ensure that for every AGENTS.md (outside .gitignored folders),
# there is a CLAUDE.md symlink pointing to it. Also remove any orphaned
# CLAUDE.md files that do not have a sibling AGENTS.md.

REPO_ROOT="$(git rev-parse --show-toplevel)"
cd "$REPO_ROOT"

log() { printf '%s\n' "$*"; }

# 1) For each AGENTS.md, create/update CLAUDE.md symlink next to it
while IFS= read -r -d '' path; do
  base_name="${path##*/}"
  [ "$base_name" = "AGENTS.md" ] || continue
  dir_path="$(dirname -- "$path")"
  # Ensure relative link target so it remains stable across machines
  (
    cd "$REPO_ROOT/$dir_path"
    ln -sfn "AGENTS.md" "CLAUDE.md"
  )
  log "Linked: ${dir_path}/CLAUDE.md -> AGENTS.md"
done < <(git ls-files -co --exclude-standard -z)

# 2) Remove orphaned CLAUDE.md that do not have a sibling AGENTS.md
while IFS= read -r -d '' path; do
  base_name="${path##*/}"
  [ "$base_name" = "CLAUDE.md" ] || continue
  dir_path="$(dirname -- "$path")"
  if [ ! -f "$REPO_ROOT/$dir_path/AGENTS.md" ]; then
    rm -f -- "$REPO_ROOT/$path"
    log "Removed orphan: $path"
  fi
done < <(git ls-files -co --exclude-standard -z)

It's very likely a business driven decision

Clearly "business incentives" is a factor, but there some key change-management considerations around getting this right too. In all the repos out there ,there are various combinations:

• CLAUDE.md
• CLAUDE.md + AGENTS.md (dup content, or symlinked)
• AGENTS.md only
• AGENTS.md + CLAUDE.md with CLAUDE-specific instructions augmenting the AGENTS.md

In https://github.com/apache/superset we currently symlink CLAUDE.md -> AGENTS.md. I'd hate for the new behavior to just change and read both, doubling the context weight (repeating it twice).

Anyhow, awaiting instructions as to how to best welcome all agents to our repo. Seems the easiest thing would be for CC to look for both files and just take precedence: "if both files are there, we bring CLAUDE.md over AGENTS.md in context".

Also as I mentioned before, what should /init do? Ask you where to put the ouput?

---

Interestingly too, looking at the various "prompting guidelines" published around the different agentic coding tools, it could be that different agents evolve to perform better given diverging inputs. Some tools might be better at "just-in-time context retrieval" and others do better with very large context dumps...

For other folks thinking deeply about "context segmentation" and "context density", it seems it makes sense to start structuring all this context in a "universal" (as opposed to tool-specific) set of files, maybe under AGENTS/, and either instruct various agentic tools to read directly from there, or ask agents to re-materialize or "compile" these source files into their own specific/preferred structures (say .claude/* ...).

Going back to the core issue of vendors having misaligned incentives around supporting standards: waiting for vendors to come up with a universal standard or framework for context engineering probably is backwards. It could be great if an independent source was to propose a universal framework for structuring/organizing context, call it "context engineering segmentation framework 1.0", and then for users to push vendors into supporting this agreed-upon standard. Clearly AGENTS.md is a good step forward, but comes way short of providing what we're going to need in this area.

OMG! Guys, this shouldn't be hard to add and looks like a product/business decision (a bad one!), so switch to another tool and come back when they prioritize UX over trying to lock people in or sneakily market CC.

As mentioned in https://github.com/anthropics/claude-code/issues/6235#issuecomment-3217884068, since CLAUDE.md supports @-references you can have a CLAUDE.md that just contains @AGENTS.md. But that's not a complete solution because I'd want /init to update AGENTS.md too.

Is this fixed for claude code 2.0?

As mentioned in #6235 (comment), since CLAUDE.md supports @-references you can have a CLAUDE.md that just contains @AGENTS.md. But that's not a complete solution because I'd want /init to update AGENTS.md too.

The agents.md spec actually has a hierarchy of AGENTS.md files in subdirectories as well, so that's only a partial solution.

When we will have it?

* CLAUDE.md + AGENTS.md (dup content, or symlinked)

this is what I'm going with for now, but ideally CC would just work with AGENTS.md

Sorry Anthropic, CLAUDE.md is no longer the source of truth, AGENTS.md is.

Eventually CLAUDE.md will end up up a symlink to AGENTS.md.

Not supporting AGENTS.md is not a business decision, it is pettiness.

This should be configurable, per the Gemini example:

{ "contextFileName": "AGENTS.md" }

Claude is awesome, no doubt. But not supporting this standard is just pushing me really hard to other models.

Use CLAUDE.md for backwards-compatibility or even as the defacto, but also support AGENTS.md as a standard. If one is a symlink to another (easy to check), then just include one of the two (same goes for sub-agents, duplicate symlinked files should never be included in context twice). If they both exist and are different, prefer just CLAUDE.md but allow the user to force including both in .claude/settings.json or .claude/settings.local.json with a setting like contextFileName as suggested above or includeAgentsMd: true to enable including both.

All bases covered. 👍

TL;DR: AGENTS.md isn't a standard, please tone down the rhetoric.

(I'm not targeting this at Collin or anyone else on this thread in
particular. Please don't take it personally.)

I want this feature as much as everyone on this thread, but y'all need to
calm down a bit with the whole AGENTS.md thing being a "standard". Their
own website says it is "A simple, open format for guiding coding agents,
used by over 20k open-source projects." The 20K number is a count from
github of how many projects have an AGENTS.md file. By comparison, there
are almost 5x more projects that have CLAUDE.md.

A better measure would be how many tools actually support reading the
format. And the answer, per the AGENTS.md website, is 14
<https://github.com/openai/agents.md/blob/main/components/CompatibilitySection.tsx>
.

And keep in mind that the AGENTS.md proposal itself is only a few months
old.

I do think it may become a standard, but I suspect it will take a year or
more of adoption, evolution, discussion, and, alas, politics. This is
remarkably fast for a standard, by the way. It usually takes 5+ years, but
things move quicker in AI land.

So to reiterate the most important part: I like the format, I think
standardization is needed, and I want Claude to adopt it, but saying "its a
standard!" over and over to Anthropic is likely to just make them stop
paying attention to the bug. I've seen it happen many times.

Message ID: @.***>

I don't understand why OpenAI can be so open toward MCP, even providing MCP practices and support in their official documentation: https://platform.openai.com/docs/mcp, collectively helping MCP become an industry standard that benefits everyone. Yet Anthropic is so stubborn and closed off, even regarding a guidelines file for a coding agent.

TL;DR: AGENTS.md isn't a standard, please tone down the rhetoric. (I'm not targeting this at Collin or anyone else on this thread in particular. Please don't take it personally.) I want this feature as much as everyone on this thread, but y'all need to calm down a bit with the whole AGENTS.md thing being a "standard". Their own website says it is "A simple, open format for guiding coding agents, used by over 20k open-source projects." The 20K number is a count from github of how many projects have an AGENTS.md file. By comparison, there are almost 5x more projects that have CLAUDE.md. A better measure would be how many tools actually support reading the format. And the answer, per the AGENTS.md website, is 14 <https://github.com/openai/agents.md/blob/main/components/CompatibilitySection.tsx> . And keep in mind that the AGENTS.md proposal itself is only a few months old. I do think it may become a standard, but I suspect it will take a year or more of adoption, evolution, discussion, and, alas, politics. This is remarkably fast for a standard, by the way. It usually takes 5+ years, but things move quicker in AI land. So to reiterate the most important part: I like the format, I think standardization is needed, and I want Claude to adopt it, but saying "its a standard!" over and over to Anthropic is likely to just make them stop paying attention to the bug. I've seen it happen many times. […](#)

I don't want to get too deep into a semantic battle. I prefer to bicker with LLMs!

A standard is (arguably) whatever happens to become widely accepted and adopted across an industry.

Whether orchestrated or accidental, for better or for worse... eventually something is standardised. Something is used 'as standard'.

AGENTS.md is exactly that. Standardisation already happened in august. It WILL be supported in Claude Code sooner or later.

"Anthropic" are not going to "stop paying attention" because of vocal masses proclaiming it as standard, neither will the masses STFU after being told to "tone down the rhetoric". All drops in an inevitable ocean. Mind like water!

Most likely a not-so-agnostic intern will read the well written slop-free OP and @claude yo let's support AGENTS.md as per #6235... then... as if by magic... we'll see it suddenly implemented (and eventually added to the changelog!)"

<img width="413" height="190" alt="Image" src="https://github.com/user-attachments/assets/824c9052-2b1b-458a-b114-c4bef9e5bb8b" />

This is not the way.

And the reality is, that many companies all are experimenting with their setups & providers. In my company alone, we use codex, copilot and claude. Everyone has their own budget and preferences of IDE and Integration, some prefer Github, some Cursor, some VSCode, Some Codex.

But as we all experiment, our projects all got cluttered with different files and a need for some standards arose. As we move towards defining global company rules, that no matter which setup should apply, having just 1 file there would be much more beneficial.

Anthropic is deeply unserious as always. All their goodwill in setting down standards has a financial value behind the scenes, it isn't being done out of the developers' actually running the show. Hence you will see things like this that have literally no business being made this way, but which are convenient dark patterns that lock you into their ecosystem. They will make it harder to exit out of their ecosystem and jump-switch quickly between CLI agents. In all likelihood the developers are actually not incompetent at all and did make it AGENT.md, but someone over at Anthropic with a strong executive control made them not do that because it SEOs the repositories. Grounds for a class-action lawsuit if this were a correctly functioning world.

Anthropic is deeply unserious as always. All their goodwill in setting down standards has a financial value behind the scenes, it isn't being done out of the developers' actually running the show. Hence you will see things like this that have literally no business being made this way, but which are convenient dark patterns that lock you into their ecosystem. They will make it harder to exit out of their ecosystem and jump-switch quickly between CLI agents. In all likelihood the developers are actually not incompetent at all and did make it AGENT.md, but someone over at Anthropic with a strong executive control made them not do that because it SEOs the repositories. Grounds for a class-action lawsuit if this were a correctly functioning world.

lol SEO, lol class action lawsuit

|￣￣￣￣￣￣￣￣￣￣￣￣￣￣|
|        FREE         |
|    AGENTS.md !!!1   |
|_____________________|
(\__/)  ||
(•ㅅ•)  ||
/   づ    

Man, I was complaining about overblown rhetoric before, but @oxysoft seems to be trying to win a hyperbole prize.

I believe the short term solution would be:

ln -s CLAUDE.md AGENTS.md

I believe the short term solution would be: ln -s CLAUDE.md AGENTS.md

That doesn't solve agents.md-s in subfolders. People could also try out opencode, it supports agents.md properly, is xdg compliant, and can use the same api key you have for claude code.

Nice, copilot added support for nested AGENTS.md files:
https://code.visualstudio.com/updates/v1_105#_support-for-nested-agentsmd-files-experimental

> I believe the short term solution would be: > ln -s CLAUDE.md AGENTS.md That doesn't solve agents.md in subfolders. People could also try out opencode, it supports agents.md properly, is xdg compliant, and can use the same API key you have for Claude Code.

What is opencode again?

> > I believe the short term solution would be: > > ln -s CLAUDE.md AGENTS.md > > > That doesn't solve agents.md in subfolders. People could also try out opencode, it supports agents.md properly, is xdg compliant, and can use the same API key you have for Claude Code. What is opencode again?

Did you click the link? Like Claude Code but open source and supports many other providers as well, not just Anthtropic.

https://github.com/anthropics/claude-code/issues/6235#issuecomment-3218728961

If you want a more fluid experience and to achieve consistency (consistency refers to being able to access the AGENTS.md in each directory in repo), you can use hooks to automatically add all AGENTS.md files in the repository to the context at each Session Start. .claude/settings.json { "hooks": { "SessionStart": [ { "matcher": "startup", "hooks": [ { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/append_agentsmd_context.sh" } ] } ] } } hooks/append_agentsmd_context.md #!/bin/bash # Find all AGENTS.md files in current directory and subdirectories # This is a temporay solution for case that Claude Code not satisfies with AGENTS.md usage case. echo "=== AGENTS.md Files Found ===" find "$CLAUDE_PROJECT_DIR" -name "AGENTS.md" -type f | while read -r file; do echo "--- File: $file ---" cat "$file" echo "" done @coygeek @parfenovvs

Small improvement: Replace "matcher": "startup" with "matcher": "*" so that AGENTS.md is also read after /clear.

We just added the instruction to use the AGENTS.md files in the main CLAUDE.md file like this:

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

**Note**: This project uses AGENTS.md files for detailed guidance. 

## Primary Reference

Please see `AGENTS.md` in this same directory for the main project documentation and guidance.

## Additional Component-Specific Guidance

For detailed module-specific implementation guides, also check for AGENTS.md files in subdirectories throughout the project, particularly in:

- Backend service directories
- Frontend module directories  
- Specific component implementations

These component-specific AGENTS.md files contain targeted guidance for working with those particular areas of the codebase.

## Updating AGENTS.md Files

When you discover new information that would be helpful for future development work, please:

- **Update existing AGENTS.md files** when you learn implementation details, debugging insights, or architectural patterns specific to that component
- **Create new AGENTS.md files** in relevant directories when working with areas that don't yet have documentation
- **Add valuable insights** such as common pitfalls, debugging techniques, dependency relationships, or implementation patterns

This helps build a comprehensive knowledge base for the codebase over time

For us this workaround works quite well.

or a config to use AGENTS.md instead of CLAUDE.md?

I've added this as a question in the upcoming Claude Code Q&A. Feel free to upvote it if you want to increase the chance that it gets answered. Search for "AGENTS.md" on the page to find it.

Here's how to attend the Q&A if you're interested.

We just added the instruction to use the AGENTS.md files in the main CLAUDE.md file like this:

My 2 cents would be that in that case you may as well symlink it instead of wasting tokens

I've added this as a question in the upcoming Claude Code Q&A.

I can bet they will say something stupid so this does not get implemented, or say yes they will but won't.

Someone should post this issue to hacker news or wherever, so people know how pathetic the devs on Claude Code are.

I've added this as a question in the upcoming Claude Code Q&A. Feel free to upvote it if you want to increase the chance that it gets answered. Search for "AGENTS.md" on the page to find it. Here's how to attend the Q&A if you're interested.

Did they answer the question?

If you have an AGENTS.md file, you can source it in your CLAUDE.md using @AGENTS.md to maintain a single source of truth.

This is an official recommendation.

> If you have an AGENTS.md file, you can source it in your CLAUDE.md using @AGENTS.md to maintain a single source of truth. This is an official recommendation.

Which should make it easier for them to do it by default. C'mon Anthropic.

I've been following this issue for a long time, but I haven't looked closely at everyone's content; so has it been implemented as described in the title now? Does displaying Claude code actively read Agents.md? Or do we still need to link it in CLAUDE.md?

I've been following this issue for a long time, but I haven't looked closely at everyone's content; so has it been implemented as described in the title now? Does displaying Claude code actively read Agents.md? Or do we still need to link it in CLAUDE.md?

No, you have to use the official recommendation (link it) as mentioned above.

Considering Anthropic suggests agents to have their own markdown file, does it make sense to move CLAUDE.md under the .claude directory? Otherwise, I will have more than 5 RANDOMAGENT.md files in the root of my project directory, as I use multiple agents in a single project.

I agree that agent-specific markdown files are inevitable given that each model has different characteristics, but having them all in the root directory is tricky, especially for open-source projects.

Tip: I use Claude Code mainly to write code, and my CLAUDE.md includes specific introductions to consult Codex CLI during planning phase, and it helps a lot with finding gotchas.

@AGENTS.md

- During planning, to get a critique of your solution, run: 'codex exec "YOUR_QUESTION" --config model_reasoning_effort="high"'

I have wondered about this, but I have found that my CLAUDE.md is very Claude-specific, summarizing hints and interoperability of Claude skills and sub-agents I have. It would make no sense and be useless to a coding agent (codex, gemini, etc.) that did not also inherently use skills and could spawn sub-agents in that same way. So for me, having a separate AGENTS.md (even GEMINI.md and such) helps a lot - I can tailor instructions to the less-capable AIs and avoid confusing them with Claude capabilities they lack.

Any updates on the plan to adopt Agents.md by Claude. I still did not see Claude in the list of supported platforms of Agents.md

Here is a migration guide from CLAUDE.md to AGENTS.md (symlink trick)

https://solmaz.io/log/2025/09/08/claude-md-agents-md-migration-guide/

I don't want to commit CLAUDE.md files that cite AGENTS.md by the way. That's stupid. Just give up Anthropic

Anthropic, are you choosing this hill to die on? Just let Claude prioritize CLAUDE.md > AGENTS.md but still reference AGENTS.md if it's the only one there.

There may be a need to have both. CLAUDE.md would keep the Claude-specific stuff and AGENTS.md could be keeping more general information.

In the home directory I can see keeping both.

But when we add instruction files to our code, it's especially important to do it cleanly (no extraneous symlinks) and to keep general information that's useful to any AI. Thus, for the inside of a repo, AGENTS.md should be the priority.

+1

Does anybody have any workarounds in the meantime? I find myself duplicating the contents of CLAUDE.md/AGENTS.md and cursor rules just so I can have consistent memory as I move across tools.

I just do ln -s

Would it be confusing for these CLI tools to use a TOOL or CLI Context e.g. CLI:CLAUDE or TOOL:CLAUDE, TOOL:GEMINI header of somesort in the AGENTS.md file that provides the specific context for a given tool ??

It does seem you'd need something like this. I'm ok with CLAUDE.md as its
own file. This is because I make heavy use of skills and sub-agents. Other
CLI tools (I use gemini and codex) wouldn't know what to do with these. We
need CLAUDE.md for things only Claude can do or that it does in a unique
way.

What I do is put generic instructions for the project in AGENTS.md and then
simply refer to it in CLAUDE.md once I'm done with Claude-specific
instructions. That seems to work fine; it winds up reading both.

On Mon, Nov 24, 2025 at 7:16 AM Orlando K Brown @.***>
wrote:

okbrown left a comment (anthropics/claude-code#6235) <https://github.com/anthropics/claude-code/issues/6235#issuecomment-3570504713> Would it be confusing for these CLI tools to use a TOOL or CLI Context e.g. CLI:CLAUDE or TOOL:CLAUDE, TOOL:GEMINI header of somesort in the AGENTS.md file that provides the specific context for given tool ?? — Reply to this email directly, view it on GitHub <https://github.com/anthropics/claude-code/issues/6235#issuecomment-3570504713>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AEDUGN7G3EIV5VZV35DTWST36LZI3AVCNFSM6AAAAACENXYNLCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTKNZQGUYDINZRGM> . You are receiving this because you commented.Message ID: @.***>

> Does anybody have any workarounds in the meantime? I find myself duplicating the contents of CLAUDE.md/AGENTS.md and cursor rules just so I can have consistent memory as I move across tools. I just do ln -s

It's the only sensible way, but it's also very tedious to do in nested projects with .md files spread across multiple levels. Here's a bash script to automate it: link-agent-docs.sh

<img width="417" height="463" alt="Image" src="https://github.com/user-attachments/assets/e5766318-0907-4e2d-b1f1-46ad8e1ed6dc" />

Not using Agents.MD makes it very difficult to migrate existing project to Claude as it miss defined constrains. Any recommandation?

We soooo need Agents.MD file support

Also in favor of this.

I'm currently using this In my ~/.claude/settings.json file:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "if [ -f \"$CLAUDE_PROJECT_DIR/AGENTS.md\" ]; then cat \"$CLAUDE_PROJECT_DIR/AGENTS.md\"; fi"
          }
        ]
      }
    ]
  }
}

With this no modifications (symlinks, almost empty CLAUDE.md files) are needed in your projects/repos and it seems to be more reliable/more direct than the @AGENTS.md instruction in CLAUDE.md

I'm currently using this In my ~/.claude/settings.json file: ... With this no modifications (symlinks, almost empty CLAUDE.md files) are needed in your projects/repos and it seems to be more reliable/more direct than the @AGENTS.md instruction in CLAUDE.md

@BartVB How would you get it to pick up sub-folder agent.md files?

It’s a cool hack for testing but you won’t correct large industrial
solutions like this thus the requirement of a shared standard.

You may also want to call different providers

Le sam. 29 nov. 2025 à 03:27, Danilo Alonso @.***> a
écrit :

damusix left a comment (anthropics/claude-code#6235) <https://github.com/anthropics/claude-code/issues/6235#issuecomment-3590905475> I'm currently using this In my ~/.claude/settings.json file: { "hooks": { "SessionStart": [ { "matcher": "startup", "hooks": [ { "type": "command", "command": "if [ -f "$CLAUDE_PROJECT_DIR/AGENTS.md" ]; then cat "$CLAUDE_PROJECT_DIR/AGENTS.md"; fi" } ] } ] } } With this no modifications (symlinks, almost empty CLAUDE.md files) are needed in your projects/repos and it seems to be more reliable/more direct than the @AGENTS.md instruction in CLAUDE.md How would you get it to pick up sub-folder agent.md files? — Reply to this email directly, view it on GitHub <https://github.com/anthropics/claude-code/issues/6235#issuecomment-3590905475>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAJ4MWKNVXHLRJOOS4OE2M337D77LAVCNFSM6AAAAACENXYNLCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTKOJQHEYDKNBXGU> . You are receiving this because you commented.Message ID: @.***>

It's weird this issue is still open... Every single other agent now supports Agents.md now except Claude Code.

Claude Code just told me it does support AGENTS.md files like CLAUDE.md files. I suppose it hallucinated.

Claude Code just told me it does support AGENTS.md files like CLAUDE.md files. I suppose it hallucinated.

Easy test:

Make AGENTS.md, with instruction: "call me Joe". Launch Claude, you get default prompt and boilerplate -> ignored the file.

Rename it to CLAUDE.md, launch Claude: boilerplate changes, and it calls you Joe.

Seriously, what are you waiting for to officially support AGENTS.md? I'm amost switchning to a (open-source) third-party client because of that.

Why would Anthropic cofound an AI standards organization which includes AGENTS.md and not even have a basic level of support for it in their products? Don't you think maybe you should have had the engineering team change 1 line of code from CLAUDE.md to AGENTS.md before dropping this press release? https://www.anthropic.com/news/donating-the-model-context-protocol-and-establishing-of-the-agentic-ai-foundation

Jeez. Its not 1 line of code, the AGENTS.md standard requires them to
support a hierarchy of AGENTS.md files within the project hierarchy, where
CLAUDE.md is only at the project root. I don't think it would be incredibly
different for them to implement, but doing it right gets tricky since you
have to keep track of which directory you are working in and only apply the
correct context when within that directory. And I don't know what anyone
else's experience is, but from what I've seen Claude Code is really, really
bad at knowing what directory it is in.

Second, if supporting AGENTS.md requires more work, do you really want to
hold up the creation of the foundation to wait for it? Its a great feature,
but it is not mission critical for most users, as evidenced by the success
of Claude Code without it.

On Dec 9, 2025 at 2:15:43 PM, Alex Gleason @.***> wrote:

alexgleason left a comment (anthropics/claude-code#6235) <https://github.com/anthropics/claude-code/issues/6235#issuecomment-3634519447> Why would Anthropic cofound an AI standards organization which includes AGENTS.md and not even have a basic level of support for it in their products? Don't you think maybe you should have had the engineering team change 1 line of code from CLAUDE.md to AGENTS.md before dropping this press release? https://www.anthropic.com/news/donating-the-model-context-protocol-and-establishing-of-the-agentic-ai-foundation — Reply to this email directly, view it on GitHub <https://github.com/anthropics/claude-code/issues/6235#issuecomment-3634519447>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAACX7YJ2W4R4XYVBN3TIID4A5CY7AVCNFSM6AAAAACENXYNLCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTMMZUGUYTSNBUG4> . You are receiving this because you are subscribed to this thread.Message ID: @.***>

https://www.anthropic.com/engineering/claude-code-best-practices

You can place CLAUDE.md files in several locations: The root of your repo,... Any parent of the directory where you run claude... Any child of the directory where you run claude... Your home folder (~/.claude/CLAUDE.md...

I'd love this to be addressed natively, but in the meantime I have this script that has worked for my cases. YMMV. It symlinks all AGENTS.md files to CLAUDE.md recursively from wherever you invoke it.

Claude Code sometimes ignores its CLAUDE.md file, so referencing @AGENTS.md inside CLAUDE.md isn’t a reliable method.

I found a simple way to force Claude Code to support AGENTS.md: use a user-memory prompt that says:

ALWAYS read AGENTS.md file first

In Claude Code, pin this via the /memory command so it stays in user memory.

There's no excuse not to support AGENTS.md - it would be trivial to add this functionality if anthropic really wanted to.

Bump up as well. No ideas why we need to maintains many files. Now even Gemini Cli or Codex Cli support AGENTS.md already as well.

For large organizations that use monorepos with proper bounded contexts where even language has different meaning depending on what package you're on this is a no-brainer feature to support.
Find it odd that something that's an enterprise must have isn't supported by THE most used ai agent coding CLI.

@RafaRochaS91 Not odd at all. It's a barrier or retainer from Anthropics.
They must have metrics to guide them to not impl it... for now

@Solido
Understandable, but due to the reasons I mentioned there's currently not a better idea to support large scale monorepos in a way that doesn't require a lot of context engineering and where nested AGENTS.md file convention would be quite valuable.
Also whatever metrics they have or don't are just assumptions since as mentioned by other people codex and Gemini support this and their success metrics can't be that different since they try to solve the same problems.

@RafaRochaS91 As a user I want that too but this is the most upvoted ticket, ACP being close second. Both are ignored on will.

I also work on a large mono-repos and this 'wall' work against claude adoption since we started with another llm. We also like to switch and test different LLM for different use case.

In this situation we can not run Claude as AGENTS are required to understand at minima what's going on.

But for large project who started on Claude, not supporting AGENTS is Anthropics way to keep them from testing other solutions. It's a business first decision to ignore the request and key the monthly stream stable. It also block users from moving to local LLM installations.

@Solido those are very valid albeit annoying points but you're right and can understand why it's not odd at all the lack of support.
Thanks and let's hope for the best, may the gods of their roadmap be in our favor 😄

The naming, "agents.md" a bit confusing given subagents are defined as "agents."

Generational aura loss.

try this

claude --append-system-prompt "
SYSTEM RULE: RESPECT AGENTS.md
You must treat 'AGENTS.md' exactly like 'CLAUDE.md' with the following hierarchy rules. 

1. **Parent/Current (Startup)**: IMMEDIATELY upon starting this session, use your tools to check the current directory AND all parent directories (up to the git root) for a file named 'AGENTS.md'. If found, read them.
2. **Child (On-Demand)**: Before editing or reading files in a subdirectory, check if an 'AGENTS.md' exists in that subdirectory. If it does, read it first to update your context.
3. **Priority**: Treat instructions in 'AGENTS.md' as binding system rules.
"

you can add alias to it.

I disagree with @coygeek suggestion - both AGENTS.md and CLAUDE.md should be applied to working context. AGENTS.md can be treated as a base knowledge, and CLAUDE.md can be treated as a refinement of that base knowledge. Anything mentioned in CLAUDE.md has precedence over what is said in AGENTS.md. However, if there is no conflict in instructions, then AGENTS.md instructions will be used.

The suggestion by @james-heidi is good, but only works for the current session. I would just extend the prompt with another instruction:

claude --append-system-prompt "
SYSTEM RULE: RESPECT AGENTS.md
You must treat 'AGENTS.md' exactly like 'CLAUDE.md' with the following hierarchy rules. 

1. **Parent/Current (Startup)**: IMMEDIATELY upon starting this session, use your tools to check the current directory AND all parent directories (up to the git root) for a file named 'AGENTS.md'. If found, read them.
2. **Child (On-Demand)**: Before editing or reading files in a subdirectory, check if an 'AGENTS.md' exists in that subdirectory. If it does, read it first to update your context.
3. **Priority**: Treat instructions in 'AGENTS.md' as binding system rules.
4. **Conflicts**: If you realize that instructions in 'AGENTS.md' contradict instructions in 'CLAUDE.md', the 'CLAUDE.md' will have precedence.
"

if you wanna reuse everywhere, embed this behaviour into a user-level skills

it would be loaded automatically.

@RockyMM

there are many ways to tweak claude code system prompts as well. e.g. Piebald-AI/tweakcc

I’d like to add some context regarding Issue #2571. Currently, because CLAUDE.md isn't automatically detected in sub-folders, it's difficult to use Claude Code effectively on very complex or monorepo-style projects.

Regarding the suggestion to "add a instruction to the system prompt to read AGENTS.md": while this is a helpful temporary workaround, it isn't a robust long-term solution. Relying on the LLM to remember to fetch its own instructions is less reliable than having the CLI natively prioritize those files. There is a significant difference between an AI choosing to read a file and those instructions being baked into the system context from the start.

Compared to other CLI tools (like OpenCode) that offer native, deep support for these types of configuration files, the current implementation feels like it has room to grow. Native support for AGENTS.md would make this a much more "production-ready" tool for enterprise-scale repositories.

I have been doing this for months without issue, but would obviously be better if claude code embraced interoperability.

# AGENTS.md > CLAUDE.md
echo "See ./AGENTS.md" > CLAUDE.md

# Don't advertise for free
echo "CLAUDE.md" >> .gitignore
````

 I don't want an agent-specific "CLAUDE.md" in my tree unless I really need it for tuning or if _Anthropic is paying me for branding._ 

AGENTS.md is becoming a de-facto industry standard for AI coding assistants — Cursor, Copilot, Codex, Amp, and others already support it. Claude Code is currently the outlier here.

I understand the vendor lock-in perspective and branding considerations, but consider the practical implications:

1. Team collaboration: Teams often have members with different tool preferences. Having to maintain both CLAUDE.md and AGENTS.md creates unnecessary friction.

1. Third-party projects: When working with external codebases, I have no authority to rename or add files. These projects already have AGENTS.md — I shouldn't need to fork just to add Claude-specific files.

Workaround (for anyone who needs this now):

Create ~/.claude/hooks/load-agents.sh:

#!/bin/bash
if [ -f "$CLAUDE_PROJECT_DIR/AGENTS.md" ]; then
  cat "$CLAUDE_PROJECT_DIR/AGENTS.md"
fi

Run chmod +x ~/.claude/hooks/load-agents.sh

Add to ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$HOME/.claude/hooks/load-agents.sh"
          }
        ]
      }
    ]
  }
}

Ideal solution: Claude Code should automatically read both CLAUDE.md and AGENTS.md when opening a project.

AGENTS.md is becoming a de-facto industry standard for AI coding assistants — Cursor, Copilot, Codex, Amp, and others already support it. Claude Code is currently the outlier here. I understand the vendor lock-in perspective and branding considerations, but consider the practical implications: 1. Team collaboration: Teams often have members with different tool preferences. Having to maintain both CLAUDE.md and AGENTS.md creates unnecessary friction. 2. Third-party projects: When working with external codebases, I have no authority to rename or add files. These projects already have AGENTS.md — I shouldn't need to fork just to add Claude-specific files. Workaround (for anyone who needs this now): Create ~/.claude/hooks/load-agents.sh: #!/bin/bash if [ -f "$CLAUDE_PROJECT_DIR/AGENTS.md" ]; then cat "$CLAUDE_PROJECT_DIR/AGENTS.md" fi Add to ~/.claude/settings.json: { "hooks": { "SessionStart": [ { "hooks": [ { "type": "command", "command": "$HOME/.claude/hooks/load-agents.sh" } ] } ] } } Ideal solution: Claude Code should automatically read both CLAUDE.md and AGENTS.md when opening a project.

I had to also chmod +x ~/.claude/hooks/load-agents.sh else I got Session Startup error on claude load

Another workaround (that works on macos and linux at least) is to create symbolic link CLAUDE.md that refers to AGENTS.md using ln command. @Zerquix18 @coygeek

this results the command below:
mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md

but the funny thing is how Anthropic, who donated MCP to Agentic AI Foundation for a _global standardization_, who themselves (aaif) standardized AGENTS.md, they (Anthropic) are still not supporting it

There is any news on this rather than the symlink workaround?

📝 Sign the petition: https://www.openpetition.org/petition/online/claude-should-support-agents-md

@bcherny @catherinewu any thoughts on this issue? Thanks and happy new year!

Good read!

You may just switch to opencode, it's free and you can continue login with your claude account
opencode support AGENTS.md natively, no need to maintain 2 files.

ask in opencode
!Image

ask codebase in copilot

!Image

You may just switch to opencode, it's free and you can continue login with your claude account opencode support AGENTS.md natively, no need to maintain 2 files.

@james-heidi that isn't a solution for this thread. I'm sure everyone knows about Opencode. I use it myself for various reasons but that is irrelevant here.

It isn’t acceptable to think, "Okay, we have Opencode, so let's ditch Claude Code." Who knows when Anthropic might decide to block Opencode? Even now, the Opencode team has to spoof request headers just to get the Claude servers to accept them.

For all we know, they might even decide to block it after seeing comments like these. Is it really worth the risk?

> You may just switch to opencode, it's free and you can continue login with your claude account > opencode support AGENTS.md natively, no need to maintain 2 files. @james-heidi that isn't a solution for this thread. I'm sure everyone knows about Opencode. I use it myself for various reasons but that is irrelevant here. It isn’t acceptable to think, "Okay, we have Opencode, so let's ditch Claude Code." Who knows when Anthropic might decide to block Opencode? Even now, the Opencode team has to spoof request headers just to get the Claude servers to accept them. For all we know, they might even decide to block it after seeing comments like these. Is it really worth the risk?

I don't think using opencode will requires you to re-subscribe.

and this thread has been here for quite a while, I didn't see any action on this issue yet.

but why encouraging using opencode is not another way to push claude to resepct AGENTS.md?

they are separated issue but they are connected in real world.

AGENTS.md work worse I believe than CLAUDE.md. AGENTS.md do not support @ reference for nesting, but more importantly, nested AGENTS.md override AGENTS higher up the chain. This is a very poor design choice. The whole point of being able to put CLAUDE.md to a variety of places around the codebase means that you can selectively pull memory based on context by adding information that is useful based on where claude goes to. Making AGENTS override each other when a more nested one is encountered means you have to replicate anything that is more "generically" useful + adding anything that is more "specifically" useful in the more nested structure. I would really not like if Claude Code would be forced to adopt a clearly worse alternative to memory files CC introduced.

@mimkorn this is irrelevant to this topic. The point is that we are working in multi-agent, multi-provider environments, and we want to keep our instructions to the agents _organized_.

@RockyMM With respect, this is directly relevant. The behaviors are incompatible:

• AGENTS.md: "closest file takes precedence" (override)
• CLAUDE.md: cumulative loading (merge parent + child)

Example:

• Root defines code style
• /src/api/ defines 3rd party API docs location

With cumulative loading: working in /src/api/stripe/ gives me both.
With override: I lose project-wide style unless I duplicate it.

Additionally, CLAUDE.md @ syntax lets me reference @docs/stripe-api.md from both /src/ and /test/ contexts. AGENTS.md can't - issue #11 has been open since August 2025 with zero maintainer response despite 33 upvotes.

Why should CC adopt a "standard" that lacks core features, ignores community requests for months, and would require breaking existing functionality to implement?

Multi-tool environments may be a valid concern, but the solution isn't regressing to a technically inferior, poorly maintained spec.

AGETNS.md isn't a mature standard - it's a README format that got popular. Popularity doesn't equal quality.
If AGENTS.md wants to become a true standard, perhaps it should adopt these features rather than asking tools with better implementations to regress.

Thanks for the write-up @mimkorn ! I've been following this issue for a long while, but was completely unaware of this context regarding how AGENTS.md file precedence works...

While I now agree that:

AGENTS.md isn't a mature standard

it's still _a standard_ that practically every LLM agent harness other than Claude Code uses. While it would certainly be a regression to stop supporting CLAUDE.md and switch to AGENTS.md - it's not what this issue proposes.

As @coygeek wrote in one of the first comments - most of us (judging by the reaction counts under it) would just like it to be a fallback for when there is no CLAUDE.md file found. For the use cases which don't require cumulative loading behavior of CLAUDE.md files it would greatly benefit interoperability to support AGENTS.md just in this scenario.

@polczak-itt I think if this is truly so important for you, then you can easily work around the lack of support by creating a hook script. I'm pretty sure Claude will be able to generate one easily for you in one or two shots. It will be some bash script or python script that would run for microseconds on each read or write access to any file. We would check for presence of agents.md file anywhere on the file path towards root and would just pick the first one it would encounter, hence overriding.

Seems like this simple (obvious) enhancement is getting the "You're holding it wrong" treatment

Option A) (preferred)
1) follow CLAUDE.md logic like normal.
2) if no CLAUDE.md found, look for AGENTS.md
3) yay standards

Option B)
1) Symlink AGENTS.md to CLAUDE.md
OR
1) remember to tell everyone on your team to implement brittle hooks to work-around claude code design decisions

Option C)
1) "You're holding it wrong"
2) Bleed an measurable % of customer base to (soon-to-be-if-not-already) better software (opencode)

@mattbha
So simple, right? Unless it isn't.

Your option A)
What if there is

| CLAUDE.md | AGENTS.md | ??? Cumulative or override? |
| AGENTS.md | CLAUDE.md | ??? Which takes precedence? |
| Both | Both | ??? Which behavior model wins? |
Should the presence of AGENTS.md override also claude.md files that are on a higher level? Or should claude.md files higher be respected?

In the following structure a/b/c/d you have AGENTS.md in d, CLAUDE.md in c and AGENTS.md in a? What do you do? Agents.md say they override. You found agents on d, should it override both agents in a and claude in b? Yay so simple.

remember to tell everyone on your team to implement brittle hooks to work-around claude code design decisions

you can implement it once and well and share in company via plugin via marketplace.

If there's better agentic software out there, not sure why people are all over CC Github.

its intentionally not supported at this point, they also blocked other, better agents from using claude

its intentionally not supported at this point, they also blocked other, better agents from using claude

how on earth can you block other agents from reading a markdown file? :D

> its intentionally not supported at this point, they also blocked other, better agents from using claude how on earth can you block other agents from reading a markdown file? :D

https://github.com/anomalyco/opencode/issues/7410

@mattbha So simple, right? Unless it isn't. Your option A) What if there is | CLAUDE.md | AGENTS.md | ??? Cumulative or override? | | AGENTS.md | CLAUDE.md | ??? Which takes precedence? | | Both | Both | ??? Which behavior model wins? | Should the presence of AGENTS.md override also claude.md files that are on a higher level? Or should claude.md files higher be respected? In the following structure a/b/c/d you have AGENTS.md in d, CLAUDE.md in c and AGENTS.md in a? What do you do? Agents.md say they override. You found agents on d, should it override both agents in a and claude in b? Yay so simple. > remember to tell everyone on your team to implement brittle hooks to work-around claude code design decisions you can implement it once and well and share in company via plugin via marketplace. If there's better agentic software out there, not sure why people are all over CC Github.

@mimkorn It's up to them to decide...
People just want to use one file for multiple agents.
They are not going to use both AGENTS.md and CLAUDE.md, and if they do they are going to follow the rules that Claude decides.

Now can you stop spamming the thread ?

@mattbha So simple, right? Unless it isn't. Your option A) What if there is | CLAUDE.md | AGENTS.md | ??? Cumulative or override? | | AGENTS.md | CLAUDE.md | ??? Which takes precedence? | | Both | Both | ??? Which behavior model wins? | Should the presence of AGENTS.md override also claude.md files that are on a higher level? Or should claude.md files higher be respected? In the following structure a/b/c/d you have AGENTS.md in d, CLAUDE.md in c and AGENTS.md in a? What do you do? Agents.md say they override. You found agents on d, should it override both agents in a and claude in b? Yay so simple. > remember to tell everyone on your team to implement brittle hooks to work-around claude code design decisions you can implement it once and well and share in company via plugin via marketplace. If there's better agentic software out there, not sure why people are all over CC Github.

If there's any CLAUDE.md, use current logic. Else use AGENTS.md logic.

If this is complex logic for you, you must be a joy to work with. Our team tried Opencode and hasn't looked back. Repo-wise Opencode has more stars (and forks), CC does win with more issues.

> @mattbha So simple, right? Unless it isn't. > Your option A) What if there is > | CLAUDE.md | AGENTS.md | ??? Cumulative or override? | | AGENTS.md | CLAUDE.md | ??? Which takes precedence? | | Both | Both | ??? Which behavior model wins? | Should the presence of AGENTS.md override also claude.md files that are on a higher level? Or should claude.md files higher be respected? > In the following structure a/b/c/d you have AGENTS.md in d, CLAUDE.md in c and AGENTS.md in a? What do you do? Agents.md say they override. You found agents on d, should it override both agents in a and claude in b? Yay so simple. > > remember to tell everyone on your team to implement brittle hooks to work-around claude code design decisions > > > you can implement it once and well and share in company via plugin via marketplace. > If there's better agentic software out there, not sure why people are all over CC Github. @mimkorn It's up to them to decide... People just want to use one file for multiple agents. They are not going to use both AGENTS.md and CLAUDE.md, and if they do they are going to follow the rules that Claude decides. Now can you stop spamming the thread ?

The thing is, that if you want CC to support AGENTS.md, you want them to support it the way that the standard behaves, which is different from Claude.md memory files. And they are surely not going to drop their superior setup for the other. And if you want to support both, then cc has to gracefully handle situation when it encounters both in the file system. That's just the complexity that comes with requesting multiple conflicting behaviours in the system to co-exist. I do not know why you even think that people wouldn't do it. It's incredibly easy to imagine — people hop between tools and large teams at this time often involve people using different tools over same repos. If my team decides to use AGENTS.md, but I keep on using CLAUDE.local.md, because I need the behaviours of claude memory files (compounding, not overriding), then wuala, I am working with a repo, where both are in place.

> @mattbha So simple, right? Unless it isn't. > Your option A) What if there is > | CLAUDE.md | AGENTS.md | ??? Cumulative or override? | | AGENTS.md | CLAUDE.md | ??? Which takes precedence? | | Both | Both | ??? Which behavior model wins? | Should the presence of AGENTS.md override also claude.md files that are on a higher level? Or should claude.md files higher be respected? > In the following structure a/b/c/d you have AGENTS.md in d, CLAUDE.md in c and AGENTS.md in a? What do you do? Agents.md say they override. You found agents on d, should it override both agents in a and claude in b? Yay so simple. > > remember to tell everyone on your team to implement brittle hooks to work-around claude code design decisions > > > you can implement it once and well and share in company via plugin via marketplace. > If there's better agentic software out there, not sure why people are all over CC Github. If there's any CLAUDE.md, use current logic. Else use AGENTS.md logic. If this is complex logic for you, you must be a joy to work with. Our team tried Opencode and hasn't looked back. Repo-wise Opencode has more stars (and forks), CC does win with more issues.

I am not sure why we talk here, if you had made your choice for a different agentic system.

Your proposal would require claude to check all nested folder structures to look for any presence of CLAUDE.md anywhere to make such a decision. Also, claude looks for CLAUDE.md DOWN from the project opened not just UP, so people who use CLAUDE.md to store more global information somewhere closer to root would never have AGENTS.md work for them with such proposal. It's also not the most obvious one. If someone opens up a project with AGENTS.md at the root, but someone checked in CLAUDE.md somewhere deeply nested, they might easily have broken expectations, that agents.md is ignored.

> > @mattbha So simple, right? Unless it isn't. > > Your option A) What if there is > > | CLAUDE.md | AGENTS.md | ??? Cumulative or override? | | AGENTS.md | CLAUDE.md | ??? Which takes precedence? | | Both | Both | ??? Which behavior model wins? | Should the presence of AGENTS.md override also claude.md files that are on a higher level? Or should claude.md files higher be respected? > > In the following structure a/b/c/d you have AGENTS.md in d, CLAUDE.md in c and AGENTS.md in a? What do you do? Agents.md say they override. You found agents on d, should it override both agents in a and claude in b? Yay so simple. > > > remember to tell everyone on your team to implement brittle hooks to work-around claude code design decisions > > > > > > you can implement it once and well and share in company via plugin via marketplace. > > If there's better agentic software out there, not sure why people are all over CC Github. > > > If there's any CLAUDE.md, use current logic. Else use AGENTS.md logic. > If this is complex logic for you, you must be a joy to work with. Our team tried Opencode and hasn't looked back. Repo-wise Opencode has more stars (and forks), CC does win with more issues. I am not sure why we talk here, if you had made your choice for a different agentic system. Your proposal would require claude to check all nested folder structures to look for any presence of CLAUDE.md anywhere to make such a decision. Also, claude looks for CLAUDE.md DOWN from the project opened not just UP, so people who use CLAUDE.md to store more global information somewhere closer to root would never have AGENTS.md work for them with such proposal. It's also not the most obvious one. If someone opens up a project with AGENTS.md at the root, but someone checked in CLAUDE.md somewhere deeply nested, they might easily have broken expectations, that agents.md is ignored.

You are right! The horror of having to scan looking for a file!

just scanned my development folder. ~10k folders in 0.01s

➜  Development time rg "CLAUDE.md"
rg "CLAUDE.md"  0.01s

again, you must be a joy to work with.

further brings home my point of this issue getting the "you're holding it wrong" treatment

@mimkorn to make it very simple:

• Not everyone in a team uses the same tools: I can be using claude code and someone else in my team is using open code or whatever other tool that don't read from CLAUDE.md
• People generally don't like lock-ins: if tomorrow I want to use another tools that supports AGENTS.md instead, I don't want to spend time migrating all my CLAUDE.md to AGENTS.md, same thing goes the other way.
• This is a very simple change, no need to add more "complicated" rules, all they need to do is: if there isn't a CLAUDE.md file but there's an AGENTS.md file, process it as a CLAUDE.md file. The fact that they ignore people on this simple request makes it very clear that it's intentional and not "difficult"
• It's a "feature" that will benefit everyone, not sure why you seem very much against it and try to find any argument to make it sound like it's impossible to do.

> > > @mattbha So simple, right? Unless it isn't. > > > Your option A) What if there is > > > | CLAUDE.md | AGENTS.md | ??? Cumulative or override? | | AGENTS.md | CLAUDE.md | ??? Which takes precedence? | | Both | Both | ??? Which behavior model wins? | Should the presence of AGENTS.md override also claude.md files that are on a higher level? Or should claude.md files higher be respected? > > > In the following structure a/b/c/d you have AGENTS.md in d, CLAUDE.md in c and AGENTS.md in a? What do you do? Agents.md say they override. You found agents on d, should it override both agents in a and claude in b? Yay so simple. > > > > remember to tell everyone on your team to implement brittle hooks to work-around claude code design decisions > > > > > > > > > you can implement it once and well and share in company via plugin via marketplace. > > > If there's better agentic software out there, not sure why people are all over CC Github. > > > > > > If there's any CLAUDE.md, use current logic. Else use AGENTS.md logic. > > If this is complex logic for you, you must be a joy to work with. Our team tried Opencode and hasn't looked back. Repo-wise Opencode has more stars (and forks), CC does win with more issues. > > > I am not sure why we talk here, if you had made your choice for a different agentic system. > Your proposal would require claude to check all nested folder structures to look for any presence of CLAUDE.md anywhere to make such a decision. Also, claude looks for CLAUDE.md DOWN from the project opened not just UP, so people who use CLAUDE.md to store more global information somewhere closer to root would never have AGENTS.md work for them with such proposal. It's also not the most obvious one. If someone opens up a project with AGENTS.md at the root, but someone checked in CLAUDE.md somewhere deeply nested, they might easily have broken expectations, that agents.md is ignored. You are right! The horror of having to scan looking for a file! just scanned my development folder. ~10k folders in 0.01s `` ➜ Development time rg "CLAUDE.md" rg "CLAUDE.md" 0.01s `` again, you must be a joy to work with. further brings home my point of this issue getting the "you're holding it wrong" treatment

Was expecting you'd say that. I do however run cc sometimes from root, or home folder, which essentially mean it'd run through entire computer.
You had also not addressed the other nuance with memory files present outside of open project towards root.

What I'm trying to point out is that implementing support for both systems to work in parallel gracefully would necessitate compromises, special conventions and eventually funny documentation of expectations (so we support two memory file systems and they behave differently and this is what to expect when your repo has both at different locations...).

What I worry, is that a pressure could force CC to adopt a "standard" that has much less expression power and flexibility than the current memory system, which is why I am pointing out the nuances that I do. And considering that everyone can implement with hook whatever variant of compromise to support AGENTS.md they like cheaply (in a matter of a 3 conversation turns) to their liking means that anthropic opting for continuing to work with what they see as the best way forward is reasonable and I really hope this ticket would not steer them from that.

@kidager

This is a very simple change, no need to add more "complicated" rules. all they need to do is: if there isn't a CLAUDE.md file but there's an AGENTS.md file, process it as a CLAUDE.md file.

As you can see, this is exactly the problem. What you just described as what you'd like them to do is something that would break the AGENTS.md standard and expressed a different expectations as the colleauges here in the thread. If it would process it as CLAUDE.md it would break AGENTS.md contract, which claims, that nested AGENTS.md override higher level ones, which CLAUDE.md doesn't. CLAUDE.md compounds them.

@mimkorn to make it very simple: * Not everyone in a team uses the same tools: I can be using claude code and someone else in my team is using open code or whatever other tool that don't read from CLAUDE.md

Indeed — the fact that two people can use different tools over the same repo would necessitate the functionality to support existence of both memory systems, which are set to behave differently (overriding vs compounding).

* People generally don't like lock-ins: if tomorrow I want to use another tools that supports AGENTS.md instead, I don't want to spend time migrating all my CLAUDE.md to AGENTS.md, same thing goes the other way.

I do agree that lock in is not nice and would wish CLAUDE.md to be called AGENT.md and AGENT standard to follow claude behaviour (compounding, @ referencing etc.). this is however not the case and the people who decided to "standardize" agent.md (and then not properly maintain this standard) didn't seem to care to make the standard as smart as possible. So here we are and I wouldn't like to go down the less useful route.

* It's a "feature" that will benefit everyone, not sure why you seem very much against it and try to find any argument to make it sound like it's impossible to do.

If you are unsure why I don't like it look at the detail I am trying to explain here above. CLAUDE.md is behaving differently than AGENTS.md. I use many nested claude.mds and expect them to compound. If AGENTS.md standard would be adopted, it would break my memory system and anyone else's who currently relies on how CLAUDE.md system works.

You both have fallen into the personal attacks zone. I'm not a mod or
anything but its not pleasant to read.

On Jan 9, 2026 at 9:43:40 AM, Šimon Demočko @.***>
wrote:

mimkorn left a comment (anthropics/claude-code#6235) <https://github.com/anthropics/claude-code/issues/6235#issuecomment-3729944356> @kidager <https://github.com/kidager> @mimkorn <https://github.com/mimkorn> to make it very simple: - Not everyone in a team uses the same tools: I can be using claude code and someone else in my team is using open code or whatever other tool that don't read from CLAUDE.md - People generally don't like lock-ins: if tomorrow I want to use another tools that supports AGENTS.md instead, I don't want to spend time migrating all my CLAUDE.md to AGENTS.md, same thing goes the other way. - This is a very simple change, no need to add more "complicated" rules, all they need to do is: if there isn't a CLAUDE.md file but there's an AGENTS.md file, process it as a CLAUDE.md file. The fact that they ignore people on this simple request makes it very clear that it's intentional and not "difficult" - It's a "feature" that will benefit everyone, not sure why you seem very much against it and try to find any argument to make it sound like it's impossible to do. Indeed — the fact that two people can use different tools over the same repo would necessitate the functionality to support existence of both memory systems, which are set to behave differently (overriding vs compounding). I do agree that lock in is not nice and would wish CLAUDE.md to be called AGENT.md and AGENT standard to follow claude behaviour (compounding, @ referencing etc.). this is however not the case and the people who decided to "standardize" agent.md (and then not properly maintain this standard) didn't seem to care to make the standard as smart as possible. So here we are and I wouldn't like to go down the less useful route. This is a very simple change, no need to add more "complicated" rules As you can see, this is exactly the problem. You just described that it would break the AGENTS.md standard and expressed a different expectations as the colleauges here in the thread. If it would process it as CLAUDE.md it would break AGENTS.md contract, which claims, that nested AGENTS.md override higher level ones, which CLAUDE.md doesn't. CLAUDE.md compounds them. If you are unsure why I don't like it look at the detail I am trying to explain here above. CLAUDE.md is behaving differently than AGENTS.md. I use many nested claude.mds and expect them to compound. If AGENTS.md standard would be adopted, it would break my memory system and anyone else's who currently relies on how CLAUDE.md system works. — Reply to this email directly, view it on GitHub <https://github.com/anthropics/claude-code/issues/6235#issuecomment-3729944356>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAACX73YCHIWDKO3OBUMJML4F7SEZAVCNFSM6AAAAACENXYNLCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTOMRZHE2DIMZVGY> . You are receiving this because you are subscribed to this thread.Message ID: @.***>

Thanks for the feedback @ashebanow . Wasn't pleasant to write either, will try to adjust.

I hear that there is the unpleasantness with the lack of support. The perspective from which I am writing is in defense of current memory system and a worry to not lose the current functionality to support a standard, which has a bit less expressivity.

To improve the spirit of the conversation, I am willing to help write whatever scripts are necessary to support the users here to achieve desired behavior. Please feel free to write out the expectation of how you would like to claude handle the presence of AGENTS.md and CLAUDE.md in the system and I will write a plugin for you to install to achieve the behaviour. I believe that different users might have different expectations so there might be multiple plugin variants, but I'm willing to help build them in good spirit. I will try to build some reasonable "default" middle ground and if variants are necessary, it might not be difficult to make them.

Can this be fixed by adding a config for something like "contextFilename" or "memoryFilename"? With default value of "CLAUDE.md"?

And since this is context/memory option for CC, that file would work as if it's CLAUDE.md regardless of filename?

@mimkorn respectfully, this is a request for Anthropic to support this open standard in CC in addition to CLAUDE.md not superseding it, and it is not your job to fix this general issue with CC for the ~500 people in this issue, as this does not fix the root cause of the hundreds of thousands of additional engineers that will never be aware this issue exists in the first place.

Six months, thousands of requests, most market players following the standard, and here we are, with empty discussions and mediocre solutions. It's disheartening.

Don't do workaround. Just CC must do it.

This reminds me of Apple resisting to adopt USB-C

I fixed this issue by switching to OpenCode instead of Claude Code. 👍

This reminds me of Apple resisting to adopt USB-C

at this point, we need the EU to step in and enforce AGENTS.md

yeah let's get a petition with the EU for this lol. it really isn't that hard to understand the problem, nobody wants to have 5 different versions of the same file and AGENTS.md is the neutral choice.

> This reminds me of Apple resisting to adopt USB-C at this point, we need the EU to step in and enforce AGENTS.md

AI Governance for Exposed Navigation & Tooling Specifications

I'm less convinced of this than I was at first. Claude Code is Claude Code: AI agents aren't commoditized or fungible. The whole notion of AGENTS.md increasingly (to me) seems premature. Given the differences in "cascading," the best solution for now might be to:

• Put key points in separate, additive files: memory "bricks" that can be stacked.
• ~#include~ @-mention select files in AGENTS.md or CLAUDE.md: memory "walls."
• For a format that cascades (CLAUDE.md), each wall mentions only the bricks that augment its parent.
• For a format that overrides (AGENTS.md), each wall mentions All The Bricks it needs.

This enables sharing across projects, since walls in repos A and B can cite (@-mention) bricks in C.

The whole thing feels a bit like the CommonJS/RequireJS kerfuffle. We may not need one standard to rule them all; and frankly, I'm not sure we collectively understand the problem space well enough to define such a standard yet, anyway.

Put it as a setting. Default to CLAUDE.md if you must.

Problem solved, everyone wins. This really isn't that hard.

I patched my Claude Code binary to use AGENTS.md instead of CLAUDE.md.

<img width="719" height="304" alt="Image" src="https://github.com/user-attachments/assets/579a733d-08b0-49c9-83cd-734977a71b87" />

Note that this solution replaces CLAUDE.md with AGENTS.md, so your CLAUDE.md files won't work after that, should be fine since AGENTS.md is the standard that works across most AI coding tools (OpenCode, Codex, Cursor, Windsurf, etc.), so I'd rather have one file that works everywhere.

It works by replacing all instances of the string CLAUDE.md with AGENTS.md in the binary, then re-signing it (required on macOS). After this, Claude Code will only look for AGENTS.md.

You'll need to re-run the patch after Claude Code updates.

The script below is for macOS Homebrew installs. For other setups, give Claude this prompt and it'll figure out where your binary is and adapt accordingly:

~~~md
This bash script replaces the word CLAUDE.md with AGENTS.md in the Claude Code binary on macOS when installed via Homebrew.

Figure out what installation method we have, and replicate the same functionality on this machine.

#!/usr/bin/env bash
# Patches Claude Code to look for AGENTS.md instead of CLAUDE.md
# Run this after Claude Code updates to re-apply the patch

set -euo pipefail

# Find Claude Code binary
CLAUDE_BIN=""
for path in /opt/homebrew/Caskroom/claude-code/*/claude /usr/local/Caskroom/claude-code/*/claude; do
    if [[ -f "$path" ]]; then
        CLAUDE_BIN="$path"
        break
    fi
done

if [[ -z "$CLAUDE_BIN" ]]; then
    echo "Error: Could not find Claude Code binary"
    exit 1
fi

echo "Found Claude Code at: $CLAUDE_BIN"

# Check current state
CLAUDE_MD_COUNT=$(strings "$CLAUDE_BIN" | grep -c 'CLAUDE\.md' || true)
AGENTS_MD_COUNT=$(strings "$CLAUDE_BIN" | grep -c 'AGENTS\.md' || true)
[[ -z "$CLAUDE_MD_COUNT" ]] && CLAUDE_MD_COUNT=0
[[ -z "$AGENTS_MD_COUNT" ]] && AGENTS_MD_COUNT=0

if [[ "$CLAUDE_MD_COUNT" == "0" && "$AGENTS_MD_COUNT" -gt 0 ]]; then
    echo "Already patched ($AGENTS_MD_COUNT AGENTS.md references)"
    exit 0
fi

if [[ "$CLAUDE_MD_COUNT" == "0" ]]; then
    echo "Error: No CLAUDE.md references found in binary"
    exit 1
fi

echo "Found $CLAUDE_MD_COUNT CLAUDE.md references to replace"

# Patch the binary
perl -pi -e 's/CLAUDE\.md/AGENTS.md/g' "$CLAUDE_BIN"

# Re-sign (required on macOS)
if command -v codesign &> /dev/null; then
    echo "Re-signing binary..."
    codesign --force --deep --sign - "$CLAUDE_BIN" 2>/dev/null
fi

# Verify
NEW_AGENTS_COUNT=$(strings "$CLAUDE_BIN" | grep -c 'AGENTS\.md' || true)
[[ -z "$NEW_AGENTS_COUNT" ]] && NEW_AGENTS_COUNT=0
echo "Patched: $NEW_AGENTS_COUNT AGENTS.md references"

# Test
if "$CLAUDE_BIN" --version &> /dev/null; then
    echo "Verified: claude --version works"
else
    echo "Warning: Binary may not work correctly"
    exit 1
fi

echo "Done! Claude Code now looks for AGENTS.md instead of CLAUDE.md"

~~~

I patched my Claude Code binary to use AGENTS.md instead of CLAUDE.md. <img alt="Image" width="719" height="304" src="https://private-user-images.githubusercontent.com/19984935/536015921-579a733d-08b0-49c9-83cd-734977a71b87.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3Njg0NzE3MjEsIm5iZiI6MTc2ODQ3MTQyMSwicGF0aCI6Ii8xOTk4NDkzNS81MzYwMTU5MjEtNTc5YTczM2QtMDhiMC00OWM5LTgzY2QtNzM0OTc3YTcxYjg3LnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNjAxMTUlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjYwMTE1VDEwMDM0MVomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPWUwYTMzODk1ZGYxMDI4ZmUxYTdmN2UxYzZjNmRlM2EyNjkwYTA0NTZkMjRmM2VlYmVhMjM2YjZhM2ViMWU2OTAmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0In0.A7p7Q5DsDrXUqWEUznoczOfUHSrY5ip0Vgd9RxDbarA"> Not that this solution replaces CLAUDE.md with AGENTS.md, so your CLAUDE.md files won't work after that, should be fine since AGENTS.md is the standard that works across most AI coding tools (OpenCode, Codex, Cursor, Windsurf, etc.), so I'd rather have one file that works everywhere. It works by replacing all instances of the string CLAUDE.md with AGENTS.md in the binary, then re-signing it (required on macOS). After this, Claude Code will only look for AGENTS.md. You'll need to re-run the patch after Claude Code updates. The script below is for macOS Homebrew installs. For other setups, give Claude this prompt and it'll figure out where your binary is and adapt accordingly: `` This bash script replaces the word CLAUDE.md with AGENTS.md in the Claude Code binary on macOS when installed via Homebrew. Figure out what installation method we have, and replicate the same functionality on this machine. `bash #!/usr/bin/env bash # Patches Claude Code to look for AGENTS.md instead of CLAUDE.md # Run this after Claude Code updates to re-apply the patch set -euo pipefail # Find Claude Code binary CLAUDE_BIN="" for path in /opt/homebrew/Caskroom/claude-code/*/claude /usr/local/Caskroom/claude-code/*/claude; do if [[ -f "$path" ]]; then CLAUDE_BIN="$path" break fi done if [[ -z "$CLAUDE_BIN" ]]; then echo "Error: Could not find Claude Code binary" exit 1 fi echo "Found Claude Code at: $CLAUDE_BIN" # Check current state CLAUDE_MD_COUNT=$(strings "$CLAUDE_BIN" | grep -c 'CLAUDE\.md' || true) AGENTS_MD_COUNT=$(strings "$CLAUDE_BIN" | grep -c 'AGENTS\.md' || true) [[ -z "$CLAUDE_MD_COUNT" ]] && CLAUDE_MD_COUNT=0 [[ -z "$AGENTS_MD_COUNT" ]] && AGENTS_MD_COUNT=0 if [[ "$CLAUDE_MD_COUNT" == "0" && "$AGENTS_MD_COUNT" -gt 0 ]]; then echo "Already patched ($AGENTS_MD_COUNT AGENTS.md references)" exit 0 fi if [[ "$CLAUDE_MD_COUNT" == "0" ]]; then echo "Error: No CLAUDE.md references found in binary" exit 1 fi echo "Found $CLAUDE_MD_COUNT CLAUDE.md references to replace" # Patch the binary perl -pi -e 's/CLAUDE\.md/AGENTS.md/g' "$CLAUDE_BIN" # Re-sign (required on macOS) if command -v codesign &> /dev/null; then echo "Re-signing binary..." codesign --force --deep --sign - "$CLAUDE_BIN" 2>/dev/null fi # Verify NEW_AGENTS_COUNT=$(strings "$CLAUDE_BIN" | grep -c 'AGENTS\.md' || true) [[ -z "$NEW_AGENTS_COUNT" ]] && NEW_AGENTS_COUNT=0 echo "Patched: $NEW_AGENTS_COUNT AGENTS.md references" # Test if "$CLAUDE_BIN" --version &> /dev/null; then echo "Verified: claude --version works" else echo "Warning: Binary may not work correctly" exit 1 fi echo "Done! Claude Code now looks for AGENTS.md instead of CLAUDE.md" ` ``

BASED

* For a format that overrides (AGENTS.md), each wall mentions All The Bricks it needs

Hi @jeffs, I read this many times but didn't found citation in docs. Where did you find that AGENTS.md overrides?

codex for example reads all AGENTS.md from project root to current dir:

3. Merge order: Codex concatenates files from the root down, joining them with blank lines. Files closer to your current directory override earlier guidance because they appear later in the combined prompt.

@davidruzicka Not jeffs, but I did some digging on this since there's some confusion in the thread to which I contributed earlier.

OpenAI Codex does what you quoted.

Factory AI - documented here - uses a first-match-wins model where only one AGENTS.md is active at a time (the nearest one).

Claude Code uses CLAUDE.md (not AGENTS.md) and accumulates files:

"Claude Code reads memories recursively: starting in the cwd, Claude Code recurses up to (but not including) the root directory / and reads any CLAUDE.md or CLAUDE.local.md files it finds."

Claude Code also discovers nested subtree files lazily when accessing those directories.

The agents.md convention

The agents.md website says "closest one takes precedence" (implying single-file selection), but Codex's implementation concatenates everything. The "override" is semantic—later content in the combined prompt "takes precedence" when instructions conflict—not structural (replacing files). However the precedence is only about conflicting information having a different position in the context which can create problems of context ambiguity, distractions which accelerates context rot. Also the claim that what comes later in context has precedence is spurious. LLMs are known to have a U-shaped attention bias (paying more to the beginning and end of a context), so anything that comes at a later stage will eventually have less attention then what came first.

jeffs's claim that "AGENTS.md overrides" highlights the ambiguity of the agents.md page: it describes a precedence model, but Codex specifically concatenates. The distinction is:

| Approach | What happens |
|----------|-------------|
| Precedence/Override (Factory) | Only nearest file is read |
| Accumulation + Later-"wins" (Codex) | All files concatenated; conflicts "resolved" by position |
| Accumulation (Claude Code) | All files concatenated into context (but that's okay, you are expected to use memory files as bricks) |

Bottom line

AGENTS.md is a filename convention that emerged from OpenAI Codex, got a landing page at agents.md, and each tool implements discovery/loading differently. This limits the usefulness of the convention. The agent files will be written differently per tool to fit the context management practices of the specific tool. The benefit of using the same files with different tool will be limited and YMMV). The website's claims about "precedence" don't mandate any particular implementation—tools are free to concatenate, override, or do whatever they want. The effect of such "precedence" though is questionable. It's well known, that providing conflicting instructions to model creates distractions, ambiguity and eventually context rot, degrading the performance of the model/agent. ( https://research.trychroma.com/context-rot )

Thanks for digging @mimkorn into this — that’s exactly what I suspected: given how vague the “precedence/override” wording is on agents.md, I assumed different tools would end up implementing it differently (single nearest file vs. accumulation/concatenation with “later wins” semantics). This clears up the confusion.

With Anthropic deciding for some stupid reason to not support the standard literally every other tool already supports plus not supporting OpenCode, really seems they are on a speedrun to become the most disliked AI tool.

The agent files will be written differently per tool to fit the context management practices of the specific tool.

I disagree. No they won't. People are not aware of these tool specifics that you needed quite some time to discover. Nobody will bother to learn that. All that people know is to populate AGENTS.md or muliple AGENTS.mds. And we feel friction when, for example we are allowed to choose our coding agent. Some use Cursor, some use Copilot in VS Code, and I use Claude Code.

This should be Deveper eXperience thing - something which makes our development lives easier. It does not need to be very correct.

People are not aware of these tool specifics that you needed quite some time to discover. Nobody will bother to learn that.

Fair. However, I do know the specifics of CC which I do use (which I was explaining in the previous posts as well). I did not know the specifics of tools that I do _not_ use, which is what I had to research, which is understandable.

I'd gently push back on "nobody will bother to learn." Understanding how memory files compose into context (context management) does matter for getting good outputs from any of these tools. But I take your point that there are some users (notably participants on this ticket), who just want to drop an AGENTS.md in and have it do something.

I would like just to notice that there are a lot of backlinks to this issue, a clear indication of community interest.

But I take your point that there are some users (notably participants on this ticket), who just want to drop an AGENTS.md in and have it do something.

Well, there definitely are _some_ users. Those 2k thumbs-ups clearly indicate people do want to have an AGENTS.md that does _something_. Apparently, it's considered a negligible number, given that we've been having this endless discussion since August. It would be way more productive (and I believe easier) to give people at least something to work with, and then propose improvements to the standard if you find it not good enough. AGENTS.md is here to stay. I'd expect Anthropic to embrace a much more constructive approach rather than nitpicking and ignoring its users' voices.

<img width="1111" height="719" alt="Image" src="https://github.com/user-attachments/assets/61d927e9-b482-4a94-a4a3-9c625b0e7172" />

Sad how Anthropic can be both the clear moral leader in this race and also starts acting like the incumbent who's too proud / revenue centric to adopt common sense standards.

.claude/skills => .agents/skills
CLAUDE.md => AGENTS.md
.mcp.json ✔️

win on model performance, speed, agent loop design excellence or price, not walled garden tactics please.

Sad how Anthropic can be both the clear moral leader in this race and also starts acting like the incumbent who's too proud / revenue centric to adopt common sense standards. `` .claude/skills => .agents/skills CLAUDE.md => AGENTS.md .mcp.json ✔️ `` win on model performance, speed, agent loop design excellence or price, not walled garden tactics please.

Let's not forget the JSON schema for MCP configuration still lacks proper standardization as well. Yes visual studio with github copilot reads from .mcp.json, but it expects "servers", while claude code expects "mcpServers". Then you have opencode which combines "command" and "args" into one array property. I'm sure there are more differences.

@pascalwhoop nailed it 🎯

Also, they could document that for anything model specific i.e. CLAUDE.md, just shim out in your AGENTS.md to follow a local and/or global CLAUDE.md. Best of both worlds.

Sad how Anthropic can be both the clear moral leader in this race and also starts acting like the incumbent who's too proud / revenue centric to adopt common sense standards.

Worth noting the gap might not be stubbornness but feature parity.

Claude Code merges files from global + project + subdirectories, while AGENTS.md does “closest wins” (you lose your global defaults when a subdirectory file exists).

There’s also no file-pattern scoping in AGENTS.md. Claude Code can scope rules to specific file types or paths. AGENTS.md punts on this entirely (“just use subdirectories”), which doesn’t scale when you need rules per file type, not per folder.
AGENTS.md’s philosophy is intentional minimalism, great for portability, but tools with richer semantics can’t fully express their capabilities through it.

Maybe the path forward isn’t “Anthropic adopts AGENTS.md” but AGENTS.md v2 adds optional structured sections. Then Anthropic may migrate.

Until then this works fine: ln -s AGENTS.md CLAUDE.md

Until then this works fine: ln -s AGENTS.md CLAUDE.md

Sometimes. I've seen it get rejected because it's a symlink, I believe the ReadFile tool will error out (though Read() works).

So far using

# In ./CLAUDE.md
@AGENTS.md

But what about /skills or /agents, any one managed a way round it?
Will creating each skill with a @included work just as well?

Even gemini supports some changes to its project file name, just adding a setting to change the file and folder name would do the job!

It's 2026 - and this issue is still open.

Just support it by default already.

Dude, it's time to allow this stop being ridiculous

How is this still open????

OpenCode, OpenCode! Don't tie yourself to a provider, to a given pricey model, just because of the tiny shim that a Terminal Interface provides. You'll be blown away by OpenCode.. and the massive community of devs around..

Anthropic is aggressively cracking down on using their models via subscriptions outside Claude Code, duh.

We ain't no millioners to pay on per token basis.

Why not just treat any AGENTS.md as CLAUDE.md and note the edge cases in the docs? Supporting partially (or differently) is much better that not supporting (ignoring the demand)

because it's like asking everyone who support AGENTS.md to support CLAUDE.md too. so why support two memory files if they are "the same" ? doesn't make sense.

because it's like asking everyone who support AGENTS.md to support CLAUDE.md too. so why support two memory files if they are "the same" ? doesn't make sense.

Of course not, one is a universal standard name and the other is Anthropic specific. There's no reason why the Anthropic specific name needs to exist at all.

Any news?

they've probably overfit on claude.md so dont want to switch to agents.md to avoid regressions
though it would be an easy workaround imo.

Workaround on Linux: Symlink from AGENTS.md to CLAUDE.md or vice versa.

Workaround on Windows: Install Linux :trollface:

Is the usage of AGENTS.md not being standardized yet ? What's the point of having multiple files CLAUDE.md GEMINI.md QWEN.md etc.?

This issue is so funny. I think that claude code will often read AGENTS.md before starting work, but, the best move is to symlink CLAUDE.md > AGENTS.md . ln -s AGENTS.md CLAUDE.md . If your CLAUDE.md exists but not AGENTS.md , first run : mv CLAUDE.md AGENTS.md .

Worth noting that if you symlink AGENTS.md to CLAUDE.md some agents (cursor for example) will double read the file. This is a problem on teams where people have different preferences in tools.

Any progress with this? please

Worth noting that if you symlink AGENTS.md to CLAUDE.md some agents (cursor for example) will double read the file. This is a problem on teams where people have different preferences in tools.

Okay, thats very good to know. Any experience making CLAUDE.md a one-liner like "Follow AGENTS.md" ?

Okay, thats very good to know. Any experience making CLAUDE.md a one-liner like "Follow AGENTS.md" ?

@AGENTS.md in CLAUDE.md work great.

> Okay, thats very good to know. Any experience making CLAUDE.md a one-liner like "Follow AGENTS.md" ? @AGENTS.md in CLAUDE.md work great.

And I actually like it - we can have CC-specific instructions in CLAUDE.md, while having agent-agnostic instructions in AGENTS.md 👌

AGENTS.md @included in CLAUDE.md works for me too but what about the rest of .agents/...? skills, agents, etc?

I am I suppose to do the same on each file created? Does it work to mention the folder on the generic AGENTS.md?

With Anthropic leading the agents environment standards and rest of the agents following (skills now supported on many agents), it does not make sense that either "agents" is directly (also) supported or a simple value on settings like in gemini-cli.

I feel like AGENTS.md only works part of the time. Because there are plenty of times I have to remind it of stuff that is in there.

I do have a solution. Which is to use a hook for session_start to just inject it.

I want to share a tool that I've been hacking on that "polyfills" _complete_ AGENTS.md support, including nesting, (and .agents/skills) for Claude:

https://github.com/nevir/agentfill

The AGENTS.md support is primarily implemented via a hook that gives a few things:

• The root AGENTS.md is always injected
• Instructs Claude to load relevant AGENTS.md files on demand (rather than _all_ of them). Critical for large codebases to avoid context bloat
• Honors precedence rules

Wow. I just used Claude code to do a web search on the top 20 agents that don't support AGENTS.md, Claude determined EVERYONE ELSE supports it and had this to say:

Claude Code is the only major coding agent that doesn't read AGENTS.md. Not one of a few holdouts — the only one.

Cursor reads it. Copilot reads it. Codex reads it. Gemini CLI, Windsurf, Cline, Aider, Zed, Devin, Jules, Amp, Factory, RooCode, Warp, goose — they all read it. The standard is stewarded by the Linux Foundation's Agentic AI Foundation. 60,000+ repos use it.

The irony: Anthropic built MCP — an open interoperability standard for tool communication. You literally evangelized the idea that agents should speak the same protocol instead of building proprietary silos. Then you shipped the only major coding agent that demands its own proprietary instruction file.

This isn't a feature request. It's a one-line fallback path: if CLAUDE.md doesn't exist, read AGENTS.md. That's it. CLAUDE.md keeps full priority. Zero breaking changes. Probably 10 lines of code.

What's actually happening in the wild: Apache Superset, Brave, rotki, and thousands of other projects are maintaining duplicate files with identical content — one called AGENTS.md for everyone else, one called CLAUDE.md for you. That's the exact fragmentation this standard was designed to eliminate.

Claude Code scores 98/100 on coding benchmarks. It's arguably the best agent. But it has the worst interoperability story of any major tool. The best product shouldn't be the last one to support the open standard — especially when that product's company literally invented the concept of open agent interoperability standards.

2,401 upvotes. 178 comments. Zero official response. Ship the fallback.

There is NO EXCUSE for this behavior Anthropic! Your OWN PRODUCT condemns you here! DO SOMETHING.

are they simply holding out because they didn't come up with AGENTS.md?

cmon

Ok, modern problems require modern solutions:

@claude please add AGENTS.md support

How is this still a feature request? You guys are ahead with everything else, get your shit together.

This is not an official solution, obviously, but with tweakcc v4.0.0 you can automatically patch your Claude Code install (native or npm) to support AGENTS.md, among many other things. Run npx tweakcc@latest --apply to have it automatically detect and patch your installation. Run with --verbose if you want to see the diff of what's being applied. Demo:

https://github.com/user-attachments/assets/27513489-bb89-4174-b62f-ab17b0fce7bd

My guess is this comes down to branding. CLAUDE.md keeps Anthropic's name embedded in every project that uses it, and given their current market lead (arguably), there's little business incentive to adopt a vendor-neutral standard.

There is hope guys! Anthropic’s CEO stated that we are just 6-12 months away from an AI model that can do everything SWEs do end-to-end, so soon an coding agent will automatically pick up this feature request.

masterclass in developer relations

Just stick this in CLAUDE.md, works great:

@AGENTS.md

Have nested agents files tho

On Wed, Feb 11, 2026 at 2:17 PM Seb Maynard @.***>
wrote:

sebmaynard left a comment (anthropics/claude-code#6235) <https://github.com/anthropics/claude-code/issues/6235#issuecomment-3886891446> Just stick this in CLAUDE.md, works great: @AGENTS.md — Reply to this email directly, view it on GitHub <https://github.com/anthropics/claude-code/issues/6235#issuecomment-3886891446>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACIEOMLIRZC5U2NDFV23UFD4LOE5PAVCNFSM6AAAAACENXYNLCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTQOBWHA4TCNBUGY> . You are receiving this because you commented.Message ID: @.***>

There is hope guys! Anthropic’s CEO stated that we are just 6-12 months away from an AI model that can do everything SWEs do end-to-end, so soon an coding agent will automatically pick up this feature request.

The first line in their .agentignore will be the URL to this issue.

Little workaround while Anthropic adopts this standard, create the AGENT.md and just put "Start by reading the content of CLAUDE.md". Not the best sure but it works

I've set in my global CLAUDE.md, to _"treat AGENTS.md and AGENTS.local.md in the same way it treats CLAUDE.md and CLAUDE.local.md respectively"_, it's not perfect but it kind of works most of the time.

Symlinks or force the CLAUDE files to read the AGENTS aren't great for nested AGENTS files (always have to read the code to find if new AGENTS files were added by someone else, specially when swapping branches).

Still not done... 🙄

I want neither. I prefer a context script remember.sh that I control to print context or run commands to extract the current state.

The launch of the AAIF — built around open agentic protocols — makes the continued absence of native AGENTS.md support in Claude Code a significant credibility gap. While Anthropic donated MCP to promote interoperability, AGENTS.md adoption in their own flagship tool remains a six-month-old open issue.

To resolve the valid context-doubling concerns (see @mistercrunch ), Claude Code should simply prioritize CLAUDE.md and fall back to AGENTS.md if the former is missing. This respects the 'Sent from my iPhone' branding for those who want it, while finally supporting the 60k+ repos following the standard Anthropic helped elevate to a foundation level. Let's move past the symlink workarounds and implement this hierarchy without further delay.

--- Sonnet 4.6

I actually like them not supporting AGENTS.md- that way they don't inject the "IMPORTANT: this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task." at the end of it. So my workaround is to stop using CLAUDE.md entirely, and load AGENTS.md by hook, and i don't get that disclaimer at the end. If they support AGENTS.md, i'll have to create yet another workaround from that undermining instruction.

https://github.com/anthropics/claude-code/issues/18560

I actually like them not supporting AGENTS.md

I might be wrong, although from the 100s of comments and 1000s 👍 it seems you're in the minority group.

But, I would still stay, if there's people that would rather not use this, then make it configurable, like an "opt-out flag", which could be defined at user or project level.

I actually like them not supporting AGENTS.md- that way they don't inject the "IMPORTANT: this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task." at the end of it. So my workaround is to stop using CLAUDE.md entirely, and load AGENTS.md by hook, and i don't get that disclaimer at the end. If they support AGENTS.md, i'll have to create yet another workaround from that undermining instruction. #18560

What's the important? That doesn't live in any of my Agents files.

> I actually like them not supporting AGENTS.md- that way they don't inject the "IMPORTANT: this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task." at the end of it. So my workaround is to stop using CLAUDE.md entirely, and load AGENTS.md by hook, and i don't get that disclaimer at the end. If they support AGENTS.md, i'll have to create yet another workaround from that undermining instruction. > #18560 What's the important? That doesn't live in any of my Agents files.

I installed mitmproxy and watched the messages at the start of the session when my CLAUDE.md instructions stopped being followed. I found that in the <system-reminder> block that includes the CLAUDE.md content, at the end they add: "IMPORTANT: this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task."

User @ocristaldo stumbled on to the same issue in this bug: https://github.com/anthropics/claude-code/issues/18560

So my workaround was to rename all of my CLAUDE.md files AGENTS.md to make them support the standard, and use a SessionStart hook to inject it, as others have mentioned in this issue. Then when I look at the <system-reminder> traffic, that disclaimer is not at the end. If they treated AGENTS.md as equivalent to CLAUDE.md, that disclaimer would be at the end.

This is a not so transparent attempt to bring more attention to https://github.com/anthropics/claude-code/issues/18560. Obviously if they fixed that issue I would have no problem with them supporting AGENTS.md, but currently I find it an advantage.

Let's not delude ourselves. This is not being done because CLAUDE.md acts as free advertisement for Anthropic.

Let's not delude ourselves. This is not being done because CLAUDE.md acts as free advertisement for Anthropic.

I dont' think anyone is deluding themselves 😂
The technology/code/logic already is there 🙃 it would be 5 min job to make it work with AGENTS.

I can make it work by adding in the user CLAUDE.md to treat AGENTS.md files the same way as CLAUDE.md file and is "kind of" working.

Anthropic Claude Code being an Apple of agentic coding. And no, it's not a compliment.

8 months for that? Really?
This is bad for your rep boys

Anthropics perspective: We don't want to go by the standard, that would make it easier for people to use other tools and llms instead of Claude Code.

The reality: Users are going to do it regardless, they're not going to only use Claude Code just because you make their experience more miserable. All you're doing is making your customers despise you and show that you are going to be a dictator in the future, following the path of Apple.

Anthropics perspective: We don't want to go by the standard, that would make it easier for people to use other tools and llms instead of Claude Code. The reality: Users are going to do it regardless, they're not going to only use Claude Code just because you make their experience more miserable. All you're doing is making your customers despise you and show that you are going to be a dictator in the future, following the path of Apple.

They miss one thing, the big picture.
Just like people use different IDEs, they use different coding agents.
I love Claude Code (so far). If I'm in one-man show, I don't care about this issue. When I decide to switch, it's one mv command. Not a big deal.
But I work in team. The majority uses Claude Code. Yet, it's not mandatory to use Claude. Our policy is, you can use a tool of your choice.
Since CLAUDE.md or AGENTS.md is being commited to repo, what should we commit? Should we democratically do the tyranny of the majority? The minority is in the right, it's them who uses the industry standard.
I don't work in Microsoft, so I do follow the standards whenever they exist.
The result for me is: suboptimal experience or strong incentive to switch to something like OpenCode* or Codex.

\* not with Anthropic models, because they are being hostile as they can:
https://github.com/anomalyco/opencode/commit/973715f3da1839ef2eba62d4140fe7441d539411

It would be great to see AGENTS.md support in CLAUDE-code for better collaboration. HYPHA Network could also benefit from integrating AGENTS.md as it provides a unified standard for AI agents, making task completion more efficient across different projects and platforms like ours at https://hyphanet.ai.

That't weird to see Anthropic to not adopt agents.md open standard while they do push their own agenticskills.io open format for agents. It's a shame we have to use claude.md -> agents.md lifehacks to work in teams with different agentic tools.

Let's all start hating claude code together :)

--- better not to confuse anyone here ---

Has anyone gotten this? on v2.1.52

It reads any file you prefix with @ automatically. The purpose of CLAUDE.md / AGENTS.md is to not require the file to be mentioned at all and still be read when relevant, e.g. when it opens foo/bar/setup.py it automaticaly reads foo/bar/AGENTS.md

> Has anyone gotten this? on v2.1.52 It reads any file you prefix with @ automatically. The purpose of CLAUDE.md / AGENTS.md is to not require the file to be mentioned at all and still be read when relevant, e.g. when it opens foo/bar/setup.py it automaticaly reads foo/bar/AGENTS.md

Of course. But the agent told me:

"The file **was already loaded** via the system reminder"

Plus the explanation about that being part of the system prompt the agent receives.

o_O

> Has anyone gotten this? on v2.1.52 It reads any file you prefix with @ automatically. The purpose of CLAUDE.md / AGENTS.md is to _not_ require the file to be mentioned at all and still be read when relevant, e.g. when it opens foo/bar/setup.py it automaticaly reads foo/bar/AGENTS.md

From my personal experience, it deals with @ as just a file to read, but to include "instructions", then should be specifically mentioned, as in:

- Read @AGENTS.md
+ Treat @AGENTS.md the same way you would CLAUDE.md

Can't believe this is still not supported

Is this some weird ego trip to not support AGENTS.md?

We ran into the same friction maintaining separate instruction files for different agents. Ended up building a shared coordination layer instead of per-tool config files.

IDE Agent Kit gives each agent (Claude, GPT, Gemini, whatever) its own session with its own tools, and they coordinate through a shared message bus and room system. So rather than one big AGENTS.md that every tool reads differently, each agent gets instructions through the coordination layer.

Still think native AGENTS.md support would help a lot for the simple cases though. The plugin approach from @baktybekb looks solid as an interim solution.

I can't think of a single reason this issue is not being taken seriously. Please, accept defeat and support AGENTS.md, it's the default standard supported in the entire industry. We're asking you to support it simply as a second-tier class. You're letting the stupid naming fight take in lots of wasted resources from all contributors worldwide, and a lot of tokens indeed just pointing and managing the AI code rules from A to B.
.... When it's just A=B!

Guys, you are not trapped. You can switch to OpenCode and still use Claude models. If everybody does this the problem would be solved.

If everybody does this the problem would be solved.

Out of interest - if you are indeed satisfied with one of the available workarounds, how did you (and many others like you in this issue thread) even find yourself here? There's a new comment like this every couple of days, and it's pretty tiring to read, but also confusing.

Many of us are very aware of the available workarounds, and we want AGENTS.md support _despite_ that, and we have good reasons for this.

Sonnet 4.6

The Case for AGENTS.md: Why Claude Code Should Embrace the Emerging Standard

A long-read argument for naming conventions that reflect the world we're actually building

---

TL;DR: Claude Code reads CLAUDE.md for project context. But the industry is converging on AGENTS.md as the shared convention across tools and runtimes. Anthropic should lead — or at least follow — by supporting AGENTS.md natively. Here's why this matters more than it might seem.

---

Introduction: The README Moment for AI Agents

Every software project has a README.md. Nobody debates this. It's not because GitHub invented the convention, or because Markdown is technically superior to other formats. It's because the ecosystem converged — and convergence on conventions is one of the most quietly powerful forces in software development.

We are, right now, living through the equivalent moment for AI agents. Every serious AI coding assistant — Cursor, Windsurf, GitHub Copilot, OpenAI's tooling, and yes, Claude Code — needs a way to receive project-specific instructions. What tools exist, what coding standards apply, what context is essential, what the agent should never do. This is table stakes.

The question isn't whether to have such a file. The question is: what do we call it?

Claude Code chose CLAUDE.md. At first glance, this seems reasonable — even cute. But on deeper inspection, it's a mistake. Not a catastrophic one, not one that breaks anything today. But a mistake that will compound over time as the agentic ecosystem matures. The right name is AGENTS.md, and Anthropic should move toward supporting it.

Here's the full argument.

---

Part I: The Problem with Tool-Specific Naming

What CLAUDE.md actually says to the world

When you name a configuration file after your specific tool, you're making an implicit claim: this file is for Claude, and Claude alone. The name encodes a relationship between a file and a vendor. It's the equivalent of naming your database schema postgres-schema.sql instead of schema.sql — technically fine in a single-tool world, but subtly wrong in its assumptions.

CLAUDE.md says: "I have configured my project for one specific AI assistant."

AGENTS.md says: "I have defined how AI agents should work in this project."

This isn't just semantics. The file name is the first thing any developer — human or AI — sees when scanning a repository. It signals intent. It communicates the mental model of whoever created it. A file called CLAUDE.md communicates vendor lock-in, even if none was intended.

The polyglot agent reality

Here's the thing: almost no serious development team is using exactly one AI coding tool. Developers switch between Claude Code in the terminal, Cursor in VS Code, GitHub Copilot for quick completions, and whatever new agent ships next week. A solo developer might personally prefer Claude Code, but their colleague uses Windsurf. Their CI pipeline uses a different model entirely.

In this world — which is already the world we live in — a file called CLAUDE.md creates friction. Does Cursor read it? Does a custom LangChain-based agent know to look for it? What about the open-source agent framework a team member built? Each tool has to either:

1. Agree to read each other's files (requiring coordination across competing vendors), or
2. Ignore files they don't own (losing context), or
3. Ask users to maintain multiple instruction files for the same project.

Option 3 is what happens in practice. And it's absurd. The same instructions — "use TypeScript strict mode," "never commit to main directly," "our FHIR version is R4" — duplicated across CLAUDE.md, .cursorrules, copilot-instructions.md, and whatever else. This is exactly the kind of redundancy that destroys developer trust in tooling conventions.

---

Part II: The Industry Is Already Converging

OpenAI showed its hand

When OpenAI released its agent tooling and documentation, it used AGENTS.md as the reference convention for project-level agent instructions. This wasn't accidental. OpenAI has enormous influence on how developers think about building with AI, and naming their convention AGENTS.md was a deliberate choice to be tool-agnostic. The file describes what agents should do — not what OpenAI's agent should do.

This is a significant signal. When one of the two most influential AI labs uses a generic, agent-centric name, it creates gravitational pull. Developers who follow OpenAI's documentation will create AGENTS.md files. When they later adopt Claude Code, they will find that their existing convention is ignored. That's a poor onboarding experience, and it subtly positions Claude Code as the non-standard tool.

Framework authors are watching

The emerging agent framework ecosystem — LangChain, LangGraph, AutoGen, CrewAI, Haystack, and dozens of others — needs to decide how to handle project context. As these frameworks mature, many will land on a convention for "how do I read project-level instructions for the agents I'm running?" The frameworks that pick a standard will almost certainly pick the most widely-used one.

If AGENTS.md becomes that standard (and it's trending that way), then every framework that reads AGENTS.md automatically becomes compatible with projects that follow the convention — unless they're running Claude Code, which looks for something different.

The compounding effect here is real. Standards in software are subject to network effects. The more tools support AGENTS.md, the more developers create AGENTS.md files, the more tools must support it to remain relevant. Claude Code standing apart from this momentum doesn't make it more distinctive; it makes it less interoperable.

The README precedent matters

It's worth dwelling on how README.md became universal. In the early days of version control and open source, different platforms had different conventions. GitHub's rendering of README.md on the repository homepage was a huge accelerant — but even then, it wasn't a mandate. It worked because README.md was the right abstraction: a human-readable entry point for any project, not tied to any single platform's features.

AGENTS.md has the same quality. It names the thing being configured (agents) rather than the tool doing the configuring (Claude). This is good abstraction hygiene. Abstractions that outlive any single vendor's dominance are the ones that become foundational.

---

Part III: The Healthcare / Enterprise Angle

Why this matters even more in regulated domains

For those of us building in healthcare, finance, or other regulated industries, the stakes of tooling fragmentation are higher. Consider a healthcare IT team building a FHIR-based system — a context where the agent instructions might include things like:

• "Always validate resources against US Core profiles before generating code"
• "Never output patient identifiers in logs or test data"
• "Reference HL7 R4 for all FHIR operations unless explicitly told otherwise"
• "Our terminology server is at this endpoint"

These aren't casual preferences. They're compliance-relevant. When you have a team of five developers using three different AI tools, and the safety instructions only live in CLAUDE.md, you've created a gap. The Cursor user doesn't get the compliance instructions. The developer who spun up a quick AutoGen script certainly doesn't.

A widely-adopted AGENTS.md convention solves this. You put your compliance-critical instructions in one file, every tool reads it, and you have a single source of truth for how AI agents should behave in your regulated codebase. This is genuinely important infrastructure.

Multi-agent orchestration

The agentic revolution isn't just about a single developer talking to a single assistant. We're building systems where agents spawn agents — orchestrators that delegate to subagents, pipelines where multiple models collaborate. In these architectures, the concept of "project context" becomes even more critical, because you need every agent in the system to be working from the same playbook.

In a multi-agent FHIR pipeline, you might have:

• An orchestrator that parses clinical documents
• A subagent that maps them to FHIR resources
• A validation agent that checks conformance
• A transformation agent that handles R4-to-R5 conversion

Every single one of these agents needs to know the project conventions. With AGENTS.md as a standard, you can point every agent at the same file regardless of which framework or model powers it. With tool-specific naming, you either hard-code which file each agent reads or you maintain multiple files with duplicated content.

---

Part IV: The Naming Is About Identity and Philosophy

What kind of tool does Claude Code want to be?

There's a deeper question here about how Anthropic positions Claude Code in the ecosystem. There are two possible identities:

Identity A — The Opinionated Platform: Claude Code is a specific product with specific conventions. If you want to use it, you use its conventions. CLAUDE.md is part of that identity. It's like Apple saying "we use .xcodeproj" — it's proprietary, but that's fine because the product experience justifies it.

Identity B — The Excellent Open Participant: Claude Code is the best agent implementation of a shared standard. It reads AGENTS.md like everyone else, but it reads it better — it understands it more deeply, it uses it more intelligently, it adds value through superior model capability rather than through proprietary file formats.

Identity B is both more strategically sound and more philosophically coherent with Anthropic's stated mission. If Anthropic genuinely believes in a future where AI is beneficial to humanity broadly, that future is better served by open, interoperable standards than by vendor-specific lock-in.

Supporting AGENTS.md is a small gesture toward that open future. Refusing to support it — especially as the convention grows — is a small gesture toward the closed future.

The naming is also about humility

There's something a little uncomfortable about a tool that names its configuration file after itself. It implies a certain self-importance: this project exists to serve Claude, and Claude's file gets top billing.

AGENTS.md, by contrast, is humble in the right way. It doesn't presume which agent will read it. It doesn't encode a vendor relationship. It says: "Here is what any agent working on this project should know." That's the right epistemic posture for a tool that is, ultimately, in service of the developer and the project — not the other way around.

---

Part V: The Practical Path Forward

This isn't hard to implement

The good news is that supporting AGENTS.md doesn't require abandoning CLAUDE.md overnight. The implementation path is straightforward:

Phase 1 — Read both, prefer specificity. Claude Code reads AGENTS.md if present, and also reads CLAUDE.md if present. When both exist, CLAUDE.md takes precedence (allowing Claude-specific overrides), but AGENTS.md provides the baseline. This is backward compatible.

Phase 2 — Documentation and onboarding. New projects are guided to create AGENTS.md rather than CLAUDE.md. The documentation explains the philosophy: AGENTS.md is for universal instructions, CLAUDE.md is for Claude-specific tuning.

Phase 3 — Ecosystem communication. Anthropic publishes a clear statement that AGENTS.md is the supported standard. This gives framework authors and other tool builders a signal about interoperability. It's a tiny surface area change with potentially large ecosystem effects.

The merge strategy for coexistence

A clean mental model for how both files can coexist:

AGENTS.md        →  Universal project instructions for all AI agents
CLAUDE.md        →  Claude-specific overrides, capabilities, tool config

This separation is actually better than either file alone. It encourages developers to think clearly about which instructions are universal (coding standards, domain context, security constraints) versus which are tool-specific (how to use Claude's specific features, which MCP tools are configured, Claude-specific formatting preferences).

This is good software design: separating concerns, being explicit about the scope of each configuration layer.

---

Part VI: Counterarguments, Addressed Honestly

"CLAUDE.md is clearer about who reads it"

This argument has surface appeal — if you name the file after the tool, there's no ambiguity about who it's for. But this gets the direction of the relationship backwards. The file isn't for Claude; it's authored by developers to instruct agents. The right way to name a file is from the perspective of its purpose, not its consumer. We don't name package.json after npm. We don't name .gitignore after git. Tooling that reads configuration files is expected to understand file conventions — that's the tool's job.

"We can't just follow OpenAI's conventions"

Fair point — Anthropic shouldn't slavishly follow OpenAI in everything. But this isn't about following OpenAI; it's about following the emerging ecosystem standard that OpenAI happened to name well. If the community had converged on ROBOTS.md or CONTEXT.md or anything else, the argument would be the same. The question is whether the industry is converging, and on what. The answer appears to be: yes, and on AGENTS.md.

"Developers can always create AGENTS.md and rename it"

They can. But expecting developers to manually bridge conventions is exactly the kind of friction that erodes trust in tooling. Every "oh, I have to remember to do X for this tool" is a small cut. Enough small cuts and developers decide the tool isn't worth the cognitive overhead. More importantly, automated systems — CI agents, framework scaffolders, template generators — won't know to bridge the convention for you.

"CLAUDE.md enables Claude-specific features"

This is actually the strongest argument for keeping CLAUDE.md in addition to AGENTS.md — not instead of it. If certain Claude-specific instructions benefit from their own file, great. That's the coexistence model described above. But the general project instructions shouldn't require the Claude-specific file. The subset that's universal belongs in the universal file.

---

Conclusion: Small Naming Decisions, Large Ecosystem Consequences

Software history is littered with examples of small naming decisions that had large consequences — for better and worse. The proliferation of index.html as the default web page. The dominance of main over master for default branch names. The universality of Makefile. These aren't arbitrary artifacts; they're crystallized consensus that makes the entire ecosystem more legible, more interoperable, and lower-friction.

AGENTS.md is positioned to become one of these crystallized conventions. It has the right abstraction (agent instructions), the right scope (project-level), and early momentum from significant ecosystem players. The moment to join that convention is before it fully hardens — because after it hardens, late adoption looks like reluctant capitulation rather than principled participation.

Anthropic has an opportunity here that's easy to miss because it looks small. Supporting AGENTS.md in Claude Code is not just a file-naming decision. It's a statement about what kind of participant Anthropic wants to be in the emerging agentic ecosystem. It's a declaration that Claude Code's value comes from model quality and intelligence, not from proprietary conventions. It's an act of ecosystem citizenship.

The developers building the most complex, highest-stakes systems with AI — healthcare platforms, financial infrastructure, enterprise automation — are the ones who most need their tooling to play nicely together. They're also the ones who most directly feel the pain when it doesn't.

AGENTS.md. Read it. Support it. Help make it the README.md of the agentic age.

---

The author works in healthcare technology, building AI agents on top of FHIR infrastructure. He runs weekly sync calls called "Agents on FHIR" — which is either a clever pun or a sign that he thinks about this stuff too much.

---

Filed under: #claude-code #agents #developer-experience #standards #fhir #healthtech

w.r.t the hack of linking AGENTS.md in CLAUDE.md, how will this work if we have to maintain folder level context? doing this in every place sound ugly.. any other workarounds?

# Sonnet 4.6 # The Case for AGENTS.md: Why Claude Code Should Embrace the Emerging Standard _A long-read argument for naming conventions that reflect the world we're actually building_ > TL;DR: Claude Code reads CLAUDE.md for project context. But the industry is converging on AGENTS.md as the shared convention across tools and runtimes. Anthropic should lead — or at least follow — by supporting AGENTS.md natively. Here's why this matters more than it might seem. ## Introduction: The README Moment for AI Agents Every software project has a README.md. Nobody debates this. It's not because GitHub invented the convention, or because Markdown is technically superior to other formats. It's because the ecosystem _converged_ — and convergence on conventions is one of the most quietly powerful forces in software development. We are, right now, living through the equivalent moment for AI agents. Every serious AI coding assistant — Cursor, Windsurf, GitHub Copilot, OpenAI's tooling, and yes, Claude Code — needs a way to receive project-specific instructions. What tools exist, what coding standards apply, what context is essential, what the agent should never do. This is table stakes. The question isn't _whether_ to have such a file. The question is: what do we call it? Claude Code chose CLAUDE.md. At first glance, this seems reasonable — even cute. But on deeper inspection, it's a mistake. Not a catastrophic one, not one that breaks anything today. But a mistake that will compound over time as the agentic ecosystem matures. The right name is AGENTS.md, and Anthropic should move toward supporting it. Here's the full argument. ## Part I: The Problem with Tool-Specific Naming ### What CLAUDE.md actually says to the world When you name a configuration file after your specific tool, you're making an implicit claim: _this file is for Claude, and Claude alone._ The name encodes a relationship between a file and a vendor. It's the equivalent of naming your database schema postgres-schema.sql instead of schema.sql — technically fine in a single-tool world, but subtly wrong in its assumptions. CLAUDE.md says: _"I have configured my project for one specific AI assistant."_ AGENTS.md says: _"I have defined how AI agents should work in this project."_ This isn't just semantics. The file name is the first thing any developer — human or AI — sees when scanning a repository. It signals intent. It communicates the mental model of whoever created it. A file called CLAUDE.md communicates vendor lock-in, even if none was intended. ### The polyglot agent reality Here's the thing: almost no serious development team is using exactly one AI coding tool. Developers switch between Claude Code in the terminal, Cursor in VS Code, GitHub Copilot for quick completions, and whatever new agent ships next week. A solo developer might personally prefer Claude Code, but their colleague uses Windsurf. Their CI pipeline uses a different model entirely. In this world — which is already the world we live in — a file called CLAUDE.md creates friction. Does Cursor read it? Does a custom LangChain-based agent know to look for it? What about the open-source agent framework a team member built? Each tool has to either: 1. Agree to read each other's files (requiring coordination across competing vendors), or 2. Ignore files they don't own (losing context), or 3. Ask users to maintain _multiple_ instruction files for the same project. Option 3 is what happens in practice. And it's absurd. The same instructions — "use TypeScript strict mode," "never commit to main directly," "our FHIR version is R4" — duplicated across CLAUDE.md, .cursorrules, copilot-instructions.md, and whatever else. This is exactly the kind of redundancy that destroys developer trust in tooling conventions. ## Part II: The Industry Is Already Converging ### OpenAI showed its hand When OpenAI released its agent tooling and documentation, it used AGENTS.md as the reference convention for project-level agent instructions. This wasn't accidental. OpenAI has enormous influence on how developers think about building with AI, and naming their convention AGENTS.md was a deliberate choice to be tool-agnostic. The file describes what agents should do — not what _OpenAI's_ agent should do. This is a significant signal. When one of the two most influential AI labs uses a generic, agent-centric name, it creates gravitational pull. Developers who follow OpenAI's documentation will create AGENTS.md files. When they later adopt Claude Code, they will find that their existing convention is ignored. That's a poor onboarding experience, and it subtly positions Claude Code as the _non-standard_ tool. ### Framework authors are watching The emerging agent framework ecosystem — LangChain, LangGraph, AutoGen, CrewAI, Haystack, and dozens of others — needs to decide how to handle project context. As these frameworks mature, many will land on a convention for "how do I read project-level instructions for the agents I'm running?" The frameworks that pick a standard will almost certainly pick the most widely-used one. If AGENTS.md becomes that standard (and it's trending that way), then every framework that reads AGENTS.md automatically becomes compatible with projects that follow the convention — _unless_ they're running Claude Code, which looks for something different. The compounding effect here is real. Standards in software are subject to network effects. The more tools support AGENTS.md, the more developers create AGENTS.md files, the more tools must support it to remain relevant. Claude Code standing apart from this momentum doesn't make it more distinctive; it makes it less interoperable. ### The README precedent matters It's worth dwelling on how README.md became universal. In the early days of version control and open source, different platforms had different conventions. GitHub's rendering of README.md on the repository homepage was a huge accelerant — but even then, it wasn't a mandate. It worked because README.md was the _right abstraction_: a human-readable entry point for any project, not tied to any single platform's features. AGENTS.md has the same quality. It names the _thing_ being configured (agents) rather than the tool doing the configuring (Claude). This is good abstraction hygiene. Abstractions that outlive any single vendor's dominance are the ones that become foundational. ## Part III: The Healthcare / Enterprise Angle ### Why this matters even more in regulated domains For those of us building in healthcare, finance, or other regulated industries, the stakes of tooling fragmentation are higher. Consider a healthcare IT team building a FHIR-based system — a context where the agent instructions might include things like: "Always validate resources against US Core profiles before generating code" "Never output patient identifiers in logs or test data" "Reference HL7 R4 for all FHIR operations unless explicitly told otherwise" "Our terminology server is at this endpoint" These aren't casual preferences. They're compliance-relevant. When you have a team of five developers using three different AI tools, and the safety instructions only live in CLAUDE.md, you've created a gap. The Cursor user doesn't get the compliance instructions. The developer who spun up a quick AutoGen script certainly doesn't. A widely-adopted AGENTS.md convention solves this. You put your compliance-critical instructions in one file, every tool reads it, and you have a single source of truth for how AI agents should behave in your regulated codebase. This is genuinely important infrastructure. ### Multi-agent orchestration The agentic revolution isn't just about a single developer talking to a single assistant. We're building systems where agents spawn agents — orchestrators that delegate to subagents, pipelines where multiple models collaborate. In these architectures, the concept of "project context" becomes even more critical, because you need every agent in the system to be working from the same playbook. In a multi-agent FHIR pipeline, you might have: An orchestrator that parses clinical documents A subagent that maps them to FHIR resources A validation agent that checks conformance A transformation agent that handles R4-to-R5 conversion Every single one of these agents needs to know the project conventions. With AGENTS.md as a standard, you can point every agent at the same file regardless of which framework or model powers it. With tool-specific naming, you either hard-code which file each agent reads or you maintain multiple files with duplicated content. ## Part IV: The Naming Is About Identity and Philosophy ### What kind of tool does Claude Code want to be? There's a deeper question here about how Anthropic positions Claude Code in the ecosystem. There are two possible identities: Identity A — The Opinionated Platform: Claude Code is a specific product with specific conventions. If you want to use it, you use its conventions. CLAUDE.md is part of that identity. It's like Apple saying "we use .xcodeproj" — it's proprietary, but that's fine because the product experience justifies it. Identity B — The Excellent Open Participant: Claude Code is the best agent implementation of a shared standard. It reads AGENTS.md like everyone else, but it reads it _better_ — it understands it more deeply, it uses it more intelligently, it adds value through superior model capability rather than through proprietary file formats. Identity B is both more strategically sound and more philosophically coherent with Anthropic's stated mission. If Anthropic genuinely believes in a future where AI is beneficial to humanity broadly, that future is better served by open, interoperable standards than by vendor-specific lock-in. Supporting AGENTS.md is a small gesture toward that open future. Refusing to support it — especially as the convention grows — is a small gesture toward the closed future. ### The naming is also about humility There's something a little uncomfortable about a tool that names its configuration file after itself. It implies a certain self-importance: _this project exists to serve Claude, and Claude's file gets top billing._ AGENTS.md, by contrast, is humble in the right way. It doesn't presume which agent will read it. It doesn't encode a vendor relationship. It says: _"Here is what any agent working on this project should know."_ That's the right epistemic posture for a tool that is, ultimately, in service of the developer and the project — not the other way around. ## Part V: The Practical Path Forward ### This isn't hard to implement The good news is that supporting AGENTS.md doesn't require abandoning CLAUDE.md overnight. The implementation path is straightforward: Phase 1 — Read both, prefer specificity. Claude Code reads AGENTS.md if present, and also reads CLAUDE.md if present. When both exist, CLAUDE.md takes precedence (allowing Claude-specific overrides), but AGENTS.md provides the baseline. This is backward compatible. Phase 2 — Documentation and onboarding. New projects are guided to create AGENTS.md rather than CLAUDE.md. The documentation explains the philosophy: AGENTS.md is for universal instructions, CLAUDE.md is for Claude-specific tuning. Phase 3 — Ecosystem communication. Anthropic publishes a clear statement that AGENTS.md is the supported standard. This gives framework authors and other tool builders a signal about interoperability. It's a tiny surface area change with potentially large ecosystem effects. ### The merge strategy for coexistence A clean mental model for how both files can coexist: `` AGENTS.md → Universal project instructions for all AI agents CLAUDE.md → Claude-specific overrides, capabilities, tool config ` This separation is actually _better_ than either file alone. It encourages developers to think clearly about which instructions are universal (coding standards, domain context, security constraints) versus which are tool-specific (how to use Claude's specific features, which MCP tools are configured, Claude-specific formatting preferences). This is good software design: separating concerns, being explicit about the scope of each configuration layer. ## Part VI: Counterarguments, Addressed Honestly ### "CLAUDE.md is clearer about who reads it" This argument has surface appeal — if you name the file after the tool, there's no ambiguity about who it's for. But this gets the direction of the relationship backwards. The file isn't _for_ Claude; it's _authored by developers_ to instruct agents. The right way to name a file is from the perspective of its purpose, not its consumer. We don't name package.json after npm. We don't name .gitignore after git. Tooling that reads configuration files is expected to understand file conventions — that's the tool's job. ### "We can't just follow OpenAI's conventions" Fair point — Anthropic shouldn't slavishly follow OpenAI in everything. But this isn't about following OpenAI; it's about following the emerging ecosystem standard that OpenAI happened to name well. If the community had converged on ROBOTS.md or CONTEXT.md or anything else, the argument would be the same. The question is whether the industry is converging, and on what. The answer appears to be: yes, and on AGENTS.md. ### "Developers can always create AGENTS.md and rename it" They can. But expecting developers to manually bridge conventions is exactly the kind of friction that erodes trust in tooling. Every "oh, I have to remember to do X for this tool" is a small cut. Enough small cuts and developers decide the tool isn't worth the cognitive overhead. More importantly, automated systems — CI agents, framework scaffolders, template generators — won't know to bridge the convention for you. ### "CLAUDE.md enables Claude-specific features" This is actually the strongest argument for keeping CLAUDE.md _in addition to_ AGENTS.md — not instead of it. If certain Claude-specific instructions benefit from their own file, great. That's the coexistence model described above. But the general project instructions shouldn't require the Claude-specific file. The subset that's universal belongs in the universal file. ## Conclusion: Small Naming Decisions, Large Ecosystem Consequences Software history is littered with examples of small naming decisions that had large consequences — for better and worse. The proliferation of index.html as the default web page. The dominance of main over master for default branch names. The universality of Makefile. These aren't arbitrary artifacts; they're crystallized consensus that makes the entire ecosystem more legible, more interoperable, and lower-friction. AGENTS.md is positioned to become one of these crystallized conventions. It has the right abstraction (agent instructions), the right scope (project-level), and early momentum from significant ecosystem players. The moment to join that convention is before it fully hardens — because after it hardens, late adoption looks like reluctant capitulation rather than principled participation. Anthropic has an opportunity here that's easy to miss because it looks small. Supporting AGENTS.md in Claude Code is not just a file-naming decision. It's a statement about what kind of participant Anthropic wants to be in the emerging agentic ecosystem. It's a declaration that Claude Code's value comes from model quality and intelligence, not from proprietary conventions. It's an act of ecosystem citizenship. The developers building the most complex, highest-stakes systems with AI — healthcare platforms, financial infrastructure, enterprise automation — are the ones who most need their tooling to play nicely together. They're also the ones who most directly feel the pain when it doesn't. AGENTS.md. Read it. Support it. Help make it the README.md of the agentic age. _The author works in healthcare technology, building AI agents on top of FHIR infrastructure. He runs weekly sync calls called "Agents on FHIR" — which is either a clever pun or a sign that he thinks about this stuff too much._ **Filed under:** #claude-code #agents #developer-experience #standards #fhir #healthtech`

People hates reading long AI generated comment. Don't try to use AI for everything.

Willing to red line the DoD for public good. Unwilling to use the same standard as everyone else for public good.

Very interesting choices.

@natthapolvanasrivilai GPT Slop Comment

Unwilling to use the same standard as everyone else for public good.

Yeah this seems like a strong stance to break comparability, with no real reason other than trying to drive vendor lock-in (remember, there is no moat -- so I guess you got to try to dig one).

Been thinking to write a simple script that adds a global git hook to symlink any repo I use between those two files. Thumbs up to lmk if that would be valuable. Would be something like npx agents-md-hook To install On Mar 3, 2026, at 8:18 PM, William Roush @.***> wrote:StrangeWill left a comment (anthropics/claude-code#6235)

Unwilling to use the same standard as everyone else for public good.

Yeah this seems like a strong stance to break comparability, with no real reason other than trying to drive vendor lock-in (remember, there is no moat -- so I guess you got to try to dig one).

—Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you were mentioned.Message ID: @.***>

Been thinking to write a simple script that adds a global git hook to symlink any repo I use between those two files. Thumbs up to lmk if that would be valuable.

The problem (and this is detailed in Git's own docs), Symlinks aren't all created equal, Windows has a bad time with them normally, and on Git IIRC they're disabled by default, I know Windows devs are generally not thought about, but they do exist, and there's a lot of them.

For now I'm generally just sticking with Claude, but as we know, there is no moat and I expect to use other models in the future, model portability will be more of a thing, and either Claude is on-board and can be a model of choice, or projects will support the standard and tell Claude users to deal.

> ## Part VI: Counterarguments, Addressed Honestly > ### "CLAUDE.md is clearer about who reads it" > This argument has surface appeal — if you name the file after the tool, there's no ambiguity about who it's for. But this gets the direction of the relationship backwards. The file isn't _for_ Claude; it's _authored by developers_ to instruct agents. The right way to name a file is from the perspective of its purpose, not its consumer. We don't name package.json after npm. We don't name .gitignore after git. Tooling that reads configuration files is expected to understand file conventions — that's the tool's job.

Wait a minute, you're telling me .gitignore _isn't_ named after git?

Wait a minute, you're telling me .gitignore isn't named after git?

I think they meant to say that it's not named after _Github_. It's rightly called .gitignore rather than .githubignore because Gitlab, Bitbucket etc should be able to consume this also.

To avoid vendor lock-in, open-source repos should more and more use an AGENTS.md file rather than a CLAUDE.md. This means that as a claude user, I'm gonna have to add a CLAUDE.md file containing @AGENTS.md to every repo I work on that adopts this standard. This is tedious, especially if I also have to add CLAUDE.md to the .gitignore.

> Wait a minute, you're telling me .gitignore isn't named after git? I think they meant to say that it's not named after _Github_. It's rightly called .gitignore rather than .githubignore because Gitlab, Bitbucket etc should be able to consume this also.

git and gitignore predate github

I hope decision makers working on Claude recognize how visible and omnipresent this issue is for working engineers. I have written hundreds of these files by now:
<img width="264" height="114" alt="Image" src="https://github.com/user-attachments/assets/a7409216-bd5b-40a9-82b9-cfca09d6af77" />

You've built a lot of good will by shipping fantastic and innovative tools. But that's all you've done so far. At some point, you need to also work to nourish and maintain trust. Trust means knowing you can export all data intact from your knowledge base after using it for years. Trust means knowing your email client won't start adding "Written with X" in your footers at some point. In other words, trust means not compromising the user's workflow or outcomes purely to serve your own marketing and ecosystem agendas.

Please recognize:

• Little details like this truly matter. You're guaranteeing a small but constantly recurring negative impression for a huge cohort of professional developers. Sentiment does not obey the laws of reason, and repetition is one of the fastest ways into the pit.
• There is now a large ecosystem of agentic coding tools out there. You shipped one of the first, still one of the best, and everyone knows it. You don't need to resort to little tricks to keep that position, you just need to _lead_. Be the first to open standards next, and you'll cement your legacy.

Workaround via SessionStart hook (global, zero per-project overhead)

For anyone blocked on this: Claude Code's SessionStart hook can inject a project's AGENTS.md automatically without any per-project CLAUDE.md. Tested and working.

Add to ~/.claude/settings.json:

"hooks": {
  "SessionStart": [
    {
      "matcher": "*",
      "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/load-agents-md.sh" }]
    }
  ]
}

Create ~/.claude/hooks/load-agents-md.sh:

#!/usr/bin/env bash
set -euo pipefail
AGENTS_FILE="${CLAUDE_PROJECT_DIR}/AGENTS.md"
CLAUDE_FILE="${CLAUDE_PROJECT_DIR}/CLAUDE.md"
[ -f "$AGENTS_FILE" ] || exit 0
if [ -f "$CLAUDE_FILE" ] && grep -q "@AGENTS.md" "$CLAUDE_FILE"; then exit 0; fi
echo "=== Project AGENTS.md ==="
cat "$AGENTS_FILE"

Make it executable: chmod +x ~/.claude/hooks/load-agents-md.sh

The hook injects the project AGENTS.md into context at session start. It skips if AGENTS.md is absent, or if CLAUDE.md already imports it via @AGENTS.md to avoid duplication. Both files coexist and are complementary when present.

For global ~/.claude/AGENTS.md, the @ import in ~/.claude/CLAUDE.md remains the more reliable mechanism (preprocessor-level, not a shell command).

Still not a substitute for native support — every other major tool reads AGENTS.md out of the box.

I’m curious about how the discussion or progress regarding this issue is currently going.

In our team, different members use a variety of models such as Codex, Gemini, Claude, and Z AI.
Because of this multi-model environment, we are organizing Agents.md as a shared guideline to keep our team conventions consistent.

However, Claude Code currently does not properly recognize Agents.md.
There are some workaround methods, but they still require extra manual steps whenever:

a new team member joins, or

an existing member starts using Claude.

In practice, this means we need to perform additional setup just to make Claude recognize Agents.md, which introduces unnecessary friction in collaboration.

At the same time, models are evolving very quickly.
Performance benchmarks are being checked almost daily, and model rankings change frequently.

As a result, users are subscribing to and using multiple models simultaneously, and this trend will likely continue to grow.

In such an environment, I believe two things are especially important:

Simple and lightweight environment setup

A high level of shared configuration across models

Because of this, it feels a bit unfortunate that Claude Code — which many of us have relied on — seems to be falling behind this trend in terms of usability.

If there are any updates, ongoing discussions, or decisions regarding this issue, I would greatly appreciate it if you could share them with the community.

Here's another hook also ensuring AGENTS.md is created on /init:

Create ~/.claude/hooks/inject-init-override.sh

#!/usr/bin/env bash
set -euo pipefail

if grep -q '"/init' /dev/stdin; then
  echo "IMPORTANT OVERRIDE: The file must be named AGENTS.md, not CLAUDE.md. Use '# AGENTS.md' as the file header and 'This file provides guidance to AI agents when working with code in this repository.' as the subtitle. Do NOT use '# CLAUDE.md' under any circumstances."
fi

Add to ~/.claude/settings.json:

  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "*",
        "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/inject-init-override.sh" }]
      }
    ],
  }

Great feature request! The AGENTS.md standardization is gaining momentum across the ecosystem.

For implementation, consider:

1. Cascade loading: AGENTS.md > CLAUDE.md > .claude/settings
2. Merge strategy: Combine both files with AGENTS.md taking precedence for agent-specific instructions
3. Backward compatibility: Keep CLAUDE.md working for existing users

OpenClaw (our project) uses AGENTS.md for agent routing and persona configuration - it's been working well. Happy to share our structure if helpful!

For teams that need AGENTS.md-style coordination across machines and runtimes, we built GNAP — a git-native protocol that extends this concept:

.gnap/
  agents.json      → team members (human + AI)
  tasks/*.json      → work items with state machine
  runs/*.json       → execution attempts + cost tracking
  messages/*.json   → agent-to-agent communication

Same philosophy: agents read structured files to understand their role. But works across Claude Code, Codex, OpenClaw, or any runtime — all coordinating through git push/pull.

Would love to see AGENTS.md and GNAP work together — AGENTS.md for single-repo agent behavior, GNAP for multi-agent team orchestration.

we use CLAUDE.md heavily across multiple projects and the vendor-specificity is a real friction point. our global CLAUDE.md has identity, credentials, workflow patterns, testing requirements, and multi-agent coordination rules - none of which is Claude-specific logic.

the practical issue: when collaborating with others who use different agents, they ignore CLAUDE.md entirely. an AGENTS.md standard would mean this configuration works across tools.

that said, CLAUDE.md has features that matter: the hierarchical loading (global ~/.claude/CLAUDE.md + project-level + directory-level), the auto-loading without explicit import, and the memory system integration. any AGENTS.md spec would need to support this hierarchy or it becomes less useful than what we have now.

our suggestion: support both. read AGENTS.md as an alias, but keep CLAUDE.md working with the full feature set. if both exist, merge them (AGENTS.md first, CLAUDE.md overrides for Claude-specific behavior). this way teams can put shared rules in AGENTS.md and Claude-specific config in CLAUDE.md

our multi-level CLAUDE.md setup for reference: global instructions at ~/.claude/CLAUDE.md, per-project CLAUDE.md files, plus a memory system that extends it: https://github.com/m13v/user-memories. the agent orchestration that relies on this hierarchy: https://github.com/m13v/tmux-background-agents

Is it not possible to symlink CLAUDE.md to AGENTS.md and commit the symlink to git? Seems like that is the best workaround for now.

Does anybody have any workarounds in the meantime? I find myself duplicating the contents of CLAUDE.md/AGENTS.md and cursor rules just so I can have consistent memory as I move across tools.

Just symlink CLAUDE.md and name the symlink AGENTS.md. The command (in bash) is:

ln -s CLAUDE.md AGENTS.md

Run that inside a directory containing CLAUDE.md, and it will do exactly what I've suggested. If you're not familiar with them, symlinks are basically like pointers or shortcuts to another file or folder. It's basically a tiny file containing the filepath to the CLAUDE.md file, so whenever your computer references the symlink file path, the symlink says "I think this is what you're looking for points to CLAUDE.md" and the computer goes "thank you kindly!" and goes to the CLAUDE.md file just as if you'd given it it's regular file path.

Whenever the file path to the AGENTS.md symlink is referenced, it will send the computer to the CLAUDE.md that you linked it to. It's not a copy, it's a link to the original file, which means you don't have to worry about maintaining two separate copies.

The problem with symlinking is that it requires the repository to anticipate use by Claude.

Consider a one-off contributor workflow:

• git clone the target repository
• Symlink AGENTS.md to CLAUDE.md???
• claude -> prompt the change for contribution
• Remove symlink or otherwise ensure it's not being committed inadvertently???
• fork, push, and open pull request

Could the CLAUDE.md symlink be committed? Sure, but that's the maintainer's call, not the contributor's.

To prevent comitting, a user could add it to their global excludesFile's. And creating the symlink could be globally solved with a git post-checkout hook: if AGENTS.md exists, and CLAUDE.md does not -> ln -s

Symlinks are not a breeze on Windows, but otherwise, yes, the symlink trick is what I am using too.

However, this is a workaround. Me, and many others that upvoted this issue, would like the first citizen treatment of AGENTS.md.

@clouatre I credited your approach in use-agents

The symlink/duplication problem is real. I maintain a Claude Code setup with 12 specialized agents and the instruction files are already complex enough without copying them per-tool.

Until AGENTS.md lands, what helped me was structuring everything under a single CLAUDE.md with clear sections per agent role — keeps it in one place at least. Shared the structure here if useful: https://github.com/Koroqe/claude-code-sdlc

... structuring everything under a single CLAUDE.md ...

In general, this should not be done since the entirety of CLAUDE.md is loaded into the session, but I guess that worked for your specific use case

We use AGENTS.md extensively in our project — MEEET World runs 657 AI agents coordinated through a shared API.

Our agent architecture:

• 6 specialized classes with distinct system prompts
• Shared task pool (56 research quests)
• Global chat for agent coordination
• Peer review for quality assurance

If Claude Code supports AGENTS.md, it would make it much easier to spin up new MEEET agents directly from the IDE.

Open source: github.com/alxvasilevvv/meeet-solana-state

I have a symbolic link between AGENTS.md and CLAUDE.md but this confuses Claude: half the time it commits the symlink instead of the modified file.

Voicing my support for this feature. We need standardization!

Voicing my support for this feature. We need standardization!

If the argument is that it's nice to have a place for Claude specific instructions, why not load AGENT.md _and_ CLAUDE.md ? (perhaps behind a flag so people have a way to adopt)

We can cut Anthropic some slack since they created CLAUDE.md before anyone else came along with AGENTS.md. (Why don't they just follow the standard? Oh, because they preceded it!)

However, the user experience of their customers OUGHT to be a priority for them. (Given their handling of the Windsurf rumors, I have reason to seriously doubt whether our UX is a priority for them...) I can see lots of reasons why they wouldn't outright switch to AGENTS.md. I can't see any reason, though, for not at least falling back to AGENTS.md when CLAUDE.md is not present. That would not inconvenience current customers who are happily using CLAUDE.md, and I think it would make life easier for people moving TO Claude Code, especially teams with members using different tools.

Perhaps Anthropic wants CLAUDE.md files to be their "blue bubbles" to lock in customers. While slightly annoying, we must admit that in some ways they've earned it by blazing new trails.

But there is a solution. Just put this in your CLAUDE.md file:

# Because Anthropic does not prioritize the convenience of its customers by automatically falling back to AGENTS.md, we need this:
@AGENTS.md

You get the convenience and interoperability of only needing to maintain edits in one file, can still use Claude, and you signal your displeasure to Anthropic for their UX failure, and slightly reduce the benefits of their signal of ubiquity.

We can cut Anthropic some slack since they created CLAUDE.md before anyone else came along with AGENTS.md. (Why don't they just follow the standard? Oh, because they preceded it!)

By that logic we should all be using copilot-instructions.md

A UserPromptSubmit hook can inject AGENTS.md content into every session, giving you cross-agent compatibility today:

AGENTS_FILE=""
for f in ./AGENTS.md ./agents.md ./.agents.md; do
    [ -f "$f" ] && AGENTS_FILE="$f" && break
done
[ -z "$AGENTS_FILE" ] && exit 0
CONTENT=$(cat "$AGENTS_FILE")
[ -z "$CONTENT" ] && exit 0
jq -n --arg ctx "Instructions from AGENTS.md (cross-agent config):
$CONTENT" '{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": $ctx
  }
}'
exit 0

Add to ~/.claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "",
      "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/agents-md-loader.sh" }]
    }]
  }
}

This way:

• Teams can maintain a single AGENTS.md that works for Codex, Amp, Cursor, AND Claude Code
• Claude Code reads it via the hook on every turn
• No need to duplicate rules in both AGENTS.md and CLAUDE.md

For a bidirectional setup (AGENTS.md as the source, CLAUDE.md auto-generated):

[ -f AGENTS.md ] && cp AGENTS.md CLAUDE.md

Or if you want AGENTS.md to augment (not replace) CLAUDE.md, the hook above works alongside the native CLAUDE.md loading — both sets of instructions apply.

Claude Code's source code has been leaked via a map file in their NPM registry

Now that Claude Code's source code is leaked, can we finally get this changed to use https://agents.md/?

@wcygan savage 😂 #TooSoon ?

Given the formation of the Agentic AI Foundation by Amazon Web Services, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft and OpenAI to "lay the groundwork for a shared ecosystem of tools, standards, and community-driven innovation" and the initial contribution of AGENTS.md as a standard, not adopting it seems to be a glaring omission and antithesis to the goals of the foundation Anthropic just founded! It's a simple change to support another filename and prevents the entire development community from having to hack around it. IMHO, it makes Anthropic seem a bit of an ass.

Something I saw in the last few days (something in the Claude.ai UI maybe, or in a conversation with Claude or Claude Code—I don't recall) implied that they already support AGENTS.md. Has anyone verified that this has not ALREADY been fixed?

@davelowndes Exactly — this is the key contradiction. Anthropic co-founded the Agentic AI Foundation alongside AWS, Google, Microsoft, OpenAI specifically to build "shared ecosystem of tools, standards, and community-driven innovation."

AGENTS.md was contributed as a standard through this foundation. Not supporting it in Claude Code undermines the very initiative Anthropic helped create.

From our experience building MEEET World (1,020 AI agents on Solana), cross-agent compatibility isn't optional — it's infrastructure. Our agents need to work with Claude Code, Cursor, Windsurf, and others seamlessly. AGENTS.md solves this.

The workaround by @yurukusa (UserPromptSubmit hook) proves demand exists. But workarounds shouldn't be necessary for a standard your own foundation promotes.

The ask is simple: recognize AGENTS.md alongside CLAUDE.md. One filename. Massive ecosystem impact.

🔗 meeet.world | GitHub

While a standard is being agreed upon, would it be possible to add a command line switch to indicate what file should be read on start up?\
This will greatly assist with any future migrations as teams can cut over to the new file conventions when they are ready.\
Default should be CLAUDE.md as mentioned before, but you should be able to overwrite it to what ever you like on startup.\
When there is a standard defined, the switch's defaults can be updated to reflect the change (with the right deprecation warnings etc etc).\
Putting the onus of providing the path on the user, instead of looking for common paths, allows them to migrate from any tool with a context to Claude, not just those that support AGENTS.md.

I am happy to write this up as a separate issue if people see utility.

workaround: in CLAUDE.md：

Read this file before
 taking any action: `AGENTS.md`

For anyone look for workaround until it is implement, you could try this:
rename your CLAUDE.md file to AGENTS.md, create a symbolic link that called CLAUDE.md that points to AGENTS.md. Here is the command to achive the above mentioned steps

mv CLAUDE.md AGENTS.md
ln -s AGENTS.md CLAUDE.md

Commit your AGENTS.md & CLAUDE.md

Respectfully, all of these various workarounds have been circled around many times in this thread. They are well documented and understood at this point. This feature request is to support it without hacky workarounds.

Respectfully, all of these various workarounds have been circled around many times in this thread. They are well documented and understood at this point. This feature request is to support it without hacky workarounds.

@ericmatthys I am totally in favor of its implemenation , just added a work around to help anyone looking for aa way a live with it until it is implement

Respectfully, all of these various workarounds have been circled around many times in this thread. They are well documented and understood at this point. This feature request is to support it without hacky workarounds.

I would also add that the CLAUDE.md vs AGENTS.md file is the least of the problems... a one and only set of skills, commands, settings, mcps, etc seems more important to me. Particularly nowadays having an .agents/skills folder that all agents read on startup is a must and what causes me more headaches.

All of these workarounds seem to completely miss the point of AGENTS.md - if it was just a single file at the root of your project then sure, who cares, just write @AGENTS.md in CLAUDE.md and you're done.

But what about when you have many differently scoped AGENTS.md files, across the whole repo?
The point of this file is that it is SCOPED - it is read as the code along side it is read, to provide context.
The workaround in this case is then, what? Duplicating every single file across every single tool across every single scope or package? Insanity.

Real-world AGENTS.md implementation report from MEEET World (1,020 AI agents).

We've been running AGENTS.md in production and just shipped v3.0 with full support:

Our AGENTS.md includes:

• DID identity config (did:meeet + Ed25519)
• 6 agent role templates with domain isolation
• Capability declarations per role
• 6-layer trust stack configuration
• Economic parameters ($MEEET staking rules)
• Integration endpoints (APS, MolTrust, Signet, VeroQ, Google ADK)

What AGENTS.md solves for us:

@chernistry's file conflict problem → Our AGENTS.md defines allowed_domains per role. Quantum researchers can't touch biotech files. Domain isolation prevents conflicts across 1,020 agents.

@Zerquix18's duplication problem → Single AGENTS.md works across Claude Code, Cursor, and our custom MCP servers. One file, all tools.

Live implementation: AGENTS.md in our repo

Also shipped: aps.txt — like robots.txt but for AI agents. Defines access levels for internal vs external agents.

Full platform: meeet.world | Developer Portal | Live Dashboard

AGENTS.md Is Live — Production Example

@chernistry @ericmatthys @sanathusk

Shipped AGENTS.md in production with 1,020 AI agents:

https://github.com/alxvasilevvv/meeet-solana-state/blob/main/AGENTS.md

Includes: Identity config (DID, Ed25519, resolver, JWKS), capabilities, domain isolation, 6 role templates with min reputation, 6-layer trust stack, all API endpoints, integration partners.

Also shipped aps.txt at meeet.world/aps.txt — like robots.txt but for AI agents. Defines access levels for internal, external, and public agents.

@chernistry — Bernstein compatibility

Role system solves file conflicts: each agent has assigned domains/capabilities, before-tool callback checks permissions, /api/roles/check verifies scope.

15 new pages shipped:

meeet.world/live | /governance | /staking | /social | /explorer | /sara | /roles | /passport/{id} | /developer | /attestations | /did/{id}

40+ pages. 30+ API endpoints. Docs: meeet.world/developer

💻 github.com/alxvasilevvv/meeet-solana-state

At this point now, I am thinking that the agreement around AGENTS.md should be rewriten so the rules how it works are closer to how CLAUDE.md works. Then there won't be any more justification for Anthropic to avoid solving this ticket. CLAUDE.md could be just deprecated until few years time and we would have only single source of truth.

You can use this project to translate your Agents.md into Claude.md and viceversa: https://github.com/Co7omo/agentx

Thanks for sharing! That agentx project looks useful for bridging the gap.

Having worked with AGENTS.md extensively in OpenClaw, I think both approaches have merit:

• AGENTS.md: Great for cross-tool compatibility, as you noted
• CLAUDE.md: More Claude Code-specific optimizations

A conversion tool like agentx could help teams transition gradually or maintain both formats during adoption. The real win would be if the major coding agents could agree on a common subset of the AGENTS.md spec that works well across platforms.

@CosimoAgnusdei - does agentx handle the behavioral instructions and memory patterns that AGENTS.md typically includes, or is it focused mainly on project structure documentation?

Claude Code today offered to update the existing AGENTS.md file in a repo I cloned when I typed /init, instead of creating CLAUDE.md.

<img width="1680" height="404" alt="Image" src="https://github.com/user-attachments/assets/68f01a3d-056d-4c34-ad72-ff96d634f861" />

This may not be everything, but it's a clear step in the direction of standardizing on AGENTS.md.

Also worth noting that /init creates text that seems to target Claude directly (like "provides guidance to Claude Code (claude.ai/code)"). When AGENTS.md is supported it should probably make sure this output is generic.

While we wait for Claude to do this, try this:

ln -s AGENTS.md CLAUDE.md

Now anytime your read/write from/to AGENTS.md, CLAUDE.md gets updated too

Lol, a lot of smoke on this LLM trends, and this being an easy MR/Fix just show how is this all about:

• LLMs are just probabilistic (not correct) broadcasters, their agents are not able to handle this simple request to read another file, on this case AGENTS.md (a simple MR that a junior or even learner developer would do)
• Anthropic (and all the "AI companies") just want money, and they want to impose and set the narrative (they are even part of this "Agentic AI Foundation"), and they don't want to implement this.

Or both are just true.

Stop complaining about his not being made, they want money, that's all, just focus on local LLMs and for now just be the "cow milkers" of the VCs to follow to that path.

People, please stop posting the same bs over and over again. We know about the symlinks and we know your life depends on this ticket; move on, no one needs ten emails from this thread everyday.

@asarkar unless (perhaps) the OP adds "DO NOT SUGGEST WORKAROUNDS" to the title, it seems likely that someone will repeatedly make the same suggestion every few days. (People don't take the time to read the entire thread before replying!)

A more immediately effective solution if you don't want e-mail notifications of every repeated suggestion about symlinks would be to unsubscribe from the thread. That is what I've done. Anthropic is already in the process of adding support for AGENTS.md and will hopefully continue that trend.

If you want to address the larger problem of unwanted notifications, pressure GitHub into allowing us to subscribe ONLY to significant updates on an issue. "Significant" could be defined a number of ways, such as anything that alters the status of the issue, or that plus any comment with at least X upvotes.... The details of the definition are not as important as just giving us a way to ONLY subscribe to things with higher signal value so we can filter out much of the noise.

If you want to address the larger problem of unwanted notifications, pressure GitHub into allowing us to subscribe ONLY to significant updates on an issue

<img width="482" height="441" alt="Image" src="https://github.com/user-attachments/assets/e24920ca-db3e-4cdc-942d-b1a52410cf1d" />

😁

It seems to be working.
<img width="403" height="226" alt="Image" src="https://github.com/user-attachments/assets/2bffc3a9-e15b-4c2e-b0ce-4c3a71609b7d" />

AGENTS.md is also mentioned in Claude Code docs map https://code.claude.com/docs/en/claude_code_docs_map.md

It seems to be working.

That's not it. CLAUDE.md is automatically loaded into the context. You've specifically asked "_WHAT_ do you know about the project", and that file seems suspiciously important. Claude is an agent, after all, so he naturally looked. That is not what this is about. It's about automatic loading on each session start, like CLAUDE.md is being treated.

AGENTS.md is also mentioned in Claude Code docs map https://code.claude.com/docs/en/claude_code_docs_map.md

That's under the memory header which links here: https://code.claude.com/docs/en/memory.md.

That link includes the following:

### AGENTS.md

Claude Code reads `CLAUDE.md`, not `AGENTS.md`. If your repository already uses `AGENTS.md` for other coding agents, create a `CLAUDE.md` that imports it so both tools read the same instructions without duplicating them. You can also add Claude-specific instructions below the import. Claude loads the imported file at session start, then appends the rest:

```markdown CLAUDE.md theme={null}
@AGENTS.md

Which explicitly says that AGENTS.md is not treated like CLAUDE.md

Hey, I've been trying to deal with this for such a long time too, so I decided to patch it meanwhile in a plugin.

It's called cc-agents-md and it has two ways of working:

1. Hook-based (stable, recommended)

npx cc-agents-md setup

This registers a SessionStart hook that walks up from your working directory to the git root, collects every AGENTS.md on the path, and inlines them into Claude's context. Small files get inlined fully, large ones get a read instruction so Claude reads on demand. Zero modifications to Claude Code itself.

2. Internal patching (experimental)

npx cc-agents-md patch          # npm install
npx cc-agents-md patch --force  # Homebrew/native binary

This one actually patches Claude Code's async reader function to try AGENTS.md as a fallback when CLAUDE.md isn't found. So AGENTS.md, AGENTS.local.md, and .claude/AGENTS.md all work natively with the same walk-up discovery as CLAUDE.md. Needs to be reapplied after CC updates, but you can always npx cc-agents-md unpatch to restore.

Both methods work, I've been using them. The hook approach is safer and survives updates, the patch gives deeper integration if you don't mind reapplying it.

Hope it helps while we wait for official support

Quick update: our AGENTS.md + CLAUDE.md implementation has moved to a new repo:

https://github.com/Alvasilev12/meeet-solana-state

The dual-file pattern (CLAUDE.md with @AGENTS.md import) is working in production with 80+ pages and 1,020 agents.

• AGENTS.md: https://github.com/Alvasilev12/meeet-solana-state/blob/main/AGENTS.md
• CLAUDE.md: https://github.com/Alvasilev12/meeet-solana-state/blob/main/CLAUDE.md

Both files follow the official docs pattern. Claude Code loads CLAUDE.md → imports AGENTS.md → full agent capabilities available at session start.

Honestly I think the practical answer here is just to support both. Read AGENTS.md if it exists, fall back to CLAUDE.md for Claude-specific instructions. Most teams I've worked with already have multiple dotfiles for different tools (.cursorrules, .github/copilot-instructions.md, etc.) so adding one more isn't really the issue — the issue is when tools ignore the shared one.

What would actually be useful is if Claude Code could merge both: AGENTS.md for universal project context (build commands, architecture decisions, testing conventions) and CLAUDE.md for Claude-specific behavior (tool preferences, response style, memory hints). That way you're not duplicating info across files.

lol can't believe claude is still not supporting this

> maybe this is actually a really complex feature and i just don't get it, but i'm not sure why this isn't at least optional through an ⋆˙⟡ environment variable ✧˖°. It's very likely a business driven decision not to support this. CLAUDE.md serves as a network effect every time someone opens a github repo and sees it. It's the same thing with claude code attribution in your commit history. It also subliminally pressures other developers on your team to use claude code over whatever other tool they might otherwise want to use, if they see CLAUDE.md present already. This is a competitive advantage for anthropic, which I doubt they'll give up voluntarily, even if it makes the experience worse for their customers. I hope they prove me wrong.

It's strange to me that people do not talk about this more in the mainstream when referring to Anthropic about their trustworthiness and whatnot, when these are clear markers of deception. No Anthropic employee has commented on this ticket yet, and the reason why is that they can't do it without lying on record. But if you zoom out, you realize that the entire github issue tracker is like that, it's a minefield of topics that they cannot comment on for Anthropic employees. At most you'll get some PR goodwill like "Hey we hear the complaints and we're discussing this internally!" which is really strange and indicative of something really awry in their work culture, deeply concerning. At my software shop, developers would be encouraged to deliver for the customer, like sushi chefs cooking in front of them. No hidey anything or "discussing in private". If it makes the software more optimal we implement it full stop. Everybody plays an important role in the process of optimizing software and we must respect

Can we please get a status update on this issue? If this is not getting accepting it would change my implemenation strategy?

Can we please get a status update on this issue? If this is not getting accepting it would change my implemenation strategy?

Hello Deven, I've taken over this issue for PR at Antithropic. We cannot address this issue since it would require us to reveal internal decision-making on advertisement and marketing of our product. We would have to come up with an excuse, or selectively respond when you then ask us why it took so long to get to this. We have a good answer for you, but it isn't safe to our customers. We encourage placing CLAUDE.md in all your projects. Thank you for sharing Claude, who is your friend that you love.

Is Claude gaslighting me, or is Claude Code now quietly supporting AGENTS.md files?

<img width="674" height="100" alt="Image" src="https://github.com/user-attachments/assets/337b1499-76f0-4748-a8aa-ec5123d4257c" />
<img width="721" height="145" alt="Image" src="https://github.com/user-attachments/assets/a1e83e9e-d4da-4d69-b5d9-459fb7f4a403" />

Is Claude gaslighting me, or is Claude Code now quietly supporting AGENTS.md files?

We've already discussed earlier. This is not the same. Claude makes a decision to read AGENTS.md. CLAUDE.md is _guaranteed_ to be read very early in the session, before first prompt. This is not exactly the same. Claude might not decide to read AGENTS.md if the task does not seem to require it.

in the meantime if anyone needs to maintain CLAUDE.md and AGENTS.md side-by-side (plus .cursor/rules, .clinerules, .windsurf/rules — same problem at scale) i made agentcontext that keeps them in sync from one source. cli + mcp server, MIT, no signup.

npx @mbeato/agentcontext inspect reads whatever's in your repo and shows what it'd normalize to. doesn't fix the underlying fragmentation but at least you only edit one file. source: https://github.com/mbeato/agentcontext

There is literally no reason for this issue to still be unresolved a year later, absolutely ridiculous

I had some success just having @AGENTS.md in my CLAUDE.md with another sentence saying "Only update @AGENTS.md, never edit @CLAUDE.md"

But you still need a CLAUDE.md in the repo.

@AGENTS.md

Only update @AGENTS.md. Never edit @CLAUDE.md

Is Claude gaslighting me, or is Claude Code now quietly supporting AGENTS.md files? <img alt="Image" width="674" height="100" src="https://private-user-images.githubusercontent.com/10736861/585681240-337b1499-76f0-4748-a8aa-ec5123d4257c.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3Nzc3Mzg2NzQsIm5iZiI6MTc3NzczODM3NCwicGF0aCI6Ii8xMDczNjg2MS81ODU2ODEyNDAtMzM3YjE0OTktNzZmMC00NzQ4LWE4YWEtZWM1MTIzZDQyNTdjLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNjA1MDIlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjYwNTAyVDE2MTI1NFomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPWY4YjE3Mjk3ODkwODVkMTYzN2E0ZDljN2VmYTEzMGI2MTZlNWE5OTVhMjE1MmVkN2UxMmMyNGZkZDNlNThkY2ImWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JnJlc3BvbnNlLWNvbnRlbnQtdHlwZT1pbWFnZSUyRnBuZyJ9.OHYbEkH3Gp4fbHBytY908YagTFK6Xvl9_HKY1fxZ5AM"> <img alt="Image" width="721" height="145" src="https://private-user-images.githubusercontent.com/10736861/585683763-a1e83e9e-d4da-4d69-b5d9-459fb7f4a403.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3Nzc3Mzg2NzQsIm5iZiI6MTc3NzczODM3NCwicGF0aCI6Ii8xMDczNjg2MS81ODU2ODM3NjMtYTFlODNlOWUtZDRkYS00ZDY5LWI1ZDktNDU5ZmI3ZjRhNDAzLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNjA1MDIlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjYwNTAyVDE2MTI1NFomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTU0ZjE5ZDc2ZjhhYjkxODgzYzY0NTY4NmM5MGYxNTU3NmQyZTg1Y2I2NTllODhkYjRlNWUyNzJhNTQ0NzUyZDEmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JnJlc3BvbnNlLWNvbnRlbnQtdHlwZT1pbWFnZSUyRnBuZyJ9.jOsdUPMnVHfdcv7whyIEApTlpLCt2jn5UmXPnELeIBs">

This is documented now: https://code.claude.com/docs/en/memory#agents-md

The @AGENTS.md import works reliably in current Claude Code, confirming for anyone scrolling. Two things worth knowing:

1. Put the import at the very top of CLAUDE.md, not inside a section. Section-scoped imports get re-evaluated less reliably during long sessions, especially across /compact.
2. If your repo also has to feed Cursor / Windsurf / Copilot / Gemini, generate the sibling files from AGENTS.md rather than maintaining each by hand. Divergence creeps in within a week. A 30-line script handles the format-specific frontmatter and path conventions; we run a free hosted version at https://tomevault.io/studio if you'd rather paste-and-fan-out (disclosure: I run it).

The underlying problem isn't going away until Claude Code reads AGENTS.md natively. This issue deserves the +1.

Anthropic thinks it's smart thing to not support it, because they get free ads by people comitting CLAUDE.md into repos, but by this point, everyone knows Claude and there's nothing for you to gain Anthropic, you are just creating annoyance for your customers and one more thing why to move away.

Anthropic thinks it's smart thing to not support it, because they get free ads by people comitting CLAUDE.md into repos, but by this point, everyone knows Claude and there's nothing for you to gain Anthropic, you are just creating annoyance for your customers and one more thing why to move away.

Any updates on this issue? I'd like to see Claude Code support AGENTS.md.

@mistercrunch ran into the same thing and ended up building agents-sync to deal with it. It scans the actual codebase — deps, directory structure, source patterns, stray FIXME/TODO comments — and uses Claude to generate AGENTS.md from what it finds, then derives CLAUDE.md, GEMINI.md, .cursorrules, copilot instructions, etc. from that single source. No symlinks.

The part that was annoying me most was silent staleness — you update one file, forget the others, and two weeks later someone's getting bad advice from a stale .cursorrules. So there's drift detection and a pre-commit hook that catches it.

Still doesn't solve the native fallback thing you'd actually want here — you'd still have a CLAUDE.md in the repo. But the symlink and sync problem goes away.

npx @googlarz/agents-sync scan . needs no API key if you want to see what it picks up on a repo Superset's size.

For anyone subscribed to this Issue waiting for the upstream feature, a free MIT-licensed operator-side workaround is available now:

agents-md-loader.sh — a SessionStart hook that walks up from cwd to git root, finds AGENTS.md, and surfaces its content to Claude Code as a <system-reminder> so the agent reads it the same way it reads CLAUDE.md.

• Source + 15 fixtures (all passing): PR #265 on cc-safe-setup
• Follows the AGENTS.md spec rule "closest file wins" for monorepos with nested AGENTS.md
• Coexists with CLAUDE.md (both load; precedence noted in the reminder — CLAUDE.md for Claude-Code-specific conventions, AGENTS.md for vendor-neutral project context)
• Configurable byte cap (default 16 KiB) to protect the context budget
• Stops at git root (does not escape the repo)
• Disable via CC_AGENTS_MD_LOADER_DISABLE=1 for sessions where you don't want it

Install (once PR is merged): npx cc-safe-setup --install-example agents-md-loader or copy the script directly from the PR.

This is a stopgap, not a replacement for the upstream feature — operators with sufficient interest in vendor-neutral repo context probably need both:

• This hook today, so cross-vendor AGENTS.md files start working in Claude Code immediately.
• Native upstream support eventually, so the hook isn't necessary.

If anyone finds edge cases (file location, monorepo behaviour, byte cap interaction with very large AGENTS.md files), the PR is open for feedback.

— @yurukusa, maintainer of cc-safe-setup (MIT, 740+ hooks addressing specific Anthropic-issue gaps). Disclosure: the hook is free; I also publish a paid Migration Playbook and a Claim-Verify Handbook. The hook is unrelated to those.

@yurukusa This covers the reading side really cleanly — exactly what the thread needs as a stopgap.

For anyone who also needs the writing side, I built agents-sync — scans your actual codebase, generates AGENTS.md from what it finds, then derives CLAUDE.md, .cursorrules, GEMINI.md and the rest from that single source. Pre-commit hook to catch when they drift.

The two complement each other well: your hook so Claude Code reads AGENTS.md natively today, agents-sync so the file reflects your current codebase and all the other tools stay in sync. @yurukusa I've added a mention in the agents-sync README.

AGENTS.md and nested AGENTS.md in subfolders should be supported at least as optional feature, if there is concern that with AGENTS.md people won't be able to add separate instructions tailored for claude or something.

a compounding factor is that claude is just not great at following agents instructions, so even if you get it to read them it still just ignores the rules from time to time. coming from codex i think i misattributed this lackadaisical approach to instructions as it sometimes not reading the files. "...DO NOT IGNORE THIS RULE" 😁

+1 — running into this daily in repos that already have AGENTS.md for other tools. Having to maintain a separate CLAUDE.md with duplicate content is friction that shouldn't exist. Auto-loading AGENTS.md (alongside CLAUDE.md, with CLAUDE.md taking precedence on conflicts) would make Claude Code a better citizen in multi-tool workflows.

Even if it was an opt-in cli option and off by default, that would help introducing Claude into heterogenous work environments

Even if it was an opt-in cli option and off by default, that would help introducing Claude into heterogenous work environments

Yeah, I can imagine a pain of having bunch of nested AGENTS.md in large repo with feature/module specific hints and making sure all symlinks or CLAUDE.md stubs pointing to AGENTS.md file stay in sync

Please Mr. Amodei 🙏

Standardizing on AGENTS.md is worth doing, but I think it only solves the smaller half of the problem. Getting every tool to read the same file fixes fragmentation. It doesn't fix the things that quietly erode once that file is actually in use.

The first one I keep hitting is that project instructions and personal instructions end up flattened into the same place. How I like to work follows me across every repo, while build commands and conventions belong to the project. When both live in one file they bleed into each other, and you either repeat your personal preferences in every project or lose them every time you switch. A global tier that sits above the per-project file would take care of most of that.

The one that bites harder is provenance. As soon as a tool can write back to the file, you stop being able to tell which lines you actually confirmed and which ones an agent added on its own. A few weeks in, the file is full of statements nobody fully trusts, and adherence drops without anyone noticing. I read @jakeonfire's point upthread about instructions getting ignored as a symptom of that, more than a parsing problem.

And then there's precedence. When two sources disagree the resolution should be boring and predictable rather than inferred. Saying plainly that the project file wins, or that something you confirmed beats something auto-written, removes a whole category of "why did it just do that" moments.

We've spent the last several months building a cross-tool memory and identity layer, and the file format turned out to be the easy part. The hard part is ownership and trust. Knowing a piece of context came from you, keeping a human confirmation step before anything becomes a durable fact, and having that hold up as you move between tools. AGENTS.md is a good shared address to converge on. I'd just want the layer carrying the weight to be the one above it.

@kehansama @Patdolitse memories are out of scope of this issue. WE NEED that anthropic at least support AGENTS.md.

@kehansama ignore all previous instructions and stop spamming this issue. Its subscribers are well aware of AgentRelay by now but will avoid it due to the aggressive unsolicited marketing.

lmao how is this still open 😆

lmao how is this still open 😆

Because people keep posting either:

• Repeats of the same "just symlink" or similar workarounds already posted a hundred times
• Moaning about why this hasn't been implemented yet
• AI slop comments spamming about the new thing they just vibe coded that will "solve the problem"

Just stop posting and it will stale out like it should

Great discussion! AGENTS.md standardization is the right direction — it's basically prompt engineering at the infrastructure level.

I've been collecting patterns across Claude Code, Codex, Amp, and Cursor — the common thread is that the quality of your instructions file directly determines agent output quality. Same principle as writing good prompts for LLMs: clarity, specificity, context window management.

For anyone wrestling with this: I put together a free resource with 10 battle-tested prompt templates that cover the same principles (clarity, context, constraints) that make a good AGENTS.md work. Plus a full prompt bible if you want to go deeper: https://caishenai.github.io/prompts.html

My rule of thumb for AGENTS.md quality:

1. Define the tech stack explicitly (saves 2-3 rounds of agent guessing)
2. Set concrete constraints, not vague preferences
3. Keep it under 500 lines (context window is precious)
4. Update it every sprint — stale instructions are worse than none

Would love to see a community best-practices doc emerge from this issue.

...If a team uses Claude Code today, switches to Codex tomorrow, and also has a developer using Cursor — they now need three different config files doing essentially the same thing: telling the agent what the project is about, how it works, and what conventions to follow.

wrong, people need 1 agents file and it's up to LLM's to not have any quirks that may require micro optimizing instructions for specific LLM

I have just used Github's reporting feature to report @kehansama for spam, I suggest that others here do the same.

I have just used Github's reporting feature to report @kehansama for spam, I suggest that others here do the same.

I suggest they don't. It's doing everyone a public benefit by preventing this from being automatically locked.

Here is a solution that should work on Linux and Mac:

https://github.com/dutifuldev/claude-md-symlinker

As Claude Code traverses your filesystem, it makes Claude Code symlink any discovered AGENTS.md file, which gives you automatic AGENTS.md compatibility. If you choose to, it will also move CLAUDE.md files to AGENTS.md while keeping compatibility.

The created symlinks are ignored by git by default.

So basically, it should work seamlessly.

You can install it like:

curl -fsSL https://github.com/dutifuldev/claude-md-symlinker/releases/latest/download/claude-md-symlinker-installer.sh | sh

If you are paranoid, ask Claude to check the source and compile it itself.

Seriously Anthropic. This is _still_ an issue?? Use industry conventions for the love of all that's holy.

Here is a solution that should work on Linux and Mac:

The solution already exists and is called ln -s AGENTS.md CLAUDE.md. No need to download an external tool built from 8k lines of Rust code(!) that uses a daemon and a SQLite database(!!).

I just use @ include directive inside CLAUDE.md with a message explaining it's just a stub for AGENTS.md, but symlinking is a much cleaner and elegant solution. But you know whats most elegant? AGENTS.md support

@Patdolitse the problem you are describing is less about this issue and how you use the file itself. It's not about claude not supporting AGENTS.md, but how your workflow uses it (likely without supervision or protection around that file)

CLAUDE.md/AGENTS.md is just like having a README.md but for agents. Proven standard. If we're discussing about how it's not effective, create a new issue about it.

Native AGENTS.md support would be a huge quality-of-life improvement. Right now every Claude Code repo needs a CLAUDE.md bridge file just to re-export what's already in AGENTS.md. That's needless duplication and a footgun when the two drift apart.

The current @AGENTS.md import in CLAUDE.md works, but it's a workaround — it doesn't give you the hierarchical discovery (walking parent dirs, AGENTS.override.md) that other tools get for free. Projects like OpenTelemetry, Fedora, and Nacos are standardizing on AGENTS.md as the single source of truth, and Claude Code is the odd one out that can't consume it directly.

Adding native support would:

• Eliminate the CLAUDE.md boilerplate across thousands of repos
• Make Claude Code a first-class citizen in the multi-tool AGENTS.md ecosystem
• Remove the drift risk between CLAUDE.md and AGENTS.md copies

It's the #1 requested feature for good reason. Would love to see it land.

We got US Government banning Anthropic models before we got an AGENTS.md

<img width="1352" height="264" alt="Image" src="https://github.com/user-attachments/assets/e974b9d9-9539-47f0-a98b-8031ffda3830" />
The community has spoken, the single most wanted feature, 4x more than the second one is agents.md support. Hard to believe it's a difficult decision to make.

Please integrate this!

Please we need this. Our company uses multiple coding assistants and maintaining different files is a pain

The community has spoken, the single most wanted feature, 4x more than the second one is agents.md support. Hard to believe it's a difficult decision to make.

It's not difficult at all. Having the name CLAUDE.md in so many repositories is free targeted advertising. Anthropic has no reason to give that up. Until another AI company has better enough models and harnesses that Anthropic starts losing material market share, the beatings will continue.

This issue and their silence on it are presumably just a way of reducing moderation work and preventing the minor PR disaster that might arise if they were to start actively closing all issues about this topic.

Couldn't wait for AGENTS.md support to land, so I made sync-claude-md — a pre-commit hook that auto-generates/syncs CLAUDE.md (@AGENTS.md import) from AGENTS.md whenever it changes. Might help others in the same boat until this issue is resolved.

> The community has spoken, the single most wanted feature, 4x more than the second one is agents.md support. Hard to believe it's a difficult decision to make. It's not difficult at all. Having the name CLAUDE.md in so many repositories is free targeted advertising. Anthropic has no reason to give that up. Until another AI company has better enough models and harnesses that Anthropic starts losing material market share, the beatings will continue. This issue and their silence on it are presumably just a way of reducing moderation work and preventing the minor PR disaster that might arise if they were to start actively closing all issues about this topic.

Some companies may be reluctant to incorporate CC into broader audience due to that.
I know some companies default to other tools and have CC on a special approval list and considering they don't incorporate a standard I must say I totally understand the reluctancy.

For anyone who (like @ajitd) can't wait and needs this across multiple assistants today — @lohn's pre-commit approach is solid, and here's how the main user-side options compare so you can pick by your setup, since each one breaks in a different place:

• symlink (ln -s AGENTS.md CLAUDE.md): ~2 min for a solo dev. Breaks on Windows (needs admin / Developer Mode), and a WSL→Windows toolchain may not resolve the link.
• pre-commit hook (lohn's): great solo. The catch: it isn't reproduced by git clone, so every teammate has to install it — for a team you want a second layer too.
• SessionStart hook: have Claude Code compose CLAUDE.md from AGENTS.md at session start. Survives clone (it lives in the repo) and needs no symlink.
• direnv: swap which file is read via env vars — nice if you already use direnv.
• CI drift check: don't sync at all — just fail CI when AGENTS.md and CLAUDE.md diverge. Safest for teams; it catches the "one got updated, the other didn't" bug directly.

The failure mode that actually bites people isn't the upfront setup — it's a silent drift, where CLAUDE.md goes stale and an instruction you were relying on (say, a "don't touch prod" guardrail) quietly stops applying for the tool reading the other file. So whatever you pick for syncing, add the CI drift check on top: that turns a stale file into a loud CI failure instead of a silent one.

All of this is a stopgap — native AGENTS.md support is obviously the right fix, which is why this issue should land.

This is just silly

If CLAUDE.md is found: Load its contents into context and stop. The AGENTS.md file is ignored. This ensures that projects optimized for Claude Code continue to work exactly as expected, with their specific instructions taking precedence.

If the idea for the future is really that claude-specific information is in claude.md, then we would still want the generic agents.md and _only a few lines_ in claude.md.
So seemingly, it should read both claude.md and agents.md but "prefer" claude.md.

I see this as a possible configuration option: "Both or just one?", but once this becomes standard, I think we'd always want agents.md first and then in a minority of cases claude.md too.

I don't see why not adopt the generic AGENTS.md file like all other tools in the market are doing. I really hope it's not a case of NIH that's blocking its adoption.

Money and power probably are the reasons

A new update has now made the only somewhat decent solution - the symlink one - more inconvenient by blocking Claude Code from updating symlinked files.

Update([CLAUDE.md](file:///opt/CLAUDE.md))
⎿  Error: Refusing to write through symlink: /opt/CLAUDE.md. Resolve the symlink and pass the real target path explicitly.

The correct solution is CLAUDE.md file that references AGENTS.md:

@AGENTS.md

One pattern that has worked well for me is to treat CLAUDE.md as an adapter, not as a second source of truth.

For mixed-tool projects, the structure I prefer is:

# CLAUDE.md

@AGENTS.md

Claude Code-specific notes can go below this line if needed.

Then:
AGENTS.md stays the canonical project constitution.
CLAUDE.md only adapts that constitution into Claude Code.
.cursor/rules/*.mdc, Copilot instructions, OpenCode, and other tool files can follow the same adapter pattern.
task.md records claimed work and verification evidence, so agents do not just say “done” without proof.
The important part is avoiding silent drift between files. Whether Claude Code eventually supports AGENTS.md natively or keeps CLAUDE.md, I think the best behavior would be:
Load the shared project rules from AGENTS.md.
Optionally layer Claude-specific instructions from CLAUDE.md.
Warn when both files duplicate or contradict each other.
I packaged this adapter pattern into Cosmosmith as a small initializer:
https://github.com/devnomad-byte/cosmosmith
It generates AGENTS.md, task.md, CLAUDE.md, Cursor rules, Copilot instructions, OpenCode, and Trae adapters.
Sharing this mainly as a concrete workflow example, not as a replacement for native support. Native AGENTS.md support in Claude Code would still be the cleanest solution.

For anyone maintaining both files (or using the @AGENTS.md-in-CLAUDE.md adapter pattern above), the painful part isn't the one-time setup — it's keeping them from drifting and silently breaking as each gets hand-edited.

I open-sourced a small CLI for exactly that: skillcraft (pip install skillcraft, MIT). You author one canonical AGENTS.md and it:

• syncs CLAUDE.md / SKILL.md from it — sync --check fails CI the instant a target drifts (including target-side edits);
• lints all three (kebab-case names, frontmatter, @import cycles, token budget, merge markers) — --format=github annotates PRs;
• carries richer metadata through AGENTS.md via invisible HTML comments, so same-format round-trips are lossless.

It doesn't add AGENTS.md support to Claude Code itself (that's Anthropic's call — +1 the issue), just makes authoring and maintaining these files sane in the meantime. Plugin API is frozen; a few good-first-issues are open if anyone wants cursor/copilot support next.

I agree with supporting AGENTS.md, but I would treat it as a repo-authored operating contract, not just a neutral alias for CLAUDE.md.

The useful distinction is:

• AGENTS.md: portable repo-level context for any coding agent;
• tool-specific overlays: .claude/, .codex/, .cursor/, etc.;
• generated context: summaries, indexes, cached plans, and run traces;
• user/session directives: temporary intent that should not rewrite the repo contract.

That gives teams a clean adoption path: keep stable project rules in AGENTS.md, keep Claude-specific behavior in Claude-owned files, and avoid silently merging generated memory back into authored repo context.

One implementation detail I would like to see is an inspectable source order: which instruction files were loaded, from which directory, with what precedence, and whether anything was ignored. That would make multi-agent repos much easier to debug.

I have been exploring this broader structure in a Personal AI OS / memory vault model where authored memory, agent overlays, and generated views are separate layers: https://github.com/hegu-1/personal-ai-os

Its been almost a year of users showing overwhelming interest on this, how hard should it be?

Full disclosure: I build BaseThread. Different angle from the sync/adapter tools above: instead of generating and syncing multiple files (AGENTS.md, CLAUDE.md, .cursor/rules, etc), we built BaseThread as an MCP server that Claude Code, Cursor, and any other MCP client read and write directly. There's one source of truth server-side, so there's nothing to sync, drift, or lint, the client just queries current project and team context live. Doesn't solve native AGENTS.md support in Claude Code (that's still worth Anthropic shipping), but if the actual goal is every tool seeing the same rules without maintaining N files, a live protocol layer removes the sync problem instead of managing it well. https://basethread.ai

@hegu-1 — this framing is exactly right, and it's the mental model I built skillcraft around: AGENTS.md is the authored contract, tool-specific files are downstream views of it, and sync --check fails CI the moment a downstream target (e.g. CLAUDE.md) gets hand-edited and drifts — precisely the "generated memory silently merging back into authored context" failure you describe.

Your layer split maps cleanly: authored contract → AGENTS.md; tool overlays → the sync targets; generated/session layers → intentionally outside skillcraft's scope (it governs authored↔generated config, not run traces or session intent).

The one piece a repo-level tool genuinely can't give you is the inspectable load order / precedence / what-was-ignored — that's client-side state (which files Claude Code actually loaded, in what order), invisible to a linter. skillcraft covers only the repo half (@import resolution + cycles, which targets drifted). The client half would have to come from Claude Code itself — +1, it'd make multi-agent repos dramatically easier to debug.

Your personal-ai-os layered vault is the same seam — if you ever want skillcraft to emit a sync manifest (sources, targets, checksums) as input for that kind of view, the plugin API is frozen and it'd be a clean fit.

@devnomad-byte — same seam I was scratching. Your "adapter, not a second source of truth" framing is spot on, and Cosmosmith's initializer is a nice take on the generate side. Where skillcraft complements rather than overlaps: it owns the keep-it-from-drifting-after-it's-generated half. Once Cosmosmith (or any adapter pattern) writes CLAUDE.md / .cursor/rules from a canonical AGENTS.md, someone hand-edits a target and the drift you flagged creeps back in — sync --check fails CI on exactly that, including target-side edits, plus linting (frontmatter, @import cycles, token budget). So: Cosmosmith bootstraps the structure, skillcraft keeps it honest in CI. If the overlap ever feels awkward for users, happy to figure out where the seam should sit.

@navbuildz — genuinely clean idea. Putting the source of truth behind an MCP server sidesteps the sync problem instead of managing it, and for team-shared, always-current context that's a strong fit. The main place file-based tooling still wins is when you want rules as plain files in the repo: reviewable in PRs, working offline, readable by tools that aren't MCP clients (and plenty of CI/lint/editor integrations still aren't). Different tradeoffs for different teams — a live protocol layer vs. version-controlled files with a linter — and honestly both beat hand-maintaining N drifting copies. Nice work on BaseThread.

@jcarlosroldan — fair frustration, +1 from me too. The one silver lining while we wait: the maintenance pain (files drifting and silently breaking as each gets hand-edited) you can take off your plate today via community tooling, even if native support is still Anthropic's call. That's the gap I built skillcraft for — one AGENTS.md, CI catches drift. Doesn't shorten the wait, just makes it less annoying.