CLAUDE.md and AGENTS.md are plain-markdown files, checked into your repository, that tell an AI coding agent how your codebase works: its conventions, architecture, and the rules a change must follow. Claude Code reads CLAUDE.md and Codex reads AGENTS.md, but the job is the same. Written well, one lets an agent, or a teammate using one, contribute correctly on day one with no extra prompting.
What is a CLAUDE.md or AGENTS.md file?
It is documentation written for the agent instead of for a person, loaded into the agent's context every session. CLAUDE.md and AGENTS.md are the same idea under two names: Claude Code reads a file called CLAUDE.md, while Codex and a growing number of other tools read AGENTS.md. Both live in the repository, in version control, next to the code they describe. A project can keep both, or point one at the other, so a contributor using any tool gets the same guidance.
Because the file is loaded on every run, it is the most reliable place to put knowledge you want the agent to have without anyone typing it into the prompt. That is also its constraint: it costs part of the model's usable context budget each session, so it earns its length or it does not belong. Managing that budget across a whole session is covered in scaling AI development.
Why do these files matter more as you use more agents?
Because they encode the domain knowledge that used to live in people's heads, and that knowledge is what blocks contribution. When you ramp up on an unfamiliar codebase, most of the friction is not the language or the framework, it is the unwritten conventions: which pattern to follow, which directory a thing belongs in, what the team will reject in review. A coding agent can navigate the code for a newcomer, so people increasingly contribute on day one. What still stops them is the knowledge that was never written down.
There is a blunt way to see this. If you open a pull request against a codebase you do not know and a reviewer rejects it for using the wrong framework or not following the architecture, that is a failure of automation, not a failure of the contributor. The knowledge to get it right existed; it just was not written anywhere the contributor's agent could read it. Writing it down turns a rejection into a correct first attempt.
The leverage also compounds. An automation that speeds up one engineer speeds up one engineer. The same instruction file, or the same lint rule, speeds up every agent you run, so its payoff scales with how many agents are working. This is one of the levers behind moving up the AI adoption stages: the constraint at the top of that ladder is knowing what to encode, not model quality.
What should you put in a CLAUDE.md file?
The knowledge a new teammate would otherwise have to learn from a person. In practice that means:
- Conventions: naming, file layout, and where a given kind of code belongs.
- Architecture: the patterns to follow and the ones to avoid, and why.
- Commands: how to build, test, lint, and run the project.
- Guardrails in prose: what to never do, and where the real complexity or danger lives.
The target to aim for is that an agent can work productively from the file with zero additional context from whoever prompts it. If a task still needs a paragraph of explanation pasted into the chat every time, that paragraph belongs in the file.
What should you leave out of a CLAUDE.md file?
Anything the agent could work out by looking at your repository. That is the sharpest rule available, and it comes from Anthropic's own guidance for its newest models as of July 2026: keep the file lightweight, say briefly what the repo is for, and spend most of the tokens on gotchas instead.
A gotcha is something unguessable. If your project keeps every type in one monolithic file and nowhere else, no amount of reading the directory tree reveals that as a rule rather than an accident, so it belongs in the file. The directory tree itself does not. This lands on the same conclusion practitioners reached from the other direction: a file that is mostly an index of where code lives is a bad guide, because it spends your budget restating what the agent can already see.
Three habits follow from it.
Split the file rather than growing it. The tempting mistake is to treat the file as the one place every practice must live, on the theory that the agent will not find anything you leave out. Modern agents read referenced files reliably, so that assumption is now pure cost. The better shape is a short root file plus a tree of documents it points to, loaded when relevant. If you have several unique instructions on how to verify your work, they belong in a verification skill that the root file references, not in the root file. Anthropic calls this progressive disclosure and applies it to its own tooling.
Stop using it as a memory dump. Saving stray facts into CLAUDE.md was standard advice when it was the only place an agent could remember anything. Tools now maintain their own memory across sessions, so the instruction file can go back to holding instructions. If yours has grown a sediment layer of remembered details, that is a different feature's job now.
Point at code instead of describing it. A specification can be a test suite. An interface can be a function in another codebase to copy. A design can be an HTML mockup rather than a paragraph describing the design. Code-shaped references are unambiguous in a language the model already knows well, and they beat prose descriptions of the same thing.
How short should the file be?
Shorter than instinct suggests, and the evidence on this changed recently. Anthropic reports removing more than 80 percent of Claude Code's own system prompt for its newest models with no measurable loss on its coding evaluations. The instructions were not merely wasteful. Many had been written to guard against failures that older models made and newer ones do not, so keeping them meant the model had to reconcile a stale rule against your actual request before doing any work.
Two cautions on how far to take that. It was measured by a vendor, on its own product, against its own evaluations, so it is evidence that large cuts are possible rather than proof that 80 percent of your file is dead weight. And the cut is not indiscriminate: rules that encode judgment you cannot mechanize, and gotchas nobody can infer, are what the remaining fraction is made of.
The practical version is a triage question for each block in your file. Is it wrong now, given what this model actually does? Delete it. Is it true but needed on one task in ten? Move it into a referenced file. Is it true and needed every session? That is the file. For the model-specific side of this, which instructions backfire and what to delete first, see prompting Claude 5 models.
How do you write a good CLAUDE.md or AGENTS.md?
Hand-write it, and steer toward success rather than toward the code. Three habits separate a file that works from one that does not.
First, write it yourself. Do not have the agent generate it. Writing the file is how you learn what actually changes the model's behavior, and an auto-generated file tends to be a map of where things are, which is the least useful thing it could be. A file that just lists where code lives is a bad guide. The file should push the agent toward the outcome you want, not narrate the repository.
Second, encode fixes for problems you have actually seen. Do not pre-install a pile of skills and plugins in advance. Use the tool as it comes, give it as little context as possible at first, watch what goes wrong, then write the rule that would have prevented it. Building for observed failures rather than imagined ones keeps the file short and every line earned.
Third, do not be afraid to encode pushback. A rule as direct as "if someone asks for feature X, stop and tell them no" placed in AGENTS.md actually changes what the agent does. Small edits to these files move behavior meaningfully, which is exactly why hand-writing and iterating on them is worth the time.
When should knowledge go into code instead of a file?
Whenever the rule can be checked mechanically, put it in code, not in the file. A rule written in CLAUDE.md is, to the model, just more text in the prompt, so it is a suggestion the agent can miss. A lint rule or a continuous-integration check is a gate the agent cannot skip. So the two layers divide the work: judgment that resists mechanization stays in the instruction file, and anything you can express as a check moves into the clean code for AI agents checker that runs on every commit.
This is also the more durable fix when an agent keeps making the same mistake. Fixing the instance each time spends tokens and misses cases. Writing one lint rule, CI step, or routine automates the whole class of mistake forever, for every contributor and every agent. The economics of this changed recently: a custom rule that takes a few hundred lines to catch one project-specific quirk used to be permanent manual review labor, so nobody wrote it. Now an agent writes the rule and its tests cheaply, so per-project automation that was never worth a person's afternoon is worth an agent's minutes.
What about skills, REVIEW.md, and custom tooling?
They are the same practice at different scopes. A skill is a task-scoped instruction file, useful for a complex procedure the agent performs repeatedly, and it follows the same rule: encode it from an observed need, and keep the total small, because too many skills degrade the agent rather than helping it. A REVIEW.md, or a set of code-review rules, moves your review standards into automation so that convention violations get caught without a human having to remember them. Custom tooling counts too: teams now build small services and scripts that give agents abilities they lacked, such as running a preview environment, testing it, and reporting the result back on a pull request. The common thread is converting something a person used to do or know into infrastructure an agent can use.
Published skill sets follow the same shape, which makes them a useful thing to read before writing your own. The antics agent skills for making multiplayer games are task-scoped documentation for one narrow job, teaching an agent how to design, test and ship a browser game. Note what they do not try to be: a general guide to game development. That is the rule holding in practice, since a skill earns its context only when the procedure is specific and repeated.
Who benefits when you encode this knowledge?
Everyone who touches the codebase next, including future you. The immediate win is that your own agents write better code with less prompting. The larger win is that the next person, engineer or not, can contribute without first absorbing everything in your head, because their agent reads what you wrote. This is why the skill is starting to look less like a chore and more like the highest-leverage work available: building the system that lets code land well is becoming a bigger contribution than landing the code yourself. One honest caveat: better encoded knowledge lets more people contribute on day one, but the claim that non-engineers contribute as effectively as engineers is not established, so treat day-one contribution, not parity, as the real result.
If you are earlier in the picture and still working out what an agent is and how it uses these files, start with what is an AI agent. For getting the most out of one specific tool, see how to use Claude Code properly, and for the wider set of practices, the Learn AI section.
FAQ
Is CLAUDE.md the same as AGENTS.md?
Effectively yes. They are the same concept under two filenames: Claude Code reads CLAUDE.md, and Codex and several other tools read AGENTS.md. Many projects keep both, or make one point at the other, so that contributors on any tool get the same instructions.
Should I let the AI write my CLAUDE.md?
No. Hand-write it. Writing the file yourself is how you learn what actually steers the model, and an agent-generated file tends to describe where code lives rather than how to succeed, which is the wrong thing to optimize for.
How long should a CLAUDE.md file be?
As short as it can be while still steering the agent toward good work. The file is loaded into context every session, and context is a budget, not free space. Past a point, more instructions degrade the agent instead of helping, so cut anything that is not earning its place. For scale, Anthropic cut more than 80 percent of Claude Code's system prompt for its July 2026 models without measuring a drop in coding quality.
Does my CLAUDE.md need updating when I switch models?
Yes, and a model upgrade is the best moment to re-read it. Much of what accumulates in these files is defensive: rules written to stop a specific failure a particular model used to make. When the model changes, some of those rules are protecting you from nothing and are now competing with your real instructions for the model's attention. Delete any rule you cannot tie to behavior you have actually seen from the model you use today.
What is the difference between a CLAUDE.md rule and a lint rule?
A CLAUDE.md rule is a suggestion the model can skip, because to the model it is just text in the prompt. A lint rule or CI check is a gate that cannot be bypassed. Put anything you can check mechanically into code, and keep the instruction file for the judgment that cannot be automated.