Claude Code CLAUDE.md: The Practical Guide to Project Memory

Claude Code loses all context when a session ends. That is not a limitation of the tool — it is a property of how large language models work. Each session starts fresh, with no memory of what you discussed, what files you read, what decisions you made, or what you were in the middle of building.

CLAUDE.md is the designed solution to this. It is a markdown file that Claude Code reads at the start of every session, injecting project-level context before you write your first message. Done well, it means Claude Code understands your codebase architecture, your conventions, your deployment targets, and your non-obvious constraints without you having to explain them every time.

Done poorly, it adds noise that consumes context without providing value — and it still does not solve the problem people most often want it to solve.

Where CLAUDE.md files live

Claude Code supports CLAUDE.md files at three levels, each with different scope:

Location	Scope	Use for
~/.claude/CLAUDE.md	All projects on this machine	Global preferences, tools you always use, your working style
./CLAUDE.md	Current project only	Project architecture, conventions, commands, non-obvious constraints
./subdir/CLAUDE.md	Subdirectory scope	Service-specific context when working in a monorepo

All applicable CLAUDE.md files are loaded at session start, in order from global to local. Project-level overrides global where they conflict.

The contents count against the context window. A global CLAUDE.md at 800 tokens and a project CLAUDE.md at 1,200 tokens adds 2,000 tokens to every session before you write anything. That is small compared to a 200,000-token context window. It becomes meaningful if your CLAUDE.md files grow unchecked.

What to put in CLAUDE.md

The question is not "what does Claude Code need to know?" The question is "what would I have to explain at the start of every session if CLAUDE.md did not exist?" Those are different questions.

The first leads to documentation. The second leads to useful session context.

High-ROI content:

• How to run the project. The exact commands to build, test, and run. Not documentation prose — the commands themselves, formatted so Claude Code can use them directly.
• Non-obvious architecture decisions. Why the service is split the way it is. Why the data model is shaped the way it is. Not what it is — that is derivable from the code. Why it is.
• Active constraints and in-progress work. What you are not changing right now and why. What is broken on purpose. What is temporary.
• Coding conventions that are not enforced by tooling. If your linter enforces it, Claude Code will see it in the code. If it is informal convention, put it in CLAUDE.md.
• Key files and their purpose. In a large codebase, the file that controls X or the file where Y is configured is not obvious. A short map of non-obvious locations saves a read operation every session.

# Project: Payments Service

## Build and test
cargo build --release
cargo test -- --nocapture
cargo clippy --all-targets

## Architecture
- src/handlers/ — HTTP entry points only. No business logic.
- src/domain/ — Business logic. No I/O. Pure functions where possible.
- src/infra/ — DB, external API clients, event publishers.
Domain layer must not import from infra layer. This is enforced by module visibility.

## Active constraints (as of 2026-05-07)
- Do NOT touch src/infra/stripe.rs — migration in progress, PR #441 owns it.
- The settlement reconciler (src/domain/settle.rs) has a known off-by-one on DST boundaries. Not fixing until next quarter. Do not "fix" it.

## Non-obvious files
- config/feature-flags.toml — runtime feature flags, loaded at startup
- scripts/seed-dev.sh — populate a local dev DB with realistic test data

Low-ROI content that adds noise:

• General descriptions of what the project does (derivable from the README Claude Code will read anyway)
• Lists of every file and what each one contains (Claude Code reads the directory structure itself)
• Generic instructions like "write clean code" or "follow best practices"
• Outdated information you have not updated in months

The global CLAUDE.md: personal working style

The global ~/.claude/CLAUDE.md is where you encode how you want Claude Code to work with you across all projects. This is genuinely useful because it removes friction on preferences that should apply everywhere but are not enforced by any project-level convention.

Useful global entries:

• Your preferred response style (terse or detailed, code-first or explanation-first)
• Tools or commands you always want Claude Code to have available
• Security guardrails you want enforced globally (never run rm -rf without confirmation, always read a file before editing it)
• Commit message style or PR body format you use across all projects
• The model behavior you want when you give an unclear instruction (ask for clarification vs. make a reasonable assumption and proceed)

