Claude Code CLAUDE.md: the one file that makes your AI sessions 10x more consistent

If you've been using Claude Code for more than a week, you've noticed the inconsistency problem.

Monday: Claude remembers your project structure, follows your coding conventions, knows you prefer TypeScript strict mode.

Friday: Same project, new session. Claude suggests JavaScript. Proposes a pattern you explicitly banned. Forgets your testing framework.

The problem isn't Claude's memory. It's that you're not giving it one.

What CLAUDE.md actually is

CLAUDE.md is a markdown file you place at the root of your project. Claude Code reads it automatically at the start of every session.

It's not magic. It's just a file that gets prepended to your context window. But that simple mechanic makes it the highest-ROI thing you can do for consistent Claude Code sessions.

# Create it
touch CLAUDE.md

Now Claude will read it every time you open Claude Code in that directory.

The 5 sections every CLAUDE.md needs

1. Project overview (3-5 lines max)

# Project: PaymentService

Node.js microservice handling Stripe webhooks and subscription state.
Part of a larger monorepo. This service owns the `payments` database schema.
Do NOT modify anything outside /src/payments/.

This single section eliminates the biggest source of Claude drift: not knowing where the boundaries are.

2. Tech stack (explicit versions)

## Stack
- Node.js 20.x (NOT 18.x)
- TypeScript 5.4 with strict mode
- Prisma 5.x for database (NOT raw SQL)
- Jest for testing (NOT Vitest)
- pnpm (NOT npm or yarn)

Be explicit. Claude has trained on millions of codebases and will default to whatever it saw most often. Your constraints override that.

3. Coding conventions

## Conventions
- Always use async/await, never .then() chains
- Error handling: always use Result<T, E> pattern, never throw
- All database calls go through /src/db/client.ts - never import Prisma directly
- Functions max 30 lines. If longer, break into helpers.
- No comments that explain WHAT the code does. Comments explain WHY.

This is where you encode your team's decisions. These are the rules that new developers take weeks to learn. Claude learns them in one file read.

4. What NOT to do

## Do NOT
- Do NOT add console.log for debugging (use the logger utility)
- Do NOT modify /src/legacy/ - this is frozen code
- Do NOT install new packages without asking first
- Do NOT use `any` type in TypeScript
- Do NOT add TODO comments - if it needs doing, do it now or create a GitHub issue

Negative constraints are often more important than positive ones. Claude is optimistic by default — it will add logging, install packages, and use any when it seems convenient. Explicit prohibitions stop this.

5. Current context (update frequently)

## Current focus
Migrating from Stripe v2 webhooks to v3. Reference: /docs/stripe-v3-migration.md
Known issue: webhook deduplication is broken in production. Fix is in PR #447.
Do NOT touch the deduplication code until PR #447 is merged.

This section changes week to week. It's where you put the "situational awareness" that would take 10 minutes to explain in every session.

Real example: before and after

Without CLAUDE.md:

You: Add error handling to this payment webhook
Claude: Here's the updated function. I added a try/catch and console.error for debugging, and used Promise.then() for the async chain.

Three violations in one response.

With CLAUDE.md:

You: Add error handling to this payment webhook

Claude: Here's the updated function using the Result pattern. I'm using your logger utility for errors. Note: I avoided modifying the deduplication logic since you mentioned PR #447 is pending.

Claude is now working with your context instead of against it.

Advanced: nested CLAUDE.md files

Claude Code respects CLAUDE.md files at multiple levels:

your-project/
├── CLAUDE.md          # Global project rules
├── src/
│   ├── payments/
│   │   └── CLAUDE.md  # Payment-specific rules
│   └── auth/
│       └── CLAUDE.md  # Auth-specific rules

The nested file adds context when you're working in that subdirectory. Global rules still apply.

Useful for monorepos where different packages have different conventions.

The rate limit problem with long CLAUDE.md files

Here's the tradeoff: every line in CLAUDE.md costs tokens. In every session. Forever.

A 500-line CLAUDE.md will eat through your context window faster. Long sessions will hit limits sooner.

The solution is to keep CLAUDE.md focused: project structure, non-negotiable conventions, current blockers. Move detailed documentation to separate files that you reference in CLAUDE.md:

## Architecture
See /docs/architecture.md for the full system diagram.
Key constraint: all external API calls go through /src/gateway/ — never directly.

If you're hitting token limits and rate limits frequently despite this optimization, there's a practical workaround: use ANTHROPIC_BASE_URL to point to a service like SimplyLouie that provides the same Claude API at a much lower monthly cost. At ���️$2/month it makes running longer sessions daily economically sustainable.

Template you can use today

# Project: [NAME]

[2-3 sentence description of what this does and what it owns]

## Stack
- [Runtime + version]
- [Language + version]
- [Key frameworks + versions]
- [Test framework]
- [Package manager]

## Conventions
- [Async pattern]
- [Error handling pattern]
- [File organization rule]
- [Naming conventions]

## Do NOT
- [Most common mistake #1]
- [Most common mistake #2]
- [Frozen files/directories]

## Current focus
[What's happening this week. Update every Monday.]
[Active PRs that Claude should know about]
[Known issues Claude should avoid touching]

Copy this. Fill it in for your project. Commit it. Your sessions will be immediately more consistent.

One more thing

CLAUDE.md is also useful for onboarding human developers. New teammate? They can read your CLAUDE.md and get the same situational awareness Claude gets. It forces you to write down the unwritten rules.

Document for the AI. Get human-readable docs for free.

---

If you're spending too much on Claude subscriptions, SimplyLouie offers the same API at ✌️$2/month — useful for teams running multiple Claude Code sessions daily.