How to Write a CLAUDE.md That Agents Actually Follow

A project memory file is the cheapest improvement you can make to a coding agent. It takes an hour to write and pays back on every task. It is also easy to get wrong: most bad CLAUDE.md files are too long, restate what the code already says, or try to enforce rules that a text file cannot enforce. Here is how I write them on client projects, with an annotated example.

What is a CLAUDE.md file, and how does it relate to AGENTS.md?

CLAUDE.md is a Markdown file of instructions that Claude Code reads at the start of every session. The memory documentation describes several scopes: a project file committed to the repository for the team, a personal CLAUDE.local.md that stays out of git, a user-level file for your own preferences, and organisation-wide managed files. Files in the directories above where you start are loaded at launch; files in subdirectories load when the agent works there.

AGENTS.md is the tool-neutral version of the same idea. Its site describes it as "a README for agents", says it is used by over 60,000 open-source projects, lists support in tools including OpenAI Codex, Cursor, GitHub Copilot's coding agent, Gemini CLI and many others, and notes that it is now stewarded by the Agentic AI Foundation under the Linux Foundation. Claude Code can read an AGENTS.md in place of CLAUDE.md when the repository has no CLAUDE.md, or you can import it from a CLAUDE.md with a line such as @AGENTS.md so both tools share one source.

On client projects I follow whatever the team already uses. If several coding agents are in play, one AGENTS.md imported into a short CLAUDE.md avoids two files drifting apart.

What should go in a CLAUDE.md?

Only what the agent cannot work out by reading the repository. Anthropic's best practices give a two-question test: could it find this by reading the code, and would it actually go and look? If both answers are yes, leave it out. The same page lists what passes:

• How to confirm work: the exact test, typecheck and lint commands, and how to run a single test file.
• Places where the code is misleading: an old pattern that is everywhere but new code must not copy, or a directory that looks unused but is not.
• Decisions that are not in the repo: which error helper the team settled on, how deploys work, what needs a migration review.
• Anything you have had to correct twice.

The first item matters most. The docs call the command that runs your check "the single most useful line in your CLAUDE.md", because it lets the agent verify its own work. I wrote a whole post on why in give the agent a way to check its work.

An annotated CLAUDE.md example

This is the shape I start from for a TypeScript and Next.js client project. The specific paths are illustrative; the point is the kind of line in each section and why it earns its place.

Notice what is missing. There is no tour of the folder structure, because the agent reads it faster than I can describe it. There is no "write clean, maintainable code", because it changes nothing. And there is no "never edit generated files", because that is a rule, not a guideline.

What should you leave out of a CLAUDE.md?

Leave out anything the code already says, anything generic, and anything that must happen every time. The memory documentation recommends targeting under 200 lines per file, because "longer files consume more context and reduce adherence." Every line is read on every task, relevant or not.

Three places take what does not belong in the file:

• Skills for long procedures. A release runbook in a skill loads only when the task needs it, so it does not weigh on an unrelated bug fix.
• Path-scoped rules for one area of the code. A rule file with a paths filter loads only when the agent touches matching files, and in a large repository a per-directory CLAUDE.md does the same job.
• Hooks and permission rules for anything with zero exceptions. The best practices page is explicit that CLAUDE.md "is for guidelines, and Claude is allowed to decide a guideline doesn't apply." If a line keeps being ignored, it is either lost in a long file or it is a rule that belongs in configuration.

How should you write each line so the agent follows it?

Write every line as a specific, checkable instruction rather than an aspiration. The memory documentation says that the more specific and concise your instructions, the more consistently Claude follows them, and that organised sections under Markdown headings are easier to follow than dense paragraphs.

In practice that means a few small habits:

• Name the thing. "Use the error helpers in lib/errors.ts" beats "handle errors consistently".
• Give the command, not the advice. "Typecheck: pnpm tsc --noEmit" beats "make sure types are correct".
• Say why when it is not obvious. "lib/legacy is still live" explains why the agent should not delete it.
• One instruction per bullet. Long bullets hide the second instruction.
• Write for a capable newcomer. If a new senior engineer would not need the line, the agent probably does not either.

How do you keep a CLAUDE.md useful over time?

Treat it as a living document with the same review as code. On client projects I use a few habits:

• Start from /init, then delete. The docs note that /init generates a starting version from the codebase, and from there "the work is mostly removing lines."
• Add a line when you correct the agent twice. That is the clearest signal a fact was missing.
• Check for conflicts. The memory docs warn that if two instructions contradict each other, Claude may pick one arbitrarily. Review nested files and rules periodically.
• Revisit after major model releases. Anthropic's large codebase guide points out that instructions written around an older model's limitations can become overhead once newer models handle the case themselves.
• Confirm it loaded. Running /context all in a session lists the memory files that loaded.

A good memory file is also part of a clean handover. When I leave a project, the client's own engineers and their agents inherit everything I learned about the codebase, which is the practical side of the context engineering approach I use in unfamiliar codebases. And because it tells the agent where the traps are, it prevents a share of the almost-right code that would otherwise need catching in review.

Work with me

I set up coding agents for client teams, including memory files, skills, hooks and checks that make them reliable in real codebases. See AI agent development and full-stack development, or browse my work and book a scoping call.