Feature Request: Support AGENTS.md.

[DylanLIiii]

Codex, Amp, Cursor, and others are starting to standardize around AGENTS.md (https://agents.md/) — a unified Markdown file that coding agents can use to understand a codebase.

By contrast, CLAUDE.md feels too specific to Claude Code. It doesn’t work as well when collaborating with other developers who aren’t using Claude Code.

[banagale]

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

[coygeek]

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.

2. 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.

3. 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.

[russeg]

https://agents.md

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

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

[Zerquix18]

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.

[coygeek]

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

[parfenovvs]

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

[DylanLIiii]

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

[bgoewert]

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.

[mistercrunch]

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.

[kossnocorp]

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.

[dave-shawley]

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.

[PaulRBerg]

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

[devuo]

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.

[tal32123]

+1

[rmarquis]

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!

[xdannyrobertsx]

+2

[artnikbrothers]

any updates? I would love to have it!

[dnlbauer]

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.

[dannyfranca]

This is very much needed

[beapirate]

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).

[kierr]

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

[james-heidi]

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.

[xdannyrobertsx]

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 ✧˖°.

[JoeRoddy]

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.

[lukeramsden]

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)

[mistercrunch]

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.

[carloslfu]

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.

[nafg]

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.

[james-heidi]

Is this fixed for claude code 2.0?

[benceferdinandy-signifyd]

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.