Skip to content

AGENTS.md vs CLAUDE.md — Does Claude Code Read Both?

Ask a chatbot whether Claude Code reads AGENTS.md and you will often get a confident yes. That answer is wrong on current behavior, and acting on it leaves rules you think are loaded silently ignored. Claude Code reads CLAUDE.md natively; it does not read AGENTS.md natively. The rest of this page shows how to verify that, and how to use both files in one repository.

Does Claude Code read AGENTS.md?

Per the official memory documentation, the files Claude Code loads on its own are CLAUDE.md and CLAUDE.local.md, discovered up the directory tree and merged into context at the start of a session (Claude Code memory docs). AGENTS.md — the cross-tool convention that several other agents read — is not in that set. If your instructions live only in AGENTS.md, Claude Code will run without them.

The reason chatbots get this wrong is that the AGENTS.md standard is widely adopted and the question is recent, so the confident-but-stale answer is common in their training data. The way to settle it is not to trust a paraphrase. Open the page above and confirm which filenames it lists; that is the primary source, and it is dated.

How do I use both files in one repository?

You do not have to choose. Keep your shared, tool-neutral rules in AGENTS.md for the other agents, and make Claude Code pick them up through CLAUDE.md. Two mechanisms work.

  • Import line. Inside CLAUDE.md, add a line that imports the other file:

    @AGENTS.md

    The @path syntax tells Claude Code to pull that file's contents into context when it loads CLAUDE.md (memory docs). Your CLAUDE.md can be a single import line, or the import plus a few Claude-specific notes. - Symlink. If you want one source of truth and no extra file content, make CLAUDE.md point at AGENTS.md:

    ln -s AGENTS.md CLAUDE.md

    Claude Code follows the link and reads the target. Both files then stay identical because they are the same file.

There is also a generation path. Running /init can read an existing AGENTS.md once to seed a new CLAUDE.md (memory docs). That is a one-time copy at generation time, not per-session loading; edits to AGENTS.md afterward will not reach Claude Code unless you re-run /init or use one of the two mechanisms above.

  • Use the import line when CLAUDE.md needs to carry anything Claude-specific in addition to the shared rules, or when you want the two files to stay distinct in version control.
  • Use the symlink when the two files should always be byte-identical and you would rather not maintain a second file at all. Note that a symlink can confuse tooling on some platforms and is awkward on Windows checkouts, so prefer the import line if your team is mixed.

Will the two files conflict?

With a single import line or a symlink there is one source of rules, so there is nothing to conflict. A conflict only appears when you maintain overlapping instructions in both files and let them drift. If you keep separate content in each, treat AGENTS.md as the shared base and reserve CLAUDE.md for the Claude-specific additions, so the two never restate the same rule with different wording.

The deeper point is that what gets loaded, from where, and in what order is the substance of context engineering — deciding what belongs in the always-loaded file versus what the agent should fetch on demand. The full treatment, with a runnable lab on the Triage repo, is Module 1. Next step: open your CLAUDE.md, add @AGENTS.md, and start a fresh session to confirm the shared rules are in effect.