Claude Code project memory: how I use CLAUDE.md to onboard Claude to any codebase instantly

Every time you start a new Claude Code session, Claude knows nothing about your project.

No memory of the last session. No idea where your config lives. No understanding of your conventions.

You spend the first 10 minutes re-explaining everything before you can do any real work.

There's a fix. It's called CLAUDE.md.

What CLAUDE.md actually does

When Claude Code starts, it automatically reads any CLAUDE.md file in your project root. Everything in that file becomes part of Claude's working context for the entire session.

No prompting required. No re-explaining. Claude just knows.

# Claude reads this file automatically on startup
cat CLAUDE.md

Think of it as a README — but written for Claude, not for humans.

The CLAUDE.md template I use on every project

# Project: [your project name]

## What this is
[One paragraph describing what the app does and who uses it]

## Tech stack
- Runtime: Node.js 20
- Framework: Express 4.x
- Database: PostgreSQL via pg
- Auth: JWT (jsonwebtoken)
- Tests: Jest + supertest

## Project structure

src/
routes/ # Express route handlers
models/ # Database queries
middleware/ # Auth, validation, logging
utils/ # Shared helpers
public/ # Static assets
tests/ # Jest test files

## How to run things
- Dev server: `npm run dev` (nodemon, port 3000)
- Tests: `npm test` (Jest)
- Lint: `npm run lint` (ESLint)
- Deploy: `./deploy.sh` (PM2 restart)

## Conventions
- Use async/await, never callbacks
- All DB calls go through models/, not inline in routes
- Environment variables in .env (never hardcode)
- Test files mirror source: src/routes/auth.js → tests/routes/auth.test.js

## What to avoid
- Don't use require() — we use ES modules
- Don't write raw SQL — use our query helpers in models/db.js
- Don't modify the auth middleware without running the full auth test suite

## Current focus
[What you're working on right now — update this regularly]

The "current focus" section is the most important part

The last section — ## Current focus — is the one I update every time I switch tasks.

Example:

## Current focus
Building the CSV export feature for the admin dashboard.
The export endpoint will live at GET /api/admin/export.
Status: schema done, need to write the query and route handler.

When I start a new session, Claude immediately knows:

• What I'm building
• Where it lives in the codebase
• What's done and what's left

No context dump. No re-explaining. Just: "continue where we left off."

Nested CLAUDE.md for complex projects

For larger codebases, you can put CLAUDE.md files in subdirectories. Claude reads them when working in that directory.

/CLAUDE.md                    # Project overview, conventions
/src/routes/CLAUDE.md         # Route-specific patterns
/src/models/CLAUDE.md         # Database patterns, query conventions
/tests/CLAUDE.md              # Test conventions, fixtures

This keeps context focused. When Claude is editing a route file, it reads the routes-specific CLAUDE.md with route-level context — not the entire project overview.

What goes in CLAUDE.md vs settings.json

People confuse these two files. They do different things.

	CLAUDE.md	settings.json
Purpose	What Claude should know	What Claude is allowed to do
Controls	Context and conventions	Permissions and tools
Example	"We use async/await"	allowedTools: ["Bash", "Read"]

CLAUDE.md is the brain — knowledge about your project.
settings.json is the fence — what Claude can and can't touch.

You need both. They're not interchangeable.

Live example: 5-minute CLAUDE.md setup

Here's exactly what I do when starting a new project with Claude Code:

# 1. Create CLAUDE.md in project root
touch CLAUDE.md

# 2. Add project overview (takes 3 minutes)
cat > CLAUDE.md << 'EOF'
# Project: my-saas-app

## What this is
A subscription SaaS for small teams. Users sign up, get a 7-day trial, then pay monthly.

## Tech stack
- Node.js + Express
- PostgreSQL
- Stripe for billing
- JWT auth

## How to run
- Dev: npm run dev
- Test: npm test
- Deploy: pm2 restart all

## Conventions
- Async/await only
- Models in src/models/
- Tests in tests/

## Current focus
Building the team invite flow.
EOF

# 3. Start Claude Code — it reads CLAUDE.md automatically
claude

Now say: "continue with the team invite flow" — and Claude picks up immediately.

The rate limit problem with long CLAUDE.md files

Here's a real issue: if your CLAUDE.md gets very detailed (1000+ lines), it eats into your context window on every session. Claude's context fills up faster, sessions get interrupted earlier, and you hit rate limits more often.

Two solutions:

Option 1: Keep CLAUDE.md lean. Include only conventions and current focus. Don't put entire design docs in there.

Option 2: Use a proxy that removes rate limits. If you're hitting rate limits mid-session because your CLAUDE.md + project files are filling context, you can route Claude Code through a Claude-compatible API that handles the rate limiting for you.

# Route Claude Code through a rate-limit-free endpoint
export ANTHROPIC_BASE_URL=https://api.simplylouie.com
claude

SimplyLouie runs for ✌️2/month and gives you uninterrupted sessions even with large CLAUDE.md files. simplylouie.com

Summary

CLAUDE.md solves the session memory problem. Without it, every Claude Code session starts from zero. With it, Claude walks into your codebase already knowing what it is, how it works, and what you're building next.

Create the file. Fill in the template. Update the ## Current focus section every time you switch tasks.

Five minutes of setup. Permanent productivity gain.