If you've used Claude Code for more than a few days, you've probably noticed something frustrating: the AI's behavior isn't consistent across sessions.
It might follow your code style perfectly on Tuesday, then completely ignore it on Thursday. You explained a constraint about "don't use Redux" in one session, and three sessions later it's suggesting Redux again.
The fix is a well-crafted CLAUDE.md — but most devs treat it as an afterthought. Here's the pattern that actually works.
What CLAUDE.md Actually Does
Claude Code reads CLAUDE.md automatically at the start of every session. Whatever you put in there becomes the AI's working context for that session.
This means it's your one guaranteed way to maintain consistency across sessions — without re-explaining yourself every time.
The Three-Layer Structure
The most effective CLAUDE.md files I've seen have three layers:
Layer 1: Project Identity (Never Changes)
# Project: AuthService
## What This Is
A standalone authentication microservice for [Company]. Handles user login, JWT issuance, refresh token rotation.
## Tech Stack
- Node.js + TypeScript (strict mode)
- Postgres (no ORM — raw SQL via `pg`)
- Redis for refresh token storage
- Express.js
## Deployment
- Docker containers on AWS ECS
- Staging: auth-staging.company.com
- Prod: auth.company.com
Layer 2: Constraints (Stable, But Occasionally Updated)
## Hard Rules
**Code style:**
- Functions under 30 lines — split if longer
- Explicit error types, never `throw new Error('generic message')`
- All SQL parameterized — no string interpolation
**Architecture:**
- No new dependencies without discussion first
- Auth logic stays in `/src/auth` — don't spread it
- Use existing `UserRepository` pattern for DB queries
**What to Avoid:**
- Prisma or any ORM (decided against, see DECISIONS.md)
- Any synchronous file operations
- Storing sensitive data in logs
Layer 3: Current Session Context (Updated Regularly)
## Current Focus
*Last updated: Feb 22, 2026*
Working on: Refresh token rotation implementation
Status:
- Core rotation logic: DONE (see `src/auth/refresh.ts`)
- Redis TTL handling: DONE
- Race condition guard: IN PROGRESS (file: `src/auth/refresh-guard.ts`)
- Tests: TODO
Key decisions made this week:
- Using sliding window for refresh token expiry (not fixed)
- NOT implementing token family tracking yet (deferred to v2)
Next step: Implement the atomic check-and-rotate in Redis using Lua script
Why This Structure Works
Layer 1 gives Claude instant understanding of the codebase without you explaining it. Saves 5-10 minutes per session.
Layer 2 is where most people underinvest. Constraints don't just prevent mistakes — they eliminate the AI's need to ask clarifying questions. "Should I use Prisma here?" becomes a non-question.
Layer 3 is the secret weapon. By updating current status before closing each session, you effectively give your next-session self a perfect briefing. The AI starts knowing exactly where you left off.
The Maintenance Habit
The system breaks down if Layer 3 gets stale. The habit that fixes this:
Before closing Claude Code, run:
Update the 'Current Focus' section of CLAUDE.md to reflect what we did and what's next.
Let the AI write the update. It takes 30 seconds and means your next session starts from accurate state.
Common Mistakes
Too long. If CLAUDE.md is 500+ lines, Claude has to process all of it before understanding what you want. Keep each section scannable.
Too generic. "Write clean code" is useless. "Functions under 30 lines, split if longer" is actionable.
Mixing project docs with session state. Project architecture doesn't change — current task status changes constantly. Keep them in separate sections (or even separate files linked from CLAUDE.md).
Never updating Layer 3. A CLAUDE.md that says "Current Focus: Authentication" when you're now working on payment processing is worse than nothing — it sends Claude in the wrong direction.
Template
# [Project Name]
## What This Is
[1-2 sentences]
## Tech Stack
[List the key technologies and versions]
## Hard Rules
[Non-negotiable constraints — code style, architecture decisions, what to avoid]
## Current Focus
*Last updated: [date]*
Working on: [current feature/bug]
Status: [what's done, what's in progress, what's next]
Key decisions: [anything decided recently that affects current work]
The Result
With a well-maintained CLAUDE.md, my sessions start in under 2 minutes instead of 15-20. The AI picks up exactly where I left off, respects constraints without reminders, and produces code that fits the existing patterns.
The investment: 5 minutes to write the initial file, 30 seconds at the end of each session to update Layer 3.
For teams working on larger projects where session state is more complex, tools like Mantra automate the snapshot/restore process — useful when you're managing multiple long-running AI sessions across different features.
But even without tooling, a good CLAUDE.md eliminates most of the friction from stateless AI sessions.
What's in your CLAUDE.md? I'm curious what constraints other devs have found worth encoding.
🛠️ How I Actually Solved This: Mantra
A solid CLAUDE.md gets you most of the way there. For the rest — especially the state that's too dynamic to encode in a file — Mantra handles three specific problems:
▶ Replay — Click any message in your session and the code returns to the exact Git state from that moment. The TimberLine scrubber works like a video timeline. When you pick up a session after days away, you don't reconstruct — you rewind.
⚙️ Control — One MCP gateway shared across Claude Code, Cursor, Gemini CLI, and Codex. Add a tool or integration once — every AI assistant you use picks it up automatically. Skills Hub manages the prompt patterns that belong across projects, complementing what your CLAUDE.md handles per-project.
🔒 Secure — A local Rust engine automatically detects API keys, passwords, and tokens in session history before you share it. One-click redaction. Nothing leaves your machine.
No cloud. No sign-up. Free. → mantra.gonewx.com
Top comments (0)