CLAUDE.md is Claude Code's primary memory mechanism — the file that tells the AI what it needs to know about your project before writing a single line of code. A well-written CLAUDE.md makes Claude noticeably more useful. A bloated or poorly structured one gives the AI contradictory or outdated information.

This guide covers what to include, what to leave out, and which part of the job belongs to a memory the agent writes for itself rather than to a file you write by hand.

What is CLAUDE.md and how does it work?

When Claude Code starts a session in your project, it automatically reads any CLAUDE.md file it finds in the working directory or parent directories. This file is included in the context window on every conversation — so everything in it costs tokens on every session, whether it's relevant or not.

Claude Code respects nested CLAUDE.md files: a backend/CLAUDE.md is read when working in the backend folder, a root CLAUDE.md is always read. This lets you keep global rules at the root and service-specific rules closer to the code.

What to write in your CLAUDE.md

1. Project overview (2-4 sentences max)

State what the project is, what stack it uses, and what it does. Claude doesn't need your entire architecture document — just enough to avoid category errors.

# MyApp — FastAPI backend + React frontend
# Auth: JWT sessions, bcrypt passwords. DB: PostgreSQL via SQLAlchemy.
# Deployments: Docker containers on DigitalOcean. Staging at staging.myapp.io.

2. Coding conventions that aren't obvious from the code

Document things the AI can't infer by reading the files: preferred patterns, forbidden anti-patterns, house style decisions.

# CONVENTIONS
# - Always use async/await, never sync DB calls
# - No raw SQL — always use SQLAlchemy ORM
# - Error responses: {"error": "message"}, never expose stack traces
# - Tests must use real DB (no mocks), fixtures in tests/conftest.py

3. Entry points and key files

Name the files that matter most. This saves the AI from reading your entire file tree looking for where things start.

# KEY FILES
# backend/app.py — FastAPI app factory
# backend/auth/router.py — all auth endpoints
# backend/models/user.py — User model
# frontend/src/App.tsx — React root

4. Things the AI must never do

Hard constraints. These are the most important things to put in CLAUDE.md because they prevent costly mistakes.

# NEVER
# - Drop or truncate any database table
# - Skip migrations — always use alembic
# - Commit to main directly
# - Use print() for logging — use the logger module

5. Current session goals (optional, update frequently)

Some developers add a "current focus" section that they update each sprint. This works well, but keep it short — outdated context is worse than no context.

What to leave out of your CLAUDE.md

Include
  • Rules and constraints (what never to do)
  • Non-obvious conventions
  • Entry point file paths
  • Stack and deployment basics
  • Security-critical reminders
Don't include
  • Full API documentation
  • Detailed architecture diagrams in text
  • Information that changes weekly
  • Things the AI can find by reading the code
  • Anything over ~300 lines total

The biggest mistake is writing a CLAUDE.md that describes what the code already says. If the AI can read auth/router.py and see that you use JWT, you don't need to tell it that in CLAUDE.md. Claude Code finds it with grep, precisely and fast — a line that repeats it only goes stale.

The context cost of CLAUDE.md

The whole file is read at the start of every session, relevant or not. A long one does not break anything, but every line is a chance to be out of date, and out-of-date instructions are worse than none. Trim it and keep it current.

What does not belong in CLAUDE.md: the agent's own memory

The fundamental limitation of CLAUDE.md is that a person writes it. The knowledge that gets lost between sessions — where the work stopped, what was tried and dropped, the trap in the Redis TTL, why sessions stay out of JWT — is knowledge the agent had, and a person rarely writes it down in its terms.

With Codelux AI the agent writes that part itself, as a memory in free JSON (memory_set): summary, next step, open points, traps, decisions, facts anchored to a file and line, a map of the code it touched. A hook puts it back in context at the next session start, and Codelux AI keeps a block up to date in AGENTS.md and, if it exists, CLAUDE.md:

<!-- codelux:start -->
Status: Auth.Session — done: refresh-token race fixed
Next: logout must revoke the refresh token
Traps: Redis TTL is in ms, not s
Decisions: sessions stay in Redis, not JWT (2026-09-27)
<!-- codelux:end -->

Sixty lines at most, rewritten on every save, nothing outside the markers touched. What remains for you to write in CLAUDE.md are the constraints and conventions that cannot be inferred from the code or from the work — and that part stays short.

A minimal CLAUDE.md template

# Project: [Name]
# Stack: [language/framework/db/deploy in one line]

# CONVENTIONS
# [3-5 non-obvious rules, one line each]

# NEVER
# [3-5 hard constraints]

# ENTRY POINTS
# [main.py / app.ts / index.go — 3-5 lines max]

<!-- codelux:start -->
[status, next step, traps, decisions — written by Codelux AI, do not edit]
<!-- codelux:end -->

Keep your part under 50 lines. Every section should answer a question the AI cannot answer by looking at your code or at its own memory.

Let the agent write the part you never would

Codelux AI gives Claude Code a memory it writes for itself, a block it keeps up to date in CLAUDE.md, and a timeline of everything that happens — so your CLAUDE.md stays small and current.

Try Free — no time limit →

← Back to the blog  |  Next: What is an MCP server? →