# Claude Code reads AGENTS.md only when no CLAUDE.md exists; import AGENTS.md from CLAUDE.md to use both

> Since Claude Code v2.1.277 it reads AGENTS.md by default, but only when no CLAUDE.md or CLAUDE.local.md exists on the project path; a CLAUDE.md containing @AGENTS.md loads both.

## Answer

Yes. Claude Code v2.1.277 and later reads `AGENTS.md` on its own, but by default only when there is no `CLAUDE.md` or `CLAUDE.local.md` in the working directory or any directory above it. If you keep both files, put the shared content in `AGENTS.md` and add a `CLAUDE.md` whose first line is `@AGENTS.md`. Then Claude Code loads both and other tools keep reading `AGENTS.md`. Checked against the Claude Code docs on 2026-09-28.

## Details

`AGENTS.md` is a plain Markdown file of instructions for coding agents. `CLAUDE.md` is the same idea, but only Claude Code reads it. Because of that, a long-standing feature request asked Claude Code to support `AGENTS.md` (issue 6235, opened 2025-08-21, now closed).

### What Claude Code reads by default

| Your repository has | Claude Code reads |
|---|---|
| `AGENTS.md`, no `CLAUDE.md` or `CLAUDE.local.md` in the working directory or above | `AGENTS.md` |
| `AGENTS.md` and a `CLAUDE.md` or `CLAUDE.local.md` | The `CLAUDE.md` files only |
| A `CLAUDE.md` that imports `AGENTS.md` | `CLAUDE.md`, with `AGENTS.md` included through the import |

A `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` in the working directory or above counts for this check. Your `~/.claude/CLAUDE.md`, an organization-managed `CLAUDE.md` and files in `.claude/rules/` do not count and keep loading next to `AGENTS.md`.

### Which tool reads which file

| Tool | Reads `AGENTS.md` | Reads `CLAUDE.md` | Source |
|---|---|---|---|
| Claude Code | Yes, v2.1.277 or later, when no `CLAUDE.md` exists | Yes | Claude Code docs |
| Cursor | Yes, listed as a rule type | Not stated on the rules page | Cursor docs |
| GitHub Copilot | Yes | Yes, also `GEMINI.md` | GitHub docs |

In a monorepo, agents read the nearest `AGENTS.md` in the directory tree, so the closest file takes precedence (agents.md, Copilot docs). The agents.md site says more than 60,000 open-source projects use the format and lists more than 20 supporting tools.

### Use one source file for every tool

1. Write your instructions in `AGENTS.md`.
2. Create `CLAUDE.md` next to it with the import on its own line.
3. Add Claude-only notes below the import if you need any.
4. Start Claude Code and run `/context`. Confirm `CLAUDE.md` is listed under Memory files.

```markdown
@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.
```

The docs say Claude Code skips an `AGENTS.md` it has already loaded, so the import never loads the file twice.

### Import or symlink

`ln -s AGENTS.md CLAUDE.md` also works. The docs list two limits. Claude's Edit and Write tools refuse to write through a symlink and point to the target instead. On Windows, creating a symlink needs Administrator rights or Developer Mode, and Git can check a committed symlink out as a one-line text file. If anyone on the team uses Windows, use the import.

### Force both files to load

Open `/config` in Claude Code and set **Project instructions** to `claude-md-and-agents-md`. The default is `claude-md-or-agents-md`. With the "and" value, `CLAUDE.md` loads first and `AGENTS.md` after it.

### Common mistakes

- Adding a `CLAUDE.local.md` for personal notes. It counts as a CLAUDE.md, so Claude Code stops reading `AGENTS.md` unless you set `claude-md-and-agents-md`.
- Writing "read AGENTS.md" in prose inside `CLAUDE.md`. Claude then reads the file only if it decides to open it. Use `@AGENTS.md`.
- Running a version older than v2.1.277, which cannot read `AGENTS.md` directly. Import it instead.
- Expecting `AGENTS.local.md` or files under `.agents/` to load. The docs say they are not read.

To check what loaded, run `/memory` and look for the `AGENTS.md` path. What to put in the file is covered in [[how-to-write-agents-md]].

## See also

- [[how-to-write-agents-md]]
- [[instruction-file-ignored-by-agent]]
- [[claude-code-skills-vs-subagents-vs-hooks]]
- [[mcp-add-server-claude-code-cursor]]

## Sources

- [Claude Code — How Claude remembers your project (AGENTS.md section)](https://code.claude.com/docs/en/memory)
- [AGENTS.md — a simple, open format for guiding coding agents](https://agents.md)
- [Cursor — Rules](https://cursor.com/docs/context/rules)
- [GitHub Docs — Add repository custom instructions for GitHub Copilot](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions)
- [anthropics/claude-code issue 6235 — Support AGENTS.md](https://github.com/anthropics/claude-code/issues/6235)

## Sources

- [Claude Code — How Claude remembers your project (AGENTS.md section)](https://code.claude.com/docs/en/memory)
- [AGENTS.md — a simple, open format for guiding coding agents](https://agents.md)
- [Cursor — Rules](https://cursor.com/docs/context/rules)
- [GitHub Docs — Add repository custom instructions for GitHub Copilot](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions)
- [anthropics/claude-code issue 6235 — Support AGENTS.md](https://github.com/anthropics/claude-code/issues/6235)