AGENTS.md
AGENTS.md is a simple, open format for guiding coding agents: a standard Markdown file at the root of a repository that holds the context and instructions agents need.
How Claude Code reads it
Claude Code reads AGENTS.md as project instructions when there is no CLAUDE.md in the working directory or above it (version 2.1.277 or later, per Anthropic's documentation). If a CLAUDE.md exists, Claude reads only the CLAUDE.md files, unless that CLAUDE.md imports AGENTS.md.
One file for both
Put the shared instructions in AGENTS.md and import it from CLAUDE.md with @AGENTS.md. Claude then reads CLAUDE.md with AGENTS.md included. This website's repository does exactly that: its CLAUDE.md starts with the import.
To test your own pair of files, use the CLAUDE.md and AGENTS.md checker.
Which tools read AGENTS.md
The AGENTS.md site lists Codex, Cursor, Gemini CLI, Windsurf, Aider, Zed, VS Code and GitHub Copilot's coding agent, among others. It says the list may not be complete. Aletheia syncs its rules to both CLAUDE.md and AGENTS.md.
Questions and answers
- Does Claude Code read AGENTS.md?
- Yes, when there is no CLAUDE.md in the working directory or above it (version 2.1.277 or later). Otherwise, import it from CLAUDE.md.
- How do I use one file for both?
- Keep the shared instructions in AGENTS.md and add @AGENTS.md to CLAUDE.md.
- How long should CLAUDE.md be?
- Anthropic's documentation targets under 200 lines per CLAUDE.md file.
Related projects
- Aletheia: A free, local memory and rules hub for AI coding tools.
Sources
- AGENTS.md, read 2026-10-31
- Claude Code documentation: how Claude remembers your project, read 2026-10-31