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.

AGENTS.md works too (2.1.277, September 2026). In a project with no CLAUDE.md, Claude Code now reads AGENTS.md instead, the instruction file other coding agents already use. Switch the behavior under "Project instructions" in /config. It is a fallback: a repo that has a CLAUDE.md keeps using it. Not yet available on Bedrock, Vertex or Foundry. The loader is now a built-in mod, cc-plugin-agents-md, which you can disable in /plugin.

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.
• One file for a mixed-tool team. If teammates use other agents, a single AGENTS.md now serves everyone. If you keep both files, only CLAUDE.md loads, so do not let them drift apart.
• Audit it when models change. /doctor prompt-audit (also /checkup prompt-audit, 2.1.283) checks your CLAUDE.md, AGENTS.md, rules, skills, commands and subagents for instructions written for older models, references to files or commands that no longer exist, and files that contradict each other. It proposes edits and changes nothing until you say so. Pass a path to audit one file or folder. A good habit after each model upgrade.
• 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.