CLAUDE.md and AGENTS.md: What Coding Agents Read

A coding agent starts every session knowing nothing about your repo except what it can read. The instruction file is the one thing it reads before it reads anything else, so it's where the corrections you keep typing should go.

Claude Code calls that file CLAUDE.md. Codex, and the other tools listed at agents.md, call it AGENTS.md. As of September 2026 the two tools load them differently, and one setup lets you keep a single file for both. This guide covers how each tool loads its file, what to put in it, a worked example for a small Next.js app, and what to keep out.

How Claude Code reads CLAUDE.md

Claude Code loads CLAUDE.md and CLAUDE.local.md from your working directory and every directory above it, at launch. It concatenates them from the filesystem root down, so the file closest to where you started is read last (Claude Code memory docs). Files in subdirectories below you load on demand, when Claude reads a file in that folder.

There are three scopes worth knowing:

A CLAUDE.md can pull in another file with an @path/to/file line. Imports are expanded at launch and can nest up to four levels deep. Run /context in a session to confirm which memory files actually loaded, and /init to generate a starting file from the codebase.

Claude Code can also read AGENTS.md directly. The rule is simple: if there is no CLAUDE.md or CLAUDE.local.md in your working directory or above it, Claude reads your AGENTS.md. If there is one, it reads the CLAUDE.md files only, unless that CLAUDE.md imports AGENTS.md. The docs say reading AGENTS.md directly needs Claude Code v2.1.277 or later.

That rule has a trap in it. A personal CLAUDE.local.md counts as a CLAUDE.md, so adding one to a repo that relies on AGENTS.md quietly stops Claude from reading AGENTS.md for you. The memory docs call this out and offer a Project instructions setting, claude-md-and-agents-md, that loads both.

How Codex reads AGENTS.md

Codex builds an instruction chain once per run (Codex AGENTS.md guide):

1. Global. In ~/.codex (or CODEX_HOME), it reads AGENTS.override.md if present, otherwise AGENTS.md.
2. Project. Starting at the Git root, it walks down to your current directory. In each directory it takes at most one file, checking AGENTS.override.md, then AGENTS.md, then any names you list in project_doc_fallback_filenames.
3. Merge. It joins the files root-down, so guidance closer to your directory appears later and wins.

Codex stops adding files once the combined size reaches project_doc_max_bytes, 32 KiB by default. Past that point your instructions are truncated, not summarized. To check what loaded, the guide suggests codex --ask-for-approval never "Summarize the current instructions." from the repo root, and /init generates a starting AGENTS.md.

One file for both tools

If you use both agents on one repo, keep the rules in AGENTS.md and make CLAUDE.md a thin pointer. The Claude Code memory docs describe this setup:

@AGENTS.md

## Claude Code

- Use plan mode for changes that touch more than one route.

Claude reads the imported file first and then the Claude-specific lines below it. Codex ignores CLAUDE.md and reads AGENTS.md directly. A symlink (ln -s AGENTS.md CLAUDE.md) also works, but the docs advise the import instead if anyone clones the repo on Windows. There, Git can check a symlink out as a one-line text file.

This is the setup this site's own repository uses: a short CLAUDE.md that imports AGENTS.md and adds two Claude-specific notes. One file to edit means the two agents can't drift apart.

What belongs in the file

Both vendors converge on the same test. Anthropic's best-practices page asks of each line whether removing it would cause Claude to make mistakes, and says to cut it if not. OpenAI's Codex best practices list repo layout, build and test commands, conventions, constraints, and "what done means".

In practice that is five kinds of line:

• Commands the agent can't guess. The exact test, lint, and build commands, and which one gates a commit.
• Rules that differ from the defaults. If you use named exports everywhere or forbid a library, say so. Standard language conventions the model already knows are wasted lines.
• Where things live, only where it isn't obvious. One line on the folder that surprises people, not a tour of the tree.
• What done means. The check that has to pass before the agent reports success.
• Boundaries. Files it must not edit, commands it must not run, actions that need a human.

