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 first thing it reads. So that'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, but you can still keep one file for both. Below: how each tool finds its file, what to put in it, an example for a small Next.js app, and what to leave out.

How Claude Code reads CLAUDE.md

When it starts, Claude Code loads CLAUDE.md and CLAUDE.local.md from the folder you're in and every folder above it. It stacks them from the top of the drive down, so the file closest to where you started is read last (Claude Code memory docs).

Files in folders below you load later, only when Claude opens 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. Those imports get filled in at launch, and an imported file can import another, up to four levels deep.

Two commands help. Run /context in a session to see which memory files actually loaded. Run /init to generate a starting file from your code.

Claude Code can also read AGENTS.md directly. The rule: if there's no CLAUDE.md or CLAUDE.local.md in your folder or above it, Claude reads your AGENTS.md. If there is one, it reads only the CLAUDE.md files, unless one of them imports AGENTS.md. The docs say this 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 if your repo relies on AGENTS.md and you add one for yourself, Claude quietly stops 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 gathers its instruction files once per run, in this order (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.

There's a size limit. Codex stops adding files once the total reaches project_doc_max_bytes, which is 32 KiB by default. Anything past that is cut off, not summarized.

To check what loaded, the guide suggests running codex --ask-for-approval never "Summarize the current instructions." from the repo root. /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 short file that points to it. 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, then the Claude-only lines below it. Codex ignores CLAUDE.md and reads AGENTS.md directly.

A symlink (ln -s AGENTS.md CLAUDE.md) also works. But if anyone clones the repo on Windows, the docs suggest the import instead, because Git there can turn a symlink into 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 companies land 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's 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, and which open decisions it should settle itself versus bring back to you.

Anthropic's memory docs suggest keeping each CLAUDE.md under 200 lines. Longer files take up more of the agent's working memory, and it follows them less closely.

They also say when to add a line: Claude makes the same mistake twice, or you type the same correction you typed last session.

Turn vague rules into checks

A rule the agent can't check rarely changes what it does. The memory docs make the same point about formatting: "Use 2-space indentation" works better than "format code nicely." When a line reads like advice, rewrite it as something the agent can check or do:

The right checks depend on the project. A writing workspace needs different ones than a billing service. That's why a copied template helps less than your own commands.

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

Here's an example file for a small Next.js App Router project that uses Vitest, Tailwind, and a Postgres database through Drizzle. It was written for this page, not copied from a real repo. Every line is there because an agent could get that thing 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 choice an agent can't figure out from the code, and guessing wrong rewrites the lockfile. The "before reporting done" 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's about 30 lines. If you have more to say about one area, like rules for API routes, put it in a file inside that folder, such as src/app/api/AGENTS.md.

Codex picks it up when you work in that folder. Claude Code loads it 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 a list of things to leave out. Four 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 the agent's attention.
• 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 puts it this way.

Keep secrets out. The file is committed and shared, and everything in it gets sent to the model provider every session.

Don't rely on it for hard rules, either. Anthropic's memory docs say plainly that CLAUDE.md is context, not something that gets enforced. To block an action no matter what the model decides, they point to a PreToolUse hook, a script that runs before each tool call and can stop it. If breaking a rule would be expensive, don't trust the instruction file to prevent it. Hooks get their own page later in this series.

Keep it honest over time

Treat the file like code. Before adding anything, decide which of three kinds of information it is. Each belongs somewhere different:

• Instructions say how work gets done. They belong in the file.
• Current state is what shipped, what's half-finished, and what's next. It changes weekly, so keep it in an issue tracker or a todo file the agent reads when a task needs it.
• Lessons are corrections worth applying again. Write each one as the mistake plus the replacement behavior. "Be more accurate" gives the agent nothing to do, while "Don't describe a prototype as deployed until you've checked its release state" gives it a check to run.

Claude Code has a second place for this. Auto memory is notes Claude writes for itself from your corrections, saved per repository under ~/.claude/projects/<project>/memory/. The first 200 lines or 25KB of its MEMORY.md index load at the start of every session (memory docs).

Those notes live only on your machine. Teammates, CI, and cloud sessions never see them. So a lesson the whole team needs goes in the shared file. Open /memory now and then to clear out notes that have gone stale.

The Anthropic docs give two warning signs. 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 unclear.

Their advice: review the file when something goes wrong, trim it regularly, and check whether the agent actually behaves differently after an edit. In Claude Code, /doctor will suggest cutting anything it could work out from the code.

Previous in the series: Install Claude Code and Codex, then run a first task. Next: Plan mode and agent-sized tasks.