CLAUDE.mdHow to preserve stable project instructions across sessions without letting the file fill up with noise.
Claude Code starts each session with fresh session memory, which is tolerable once or twice but is wasteful when the same project facts have to be restated every time, things like where output files belong, which folders are generated, and what the preferred test command is.
CLAUDE.md exists to hold that kind of project memory. The file is plain Markdown. If the filename is new to you, the simplest way to think about it is as a short project note that Claude reads at the start of a session; Anthropic's documentation is quite direct on this point. The file gives Claude project context but does not override your judgment. Keep it short and specific to the project.
A prompt says what this session should do. CLAUDE.md says what this project tends to require.
The file gets confusing when several kinds of instruction pile up in it. People drop one-off requests into the project file, stuff reusable procedures into the prompt, add personal preferences next to local architecture notes, and paste in entire READMEs.
The prompt is for the current task: session-specific goals, temporary exceptions, instructions that matter now and may not matter tomorrow. CLAUDE.md is for the project, holding stable commands, conventions, and architecture notes that should survive from one session to the next. Auto memory is quieter: small notes Claude writes for itself after a session, things like "this user prefers bun over npm" or "tests live in the /spec directory," which accumulate without your having to maintain them. A skill carries a recurring workflow that benefits from its own reference files, templates, or scripts.
CLAUDE.mdCLAUDE.md.claude/rules/CLAUDE.mdMaterial in CLAUDE.md should be stable, local, and testable. The sample below gives a sense of the grain: path conventions, commands that should actually be run, warnings about generated files. Anything that made you correct Claude twice in the same week is a good candidate.
# Project Notes
- Source pages live in the repository root.
- Do not edit dist/; it is generated output.
- Shared styles live in shared.css.
- Theme behavior lives in theme.js.
- Run npx --yes htmlhint *.html before concluding changes are complete.
- Keep guide copy in a direct instructional voice.
- Prefer existing page patterns over new component systems.
- Save new guide pages in the root unless the project already has a better home for them.Every line names something concrete you can verify. Length and completeness matter less.
Poor fits for CLAUDE.md include volatile task instructions, copied documentation, secrets, unresolved brainstorming, and personal preferences that belong to you rather than the project. If you put every passing thought into the file, Claude has too much to attend to and ignores most of it.
"For this task, update the chart colors, summarize the article, remember that I may want a dark mode version later, and here are three pages of API documentation you might need."
"Charts for this project live in site/assets/charts. Use EDTF (Extended Date/Time Format, a standard for expressing uncertain or approximate dates) when date uncertainty matters. Run the repository export check before changing import code. Do not edit generated files in dist/."
Conflicting rules reduce adherence. If one line says to prefer brevity and another says to include long explanatory notes in every response, Claude cannot follow both. Resolve contradictions when you notice them.
Use ./CLAUDE.md or ./.claude/CLAUDE.md for shared project instructions, ~/.claude/CLAUDE.md (where ~/ means your home folder) for user-level preferences that should apply across projects, and .claude/rules/ when the project needs modular or path-specific rules.
If the project needs different rules for different directories, or if the main file is growing because it is trying to hold several distinct topics, move that detail into .claude/rules/ and let CLAUDE.md stay lean enough to remain readable.
After the first inspection pass, ask Claude to list the conventions and commands it discovered, then ask it to draft CLAUDE.md. If you prefer the built-in path, Anthropic's docs note that /init (typed at the Claude Code prompt) can generate a starting file automatically.
"Inspect this repository and draft a concise CLAUDE.md with project purpose, important commands, local conventions, generated folders, and verification steps. Mark any lines that are still guesses and label them explicitly."
An unmarked guess can survive across sessions long after anyone remembers it was a guess. Mark them.
Anthropic's current docs recommend keeping CLAUDE.md under 200 lines. The recommendation makes sense. A larger file is more likely to hold stale rules, contradictions, or material that belongs somewhere else. In practice, a small file that has been revised based on past mistakes is more useful than an ambitious one written to anticipate every future problem. The small file is short enough that you read it.
Revising the file is what makes it useful. When the same mistake has needed correction several times, it probably belongs in CLAUDE.md. When the file contains stale instructions, Claude follows them as confidently in the next session as it would follow fresh ones. In my own projects, I find myself trimming the file about as often as I add to it. Most of what I remove are instructions that started as one week's workaround and never got cleaned up.
To make the boundary with skills clearer, take a concrete example. In a metadata project, CLAUDE.md might hold path conventions, date formatting rules, and the required verification command. A dedicated skill would hold the import workflow itself, with field mappings, references for a specific platform, and the kind of multi-step procedure that benefits from its own reference files.
One rough test is whether the repeated correction means "this project always works this way" (dates are EDTF, output goes in dist/), edit CLAUDE.md. If it means "this workflow always follows these steps" (the six-step import sequence for loading MARC records), that procedure probably deserves its own skill.
Once the baseline context is stable, you spend less time re-establishing facts at the start of each session. You can also build more ambitious automation, since skills and multi-step workflows can assume Claude already knows how the project is organized. The Skills chapter takes that further.