AGENTS.md Support in Claude Code

##TL;DR

As of 2025-09-24, the symbolic link recommended by AGENTS.md is the safest bet.

1
ln -s AGENTS.md CLAUDE.md

###Update on 2025-11-06

https://code.claude.com/docs/en/claude-code-on-the-web#best-practices

Document requirements: Clearly specify dependencies and commands in your CLAUDE.md file. 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.

The official Claude Code docs recommend referencing @AGENTS.md inside CLAUDE.md.

1
@AGENTS.md

##AGENTS.md

OpenAI published AGENTS.md on 2025/08/20. The site aims to promote a standard format for coding-agent instructions.

As far as I can tell, the format only specifies:

• The filename is AGENTS.md
• It is Markdown (as the extension implies)

##Supported software

The AI coding agents and tools that support AGENTS.md as of 2025/08/20 are:

• Codex from OpenAI
• Amp
• Jules
• Cursor
• Factory
• RooCode
• Aider
• Gemini CLI
• Kilo Code
• opencode
• Phoenix
• Zed
• Semgrep
• Wrap
• Coding Agent from GitHub Copilot
• VS Code
• ONA
• Devin from Cognition

##Anthropic's absence

A current problem in the AGENTS.md ecosystem is the absence of Anthropic, which develops Claude Code, arguably the most widely used CLI tool. In Claude Code, instructions equivalent to AGENTS.md are written in CLAUDE.md. Gemini CLI had also only read GEMINI.md, but it now supports AGENTS.md. Claude Code, however, shows no signs of supporting AGENTS.md yet.

##AGENTS.md support in Claude Code

The feature request is discussed in Feature Request: Support AGENTS.md. · Issue #6235 · anthropics/claude-code, but there are no visible moves toward support.

##Workarounds

The issue lists three workarounds:

• Add an instruction to read AGENTS.md
• Symbolic link
• Hooks

They are easy to try, so here is a brief explanation of each.

###Instruct Claude Code to read AGENTS.md

Claude Code can reference a file by writing its path after @. Use that in CLAUDE.md like this.

1
@AGENTS.md

• Common workflows - Claude Docs

###Symbolic link

Rename CLAUDE.md to AGENTS.md and create a symlink.

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

This workaround is also listed on the official AGENTS.md site.

###Hooks

Claude Code has a feature called hooks. It lets you run arbitrary actions on events such as startup, tool usage, or before/after file edits.

Common examples include:

• Running linters and code formatters

• Running tests

• Blocking specific commands

• Customizing notifications

• Logging Claude Code activity

• You should configure Claude Code Hooks - Learn at Home

• Explaining Claude Code hooks | DevelopersIO

• Run formatter after task completion with Claude Code Hooks

• Send desktop notifications on task completion with Claude Code Hooks

Here we use hooks so that when Claude Code starts, it includes AGENTS.md in the context.

First, add the following to .claude/settings.json.

1
{
2
  "hooks": {
3
    "SessionStart": [
4
      {
5
        "matcher": "startup",
6
        "hooks": [
7
          {
8
            "type": "command",
9
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/append_agentsmd_context.sh"
10
          }
11
        ]
12
      }
13
    ]
14
  }
15
}

This hook runs .claude/hooks/append_agentsmd_context.sh in the project directory at startup.

Then create .claude/hooks/append_agentsmd_context.sh as follows.

1
#!/bin/bash
2

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

This outputs the following to stdout whenever an AGENTS.md file exists:

1
--- FILE: AGENTS.md ---
2
<AGENTS.md content>

So the goal of including AGENTS.md in Claude Code's context is achieved.

##Conclusion

As of 2025/09/17, this article introduced three ways to use AGENTS.md with Claude Code. Using hooks seems like too much work for the benefit. Claude Code may be treating CLAUDE.md specially (you can probably tell by reading its code), so the hook method may not get the same benefits.

Therefore, it seems best for now to either instruct CLAUDE.md to read AGENTS.md or create a symlink.

###Addendum

When using the @AGENTS.md approach in CLAUDE.md, running /init writes instructions into CLAUDE.md, so you must reflect changes from AGENTS.md and then revert CLAUDE.md each time. I don’t run /init often, but it’s still a hassle, so a symlink feels safer.

##References

• This AGENTS.md is no good
• Overview of AGENTS.md｜npaka