CLAUDE.md and AGENTS.md: where they go, how they load, and what they can't enforce

CLAUDE.md is a plain markdown file that Claude Code reads at the start of every session, so you stop repeating yourself. This guide covers where to put it, how it loads, and a surprising AGENTS.md gotcha that we reproduced. The behavior described here comes from Claude Code's documentation, and we checked the parts marked "tested" in real Claude Code 2.1.278 sessions in September 2026.

Where to put it

Run /init inside Claude Code to generate a starting file from your codebase. To confirm a file loaded, run /context and look under "Memory files".

How the files load

• Claude reads CLAUDE.md and CLAUDE.local.md from your working directory and every folder above it, when the session starts.
• Files in subfolders below where you started are loaded later, when Claude reads a file in that subfolder.
• Files are combined, not replaced. They are ordered from the top of the tree down, so the instructions closest to where you started are read last.

Writing one that works

These points come from the documentation:

• Keep it under about 200 lines. Longer files use more of the context window and are followed less reliably.
• Be specific enough to check. "Use 2-space indentation" beats "format code properly". "Run npm test before committing" beats "test your changes".
• Don't contradict yourself. If two rules conflict, Claude may pick one arbitrarily.
• Put multi-step procedures elsewhere. Use a skill (a custom slash command) for a procedure, and keep CLAUDE.md for facts Claude should hold in every session.

A starting point with the concrete kind of instruction that works:

# Project instructions

## Commands
- Install: `npm install`
- Dev server: `npm run dev`
- Tests: `npm test` (run before saying a task is done)
- Lint and typecheck: `npm run lint && npm run typecheck`

## Layout
- `src/api/handlers/` holds API handlers
- `src/lib/` holds shared code
- `db/migrations/` holds database migrations

## Rules
- Use 2-space indentation and named exports.
- Read the relevant files before changing them, and match the existing style.
- Make the smallest change that solves the problem.

Imports, local files and comments (tested)

We made a scratch project with a CLAUDE.md that contained a codeword, an @docs/build.md import, and a hidden HTML comment, plus a CLAUDE.local.md with a nickname. Then we asked Claude, with file-reading tools switched off, what it could see. Results:

An import is written as @path/to/file and resolves relative to the file that contains it. To mention a path without importing it, wrap it in backticks.

The AGENTS.md gotcha (tested)

Many repositories use an AGENTS.md file shared by several AI tools. Claude Code can read it directly, but only when you have no CLAUDE.md or CLAUDE.local.md in your working directory or above it. That includes your personal CLAUDE.local.md. We reproduced all three cases:

So if you add a CLAUDE.local.md to a project that relies on AGENTS.md, your team's instructions quietly stop loading for you. The fix is to keep AGENTS.md as the shared file and add a CLAUDE.md next to it that imports it, with any Claude-specific notes below:

@AGENTS.md

## Claude Code
Use plan mode for risky changes.

There is also a setting for this. Type /config and set Project instructions to claude-md-and-agents-md to make Claude read both files. Reading AGENTS.md at all needs Claude Code 2.1.277 or later.

What CLAUDE.md can't do: enforce

Claude Code's documentation is direct about this: both memory systems are loaded as context, "not enforced configuration," and to block an action regardless of what Claude decides, you should use a PreToolUse hook. In our own git push test, a CLAUDE.md line saying "never push" made Claude decline by itself. That is worth having, but it is a request, not a guarantee. For rules that must hold, add a permission rule or a hook as well. The Safe setup pack pairs a CLAUDE.md with the hooks that back it up.