Memory & CLAUDE.md

CLAUDE.md is a plain Markdown file that Claude Code reads automatically at the start of every session. It is how you give Claude standing orders (code style, key file locations, testing commands, repo etiquette) without pasting them into every prompt. There is no in-session memory that persists between conversations; CLAUDE.md is the substitute. Keep it short: it is loaded every turn, so dead weight costs you context and attention.

There are two levels. Project-level (CLAUDE.md at the repo root, and optionally in child directories for monorepo modules) sets rules for everyone on the team, so commit it. User-level (~/.claude/CLAUDE.md) sets personal rules that apply across all your projects: your preferred commit style, cost guardrails, workflow habits. The two stack, global first and then project, so project rules can override your global defaults when they conflict.

How you use it day-to-day

• Seed it from a session. Press # during any conversation and Claude will write your instruction directly into CLAUDE.md instead of just remembering it for the turn.
• Put commands in it, not prose. Quick-start commands (npm install && npm run dev), test runner invocations, and lint commands are the highest-ROI entries, since Claude can run them without asking you how.
• Flag non-obvious patterns. API route conventions, state management libraries, logger utilities, env file rules ("NEVER commit .env"): anything that isn't obvious from reading the code.
• Use emphasis for critical rules. IMPORTANT and YOU MUST prefixes measurably improve adherence on rules that Claude tends to ignore at plain priority.
• Share it via git. Project CLAUDE.md belongs in version control. Team members and CI runs pick it up automatically. It is the cheapest way to align everyone on style and workflow conventions.
• Document custom bash tools here. If your repo has internal scripts or generators, note them with a one-line usage example so Claude discovers them without --help spelunking.

Gotchas

• It loads every turn, so size matters. A bloated CLAUDE.md degrades context availability for actual work. Treat every line as a prompt you're paying to send on every request. Prune aggressively.
• Iterate like a prompt, not a doc. Rules that don't change Claude's behavior aren't helping. Run the file through a prompt improver occasionally and test whether adding or removing a rule actually changes output.
• Subagents inherit it; conversation history does not transfer. A spawned subagent starts fresh from conversation history but does load your CLAUDE.md. Brief subagents explicitly for anything not covered there.
• Tuning takes experimentation. Avoid dumping extensive content without testing whether it helps. Add one rule, observe behavior, then add the next.

Global vs project layering. Your ~/.claude/CLAUDE.md is the floor: personal non-negotiables that apply everywhere. Each project's CLAUDE.md is the ceiling: it can add specifics and override your global defaults, but you don't have to repeat universals in every repo.