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.
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.
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.
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.