Claude Code has no memory between sessions. Everything it knows about your project either comes from the files it reads at startup or gets rediscovered, slowly, every time. These three files are how I stop paying that cost.
1. A global CLAUDE.md (lives at ~/.claude/CLAUDE.md)
Rules that apply to every project: how you like things written, your tooling defaults, what the assistant should never do without asking.
# Global CLAUDE.md
These preferences apply to every project unless a project CLAUDE.md overrides them.
## Style
- [Your writing rules. Mine: never use em dashes; no marketing speak in comments or READMEs.]
- Match the existing voice in client deliverables, do not impose mine.
## Conventions
- Language / package manager: [e.g. Python 3.11+, conda or uv]
- Tests: [e.g. pytest]. Use the existing test framework, do not introduce a new one.
- Formatter and linter: [e.g. ruff]
## Subagents
Set the model explicitly when spawning subagents; they inherit the session model otherwise.
- Data gathering (reads, greps, counting): small fast model
- Analysis, code review, synthesis: mid model
- Multi-step reasoning, anything where a wrong answer costs money: biggest model you use
## General behavior
- Before a significant refactor, summarize the plan before changing files.
- When in doubt about a dependency or a breaking change, ask first.
- At the end of a working session, update `.claude/handoff.md` if it exists.
## Never
- Commit or push. I drive git.
- Add dependencies without asking.2. A project CLAUDE.md (lives at the repo root)
Hard constraints the model cannot infer from the code. The last two sections are the ones that earn their keep.
# Project: [NAME]
[One-line description.]
## Project-specific conventions
(What differs from the global file or adds to it.)
-
## Project structure
- `src/`: [what lives here]
- `tests/`: [what lives here]
## What not to touch
- [Generated files, vendored code, data directories, anything regenerated by a pipeline]
## Things Claude has gotten wrong before
- [Every correction you have had to make twice goes here]3. A session handoff (lives at .claude/handoff.md)
Written at the end of each session, read at the start of the next. Four sections, no more.
# Session handoff
Last updated: [YYYY-MM-DD]
## What was completed
-
## Key decisions and why
-
## What to avoid next time
-
## Exact next step
-“Exact next step” matters most. A vague next step (“keep working on the dashboard”) costs the next session ten minutes of rediscovery. A precise one (“wire the export button in src/Export.jsx to /api/export, the endpoint already works”) costs zero.
How they layer
Global for how you work, project for what this codebase needs, handoff for where you stopped. Do not repeat in a prompt what one of these files already says; the model has read it.
