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.