Anthropic's memory docs add a size target of under 200 lines per CLAUDE.md, because longer files use more context and reduce adherence. They also give a trigger for adding a line: Claude makes the same mistake twice, or you type the same correction you typed last session.

A worked AGENTS.md for a small Next.js app

Here is an illustrative file for a small Next.js App Router project with Vitest, Tailwind, and a Postgres database through Drizzle. It isn't copied from a real repo. Every line is there because an agent could get it wrong without it.

# AGENTS.md

## Commands
- Install: `npm ci` (not `npm install`; the lockfile is the source of truth)
- Dev server: `npm run dev` on port 3000
- Before reporting a change as done: `npm run typecheck && npm run lint && npm test`
- Database changes: edit `src/db/schema.ts`, then `npm run db:generate`.
  Never hand-edit files in `drizzle/`.

## Conventions
- App Router only. New pages go in `src/app/`; there is no `pages/` directory.
- Server components by default. Add "use client" only for state or browser APIs.
- Tailwind for styling. No CSS modules, no styled-components.
- Tests sit next to the file they test: `foo.ts` and `foo.test.ts`.

## Boundaries
- Do not edit `.env*`, `drizzle/`, or anything under `.github/workflows/`.
- Do not add a production dependency without asking first.
- Do not run `npm run db:migrate`; a human applies migrations.

## Done means
- The three commands above pass.
- The final message lists every file changed and any command that failed.

Why each section earns its place:

• Commands. npm ci versus npm install is the kind of project choice an agent can't infer from the code, and guessing wrong rewrites the lockfile. The done-gate line turns "looks finished" into a check it can run.
• Conventions. Each line overrides something a model might do by default in a Next.js repo, such as reaching for the pages/ router or adding "use client" to everything.
• Boundaries. These cover generated files, secrets, CI config, and a migration step with real consequences. Codex's own global example includes the same dependency rule (AGENTS.md guide).
• Done means. It forces the agent to report failures instead of burying them in a summary.

It runs about 30 lines. If you have more to say about one area, say API route rules, put it in a nested file such as src/app/api/AGENTS.md. Codex picks it up when you work in that folder, and Claude Code loads a subdirectory's AGENTS.md when it opens a file there, as long as that folder has no CLAUDE.md of its own.

What to keep out

The Claude Code best-practices page has an explicit exclude list. Four items do most of the damage:

• Anything the agent can read from the code. A file-by-file description of the repo goes stale and duplicates what one directory listing shows.
• Long explanations and tutorials. Link to the doc instead. The file loads every session and competes with the actual task for context.
• Information that changes often. Current sprint goals, a list of open bugs, this week's priorities. They'll be wrong next week and the agent will still follow them.
• Self-evident rules. "Write clean code" gives the model nothing to check.

Two more belong on the list even though neither doc frames them this way. Keep secrets out: the file is committed and shared, and anything in it is sent to the model provider every session. Keep hard enforcement out too. Anthropic's memory docs are explicit that CLAUDE.md is context, not enforced configuration, and point to a PreToolUse hook to block an action no matter what the model decides. If breaking a rule would be expensive, the instruction file is the wrong place to rely on it. Hooks get their own page later in this series.

Keep it honest over time

Treat the file like code. The Anthropic docs say that if Claude keeps ignoring a rule, the file is probably too long and the rule is getting lost. If it keeps asking questions the file already answers, the wording is ambiguous. Their suggested habits are to review it when something goes wrong, prune it regularly, and check whether behavior actually changes after an edit. In Claude Code, /doctor will propose cuts for content it could derive from the codebase.

For a longer look at one real instruction file, including what "done" means on this site, read Your CLAUDE.md should explain what done means. For the features that make those instructions pay off across sessions, see Claude Code features that matter after the first demo.

Previous in the series: Install Claude Code and Codex, then run a first task. Next: Your CLAUDE.md should explain what done means.