# Global — applies to all projects

## Response style
Lead with the code or command. Explanation after, not before.
One sentence of context is enough. Do not explain what you are about to do — do it.

## Safety rules
Always read a file before editing it.
Never delete files without listing them first and confirming.
When in doubt about destructive operations, ask.

## Commit messages
Imperative mood, 50 chars or less for the subject.
Reference issue number if one exists.
No co-author footers unless I ask for them.

Keeping CLAUDE.md current

A CLAUDE.md that is six months out of date is worse than no CLAUDE.md. It actively misleads — Claude Code will confidently follow instructions that no longer apply, use commands that have changed, avoid constraints that have been resolved, and preserve architecture decisions that have been replaced.

The maintenance pattern that works: treat CLAUDE.md as a living document that changes alongside the codebase. When a constraint is lifted, remove the constraint. When a non-obvious file moves, update the path. When the build command changes, update it immediately — not at the end of the PR, in the same commit.

One useful heuristic: if you would be embarrassed to show your CLAUDE.md to a new hire as a project orientation document, it needs a pass. Either it contains things that do not belong there, or it is missing things that a new person would need to know.

What CLAUDE.md cannot do

CLAUDE.md solves the cross-session problem for static project context. It does not solve two classes of problems that engineers frequently want it to solve:

1. Mid-session context loss. When Claude Code's context window fills during a long session, CLAUDE.md is already loaded. It does not help you recover the decisions you made, the files you read mid-session, the approach you were taking, or the partial work in progress. The context limit clears all of that regardless of what CLAUDE.md contains.

2. Dynamic session state. CLAUDE.md is read once at session start. It cannot capture what happened in the current session. If you make an architectural decision mid-session, that decision lives in the conversation context. It does not flow back into CLAUDE.md automatically, and it is not available to the next session unless you manually update the file.

These are not criticisms of CLAUDE.md. They are boundaries. CLAUDE.md is the right tool for project-level static context. It is not the right tool for session continuity.

The session continuity gap

The gap CLAUDE.md does not fill is the one engineers feel most acutely: picking up a long session after the context window fills, or after a day boundary, or after a context switch to a different task. The session was making progress. That progress is not in CLAUDE.md. It is in the conversation that is now gone.

What fills this gap is not a better CLAUDE.md strategy. It is structured session handoffs — capturing the working state of a session (decisions made, files read, current task state, what remains) into a compact format that a new session can load and continue from.

This is what Bring Your AI does. It is a portable coding harness that handles the handoff layer: when your session hits the context limit, it exports the structured session state. The next session — in Claude Code, Codex, or Cursor — loads the handoff and continues without re-explaining the full task.

# When Claude Code hits the context limit mid-refactor:
$ bya export --session current
Exported: .bya/handoff-2026-05-07T09:18.json

# Resume in a fresh Claude Code session:
$ claude --import .bya/handoff-2026-05-07T09:18.json

# Or hand off to Codex:
$ codex --import .bya/handoff-2026-05-07T09:18.json

The handoff is not a transcript. It is structured state: the task definition, the approach, the decisions, the current partial artifacts, and what the next session needs to do. Small enough to fit well within a fresh context window. Structured enough that any capable AI coding assistant can resume without extended re-explanation.

CLAUDE.md + session handoffs: the complete picture

The two tools are complementary, not overlapping:

• CLAUDE.md handles project-level persistent context — architecture, conventions, commands, constraints. It is written by humans, updated alongside the codebase, and read by Claude Code at every session start.
• Session handoffs handle the dynamic state of in-progress work — what was being done, what decisions were made during the session, what the partial state is. They are generated automatically at the point of interruption and consumed by the next session.

The engineers who get the most consistent value from AI coding assistants have both: a maintained CLAUDE.md that reliably provides project context, and a handoff discipline that makes any interruption — context limit, end of day, tool switch — recoverable without starting over.

Most developers have the CLAUDE.md part and are still losing work to context limits. The handoff layer is the missing piece.