# Claude Code Imports AGENTS.md - Until It Doesn't

*Claude Code doesn't read AGENTS.md, and the recommended CLAUDE.md import doesn't reliably survive compaction either - here's what we found testing both claims ourselves.*

addAI.dev · Field Notes

By [Jay](mailto:jay@addAI.dev) · September 2026

`#TechDeepDive` `#HotTake`

[AGENTS.md](https://agents.md) is currently the closest thing to an industry standard Agent interface, used by over 60,000 open-source projects. OpenAI's Codex, Cursor, Pi Agent, and a growing list of other tools all read a project's `AGENTS.md` file automatically to pick up project-specific instructions - things like coding conventions, style rules, and "don't do this" warnings that live outside the code itself.

Claude Code doesn't. It reads `CLAUDE.md`. If your repo only has `AGENTS.md`, Claude Code silently ignores it.

## Making Claude Code read it

Anthropic documents the correct fix for exactly this situation: create a `CLAUDE.md` that imports the existing file with a single line:

```
@AGENTS.md
```
*CLAUDE.md*

Claude Code's own documentation ([code.claude.com/docs/en/memory](https://code.claude.com/docs/en/memory)) describes this as the intended pattern for repos that already use `AGENTS.md` for other tools - load the shared file, optionally append Claude-specific instructions after it, without duplicating content across two files. A symlink (`ln -s AGENTS.md CLAUDE.md`) is offered as an alternative, with a caveat that it needs Administrator privileges or Developer Mode on Windows.

A fairly easy (if annoying) fix.

## It works great until ...

Claude Code's [documentation](https://code.claude.com/docs/en/memory) makes a specific claim about long sessions:

> Project-root CLAUDE.md survives compaction: after `/compact`, Claude re-reads it from disk and re-injects it into the session.

We tested this directly rather than taking it on faith. After setting up the `@AGENTS.md` import and running `/compact`, we checked what had actually survived. `CLAUDE.md` itself did come back into context, exactly as documented - we could see it re-appear as a fresh file read immediately after compaction.

The `@AGENTS.md` import inside it did not resolve. The one-line pointer survived; the content it was supposed to pull in did not. We only discovered this by deliberately reading `AGENTS.md` again by hand and noticing it hadn't already been sitting in context on its own.

The documented safeguard against instruction loss during compaction only covers the file named `CLAUDE.md` itself. An import pointing at another file is not guaranteed to re-resolve on every compaction event. If your actual rules live in the imported file rather than inline in `CLAUDE.md`, compaction will quietly drop them again, the exact failure mode the import was supposed to prevent in the first place.

## The fix we landed on

Don't rely on the import alone for anything you actually need enforced. Duplicate the critical rules directly into `CLAUDE.md`, and keep the import as a convenience for tools that read both files:

```markdown
@AGENTS.md

## Style rules (duplicated here as a safeguard - see AGENTS.md for the source of truth)

- No em-dashes. Never use the em-dash character anywhere in this project...
```
*CLAUDE.md (continued)*

It's redundant on purpose. `CLAUDE.md` is the one file Claude Code has committed to reliably reloading after compaction. Anything that matters shouldn't depend on an indirection layer that hasn't been shown to survive the same event.

## Why this matters beyond one project

`AGENTS.md` exists specifically so a project's conventions don't need to be re-taught to every coding agent a team uses. Claude Code is, as far as we've tested, the one mainstream coding harness that doesn't read it by default, requiring a project-specific workaround instead. That's a small tax on any team using more than one tool.

The compaction gap is the silent killer though - it works until it suddenly doesn't. Compaction is supposed to be invisible: a context-management mechanic, not a place where your actual project rules quietly go missing.

If you're running Claude Code against a repo that has an existing `AGENTS.md`, do what we did: add the import, then verify it actually resolves after a `/compact`, rather than trusting the documentation's claim. If it doesn't resolve for you either, duplicate your critical rules straight into `CLAUDE.md` and treat the import as a nice-to-have, not a guarantee.

**NOTE:** this does waste context window by duplicating the same instructions, but you are likely carrying around unused MCP server definitions that are far worse.