Overview
Claude Code has no memory across sessions. CLAUDE.md is the file that replaces memory. Every session begins with Claude reading it, and every session ends with Claude respecting what is in it. Write the rules that must hold across every session into this file. Leave everything else out. See claude-code-workflow for the anchor file trio; this page covers the design of CLAUDE.md specifically.
Put CLAUDE.md at the repo root
Claude Code searches for CLAUDE.md starting at the working directory and walking up to the repo root. Always place it at the repo root so every session finds it regardless of where the session starts.
One CLAUDE.md per repo. If the repo has sub-packages with distinct rules, add CLAUDE.md files in those subdirectories. The sub-file rules apply when Claude is working in that subtree; the root file always applies.
Write mission and environment first
The first section tells Claude what the repo is and what it is for. Two to four sentences.
## Mission
Maintain `myapp.com`, a Next.js 14 SaaS. Pages are built with the App Router.
The stack is TypeScript, Prisma, and Postgres 17. The live site is at myapp.com.Include the live URL, the stack, and the deploy target. Claude needs these to answer “does this change break production?” before reaching for a tool.
Write voice rules when the output is prose or code with comments
Voice rules are the constraints that keep output consistent across sessions. Without them, each session drifts.
## Voice rules
- Neutral playbook voice. Lead with the rule, then the rationale.
- No em-dashes. Use periods or commas.
- No slop preambles ("Let's dive in").
- Code comments explain why, not what.Pin specific bans, not vague adjectives like “be concise.” A ban is enforceable; an adjective is not.
Write the content schema and folder map for content-driven projects
For sites and documentation repos, the content schema is the single most load-bearing section of CLAUDE.md. Every session that adds content should copy the schema field-for-field from this file.
## Content schema (YAML)
Every page begins with:
title, slug, category, tags, status, last_updated, summary, related
Field rules: status is one of draft, stable, deprecated. slug is filename without extension.Follow the schema section with the folder map. A flat list of folders and their purpose lets Claude place new files without asking.
Separate CLAUDE.md from TODO.md and README
Three files, three jobs. Do not conflate them.
CLAUDE.md: rules, schema, architecture, folder layout, “how to add a thing.” Does not change often. Claude reads it first every session.TODO.md: open work, backlog, research questions, deferred items. Changes every session. Claude updates it as work ships.README.md: human-facing project overview. Points to live site, install instructions, contributor guide. Claude does not read it automatically.
Putting the task list in CLAUDE.md means Claude reads stale tasks alongside standing rules, which creates confusion. Keeping them separate lets each file evolve at its natural rate.
Include how-to-add procedures as step-by-step instructions
Instructions reduce tool calls. When Claude knows the exact procedure for “add a new page,” it does not need to explore the repo before acting.
## How to add a new page
1. Choose the category folder.
2. Create `<slug>.md` with full frontmatter.
3. Set status: draft unless the page is complete.
4. Add a bullet to the folder's index.md MOC.
5. Run `npx quartz build` and confirm no errors.Write these procedures in imperative steps, not in prose. Claude follows numbered steps without needing to interpret intent.
Keep CLAUDE.md under 500 lines
A long CLAUDE.md wastes context budget on every session. Every line Claude reads is a line it cannot use for work.
Prune rules that have never fired. Move reference material (full API schemas, historical context) to linked files and add a See also: pointer. The goal is a file Claude can read in ten seconds and hold in working memory for the entire session.
Related context that changes per task belongs in the brief, not in CLAUDE.md. See prompt-design for brief structure.