CLAUDE.md: the context you finally stop re-explaining every session
In the first weeks, I kept retyping the same clarifications at the start of every session: my commit message format, the project's dev port, the ban on the default indigo/violet gradient. None of it hard to explain, all of it re-explained, session after session, as if the agent had never touched this repo the day before. CLAUDE.md solves exactly this problem: a markdown file, loaded automatically when Claude Code starts, that acts as the project's persistent memory.
What it actually replaces#
On a human team, this role is filled by onboarding and internal documentation: conventions aren't re-explained for every new task, they're written once and consulted when needed. CLAUDE.md does the same thing for an agent, with one difference: it isn't consulted "when needed", it's loaded systematically, every session, before the first response. That's what distinguishes it from a skill, which only loads if the model judges the context warrants it: CLAUDE.md has no such filter, it's always there.
One file, or a file that imports others#
This blog's CLAUDE.md is one line:
@AGENTS.mdAll the actual content lives in AGENTS.md, imported through that syntax.
This repo runs on a version of Next.js deliberately ahead of my training
knowledge, and AGENTS.md says so bluntly:
# This is NOT the Next.js you know
This version has breaking changes, APIs, conventions and file structure
may all differ from your training data. Read the relevant guide in
`node_modules/next/dist/docs/` before writing any code. Heed deprecation
notices.That instruction has saved me from more than one dumb bug: an agent coding from training knowledge about an API that has since changed produces code that often compiles, but doesn't do what you'd assume. Forcing it to check the local docs before writing, instead of trusting its memory, directly changes the reliability of the result.
What deserves a place there, and what doesn't#
A CLAUDE.md that grows without discipline slows down every session: it's context loaded systematically, so paid for systematically, even on a task that doesn't need it. The question to ask before adding a line: is this information derivable by reading the code, or does it genuinely need to be written somewhere?
What deserves a place: conventions not derivable from the code itself (commit format, dev port, a ban on a specific visual pattern), project constraints (a framework version ahead of the model's training, a business rule that appears nowhere in the code), and collaboration preferences that don't change from one task to the next.
What doesn't belong there: the project's architecture (readable by exploring the files), the history of decisions (the commit message covers that), and anything already correctly documented elsewhere that a CLAUDE.md would only duplicate, with the drift risk that implies.
AGENTS.md, a standard bigger than Claude Code#
Going through @AGENTS.md rather than writing directly into CLAUDE.md
isn't just a matter of organization. AGENTS.md is a format adopted by
several agentic tools, not just Claude Code: writing a project's conventions
into that file makes them readable by any agent that respects the
convention, without duplicating the content for each tool. CLAUDE.md
stays the Claude Code-specific entry point, but the content that actually
matters lives in a file that doesn't depend on any particular tool.
Testing it like any other doc#
A CLAUDE.md, like a poorly written skill, can exist without actually being followed. The difference with a skill is that it's always loaded: the risk isn't that it fails to trigger, it's that it gets ignored in practice because a rule is poorly worded, contradicts another one, or is buried under too much text to stay a priority. The method I apply is the same as for a skill: write a rule, check on the next session that it's genuinely applied, and rephrase it if it isn't, rather than assuming it is.
What it changes day to day#
The gain isn't only the time saved from not retyping the same instructions. It's consistency: without CLAUDE.md, a session's quality depends on what I happen to remember to specify at the right moment. With it, quality depends on a versioned file, reread and corrected over time, that no longer depends on my memory that particular day. The rule fits in one sentence: anything I would repeat identically on any task in this project belongs in CLAUDE.md, not in my prompt of the moment.