CLAUDE CODE + AGENTS.MD

Use AGENTS.md with Claude Code.

Claude Code reads CLAUDE.md, not AGENTS.md directly. The reliable cross-tool setup is a small CLAUDE.md file that imports the shared AGENTS.md contract.

Published August 5, 2026 · Sources checked August 5, 2026

The short answer

Put the shared project instructions in AGENTS.md. Then create a CLAUDE.md beside it whose first line is @AGENTS.md. Claude Code expands that import when the session starts, and you can keep a small Claude-only overlay underneath it.

@AGENTS.md

## Claude Code only

- Use plan mode before changing more than three files.
- Put temporary notes in CLAUDE.local.md.

This is not a naming trick. Claude Code's current documentation explicitly says it reads CLAUDE.md, not AGENTS.md, and recommends importing AGENTS.md when a repository supports other coding agents.

Check both files locally

Choose one setup

Recommended

Import AGENTS.md

Use @AGENTS.md in CLAUDE.md. It works across operating systems and leaves room for a short Claude-specific overlay.

Exact mirror

Symlink CLAUDE.md

Point CLAUDE.md to AGENTS.md only when both files must stay byte-for-byte identical. Windows may require Developer Mode or administrator privileges, so this is less portable for a team.

Avoid

Copy the same prose twice

Two independent files eventually disagree on commands, paths, or safety rules. Duplication is the failure mode the import pattern removes.

Set it up in three steps

Make AGENTS.md the shared contract.
Keep build commands, project structure, quality gates, safety boundaries, and the definition of done here. Do not put personal preferences in the committed shared file.
Import it from CLAUDE.md.
Add @AGENTS.md as plain text, outside backticks and fenced code blocks. Relative imports resolve from the directory containing the CLAUDE.md file.
Verify a new Claude Code session.
Run /context and confirm that CLAUDE.md appears under Memory files. Ask Claude to state the repository's documented test command, then compare the answer with the shared file.

Use the same pattern in a monorepo

A root import only points at the root AGENTS.md. When a package has a narrower AGENTS.md, put a small CLAUDE.md beside that file and import the local target. Claude Code discovers nested CLAUDE.md files when it works with files in those directories.

repo/
├── AGENTS.md
├── CLAUDE.md        # @AGENTS.md
└── packages/api/
    ├── AGENTS.md
    └── CLAUDE.md    # @AGENTS.md

Keep the nested file focused on that package. Shared rules should remain at the root so every agent receives the same baseline without repeated prose.

If the import is not working

Check the exact file name and case: AGENTS.md.
Keep @AGENTS.md outside inline code and fenced code blocks.
Resolve the path relative to the CLAUDE.md that contains it.
Keep recursive imports within Claude Code's documented four-hop limit.
Start a new session and use /context to inspect loaded memory files.
Remember that Markdown instructions guide behavior; use hooks, permissions, CI, and branch protection for enforced controls.

Sources and maintenance

The import behavior, relative-path resolution, recursion limit, AGENTS.md recommendation, and /context check come from the official Claude Code memory documentation. The shared-file convention is documented at agents.md. Both were checked on August 5, 2026; provider behavior can change.

Need a broader repository review? Use the 18-point AGENTS.md and CLAUDE.md audit checklist.

Check the files before you commit them

AgentsMD Checker compares the shared contract and Claude overlay in your browser, flags likely drift, and prepares a cleaner pair of files without uploading their contents.

Compare CLAUDE.md and AGENTS.md