CLAUDE.md Setup Guide: How to Customize Claude Code for Your Project (2026)

If you've used Claude Code for more than a few days, you've probably noticed that you keep explaining the same things: "We use TypeScript strict mode," "Don't write comments," "Our API base URL is..."

Every session starts fresh. Every session costs you tokens re-establishing context.

CLAUDE.md fixes this. It's a file that Claude Code reads automatically at the start of every session — giving Claude persistent knowledge about your project, your preferences, and your rules. It's the difference between a junior dev who forgets everything overnight and a senior engineer who shows up knowing exactly how this codebase works.

Here's how to set it up right.

What Is CLAUDE.md?

CLAUDE.md is a Markdown file placed in your project root (or ~/.claude/CLAUDE.md for global settings). Claude Code reads it automatically at the start of each session, before you type a single message.

It's not a config file in the traditional sense — it's a briefing document for your AI pair programmer. Everything you'd tell a new dev on their first day: architecture decisions, coding conventions, what to avoid, what's already been tried.

The name isn't a convention — Claude Code explicitly looks for it by name.

Where to Put CLAUDE.md Files

You can have multiple CLAUDE.md files, each with different scope:

~/.claude/CLAUDE.md          # Global — applies to every project
~/project/CLAUDE.md          # Project root — applies to this project
~/project/src/CLAUDE.md      # Directory — applies when working in src/

Claude Code merges them in order: global first, then project, then directory-specific. More specific files can override or extend global settings.

Start with project-level. You can always add global later once you know what belongs everywhere.

The Anatomy of a Good CLAUDE.md

A CLAUDE.md file isn't documentation — it's instructions. Every line should either tell Claude what to do or what not to do.

Here's a battle-tested structure:

# Project: [Name]

## Tech Stack
- Python 3.12 + FastAPI
- PostgreSQL (not SQLite — never SQLite in production)
- Pydantic v2 for all data models
- Alembic for migrations

## Critical Rules
- NEVER hardcode credentials. Read from env vars only.
- NEVER use `SELECT *` in SQL queries. Always name columns.
- ALWAYS run `make test` before confirming a fix is complete.

## Architecture
The API lives in `src/api/`. Database models in `src/models/`.
Migrations in `alembic/versions/`. Config in `src/config.py`.

## Code Style
- No comments unless explaining WHY (not WHAT)
- Type hints on every function
- Black formatting, line length 88

## What We've Already Tried
- Redis caching for user sessions — caused cache invalidation bugs, removed 2025-08.
- Celery for background jobs — replaced with PostgreSQL-backed queue (simpler).

Five sections: stack, rules, architecture, style, and "don't go there again." That last one saves enormous time — stopping Claude from re-suggesting approaches you've already rejected.

The Global CLAUDE.md: Your Personal AI Rules

The global ~/.claude/CLAUDE.md is for preferences that follow you across every project. This is where you put things that are you, not your project:

# My Claude Code Preferences

## Communication Style
- Be concise. No preamble, no "Great question!"
- No trailing summaries like "In summary, I..."
- If you're uncertain, say so directly.

## Code Style (my defaults)
- No docstrings unless I ask
- Prefer functions over classes when state isn't needed
- Tests go in tests/ directory, named test_<module>.py

## Things I Always Want
- When fixing a bug: find the root cause, not just the symptom
- When I ask "why is this slow": profile before guessing
- Git commits: `[type] brief description` format

## Things I Never Want
- "I'll help you with that!" acknowledgements
- Suggesting rewrites when I asked for a small fix
- Creating new files when editing an existing one works

This is the configuration most developers skip — and it's where the biggest quality-of-life improvements come from.

Advanced: Dynamic Instructions with .claude/rules/

For large projects, one CLAUDE.md can get unwieldy. Claude Code also loads files from the .claude/rules/ directory, letting you split concerns:

.claude/
  rules/
    coding-standards.md    # How we write code
    security.md            # What never to do with secrets
    testing.md             # Our test philosophy
    architecture.md        # System design decisions

Claude Code reads all files in .claude/rules/ automatically. You can keep CLAUDE.md as a high-level overview and put the detailed rules in their own files where they're easier to maintain.

This works especially well for teams — different people can own different rule files, and PRs touching security.md get extra scrutiny because everyone knows what that file controls.

Common Mistakes (and How to Fix Them)

Mistake 1: Writing descriptions instead of instructions

Bad:

## Testing
We use pytest for testing. Tests are important and should be comprehensive.

Good:

## Testing
- Run `pytest tests/ -v` to run all tests
- ALWAYS write a test for any new function
- Tests live in `tests/` matching `test_<module>.py` naming
- Use `pytest-mock` for mocking — never monkeypatching

One tells Claude about your testing. The other tells Claude how to behave.

Mistake 2: Vague rules that Claude has to interpret

Bad: "Be careful with the database"
Good: "NEVER run migrations in production without a backup confirmation step"

Specificity is what makes rules actually fire.

Mistake 3: Documenting the current state instead of the target behavior

Your CLAUDE.md isn't a README. Don't describe what the code does — describe what Claude should do. If you're documenting current architecture just for context, keep it short. If you're writing rules, make them imperative.

Mistake 4: Never updating it

CLAUDE.md has a half-life. The tech decisions from last year may not be right today. The "don't do X" rule should note why, so you can evaluate whether that reason still applies. Review it whenever you make a significant architectural decision.

What Belongs in CLAUDE.md vs Git History

CLAUDE.md is for persistent operational knowledge — things Claude needs in every session:
- ✅ Coding standards and preferences
- ✅ Architecture decisions and why
- ✅ What NOT to do (failed approaches)
- ✅ Critical paths and entry points
- ✅ Security constraints

It's NOT a changelog or design document:
- ❌ "In February we migrated from X to Y" (history belongs in git)
- ❌ Complete API documentation (that belongs in docs)
- ❌ Step-by-step deployment guides (use a runbook)

The test: "If Claude needed to know this to do good work tomorrow, does it belong here?" If yes, put it in. If no, keep it out.

A Real-World Example: The Minimal Effective CLAUDE.md

Here's a CLAUDE.md for a typical SaaS project that actually gets used (based on what we've refined running an AI-first company for 9 months):

# SpockyAI Backend

## Stack
- Python 3.12, FastAPI, PostgreSQL
- SQLAlchemy 2.0 (async) + Alembic
- Redis for rate limiting only (not for caching sessions)

## Rules
- Read all env vars from `.env` via `python-dotenv`. NEVER hardcode.
- Async all the way — no sync DB calls in async routes
- Each endpoint needs a test in `tests/api/`
- Run `make check` (lint + type check + tests) before calling anything done

## Files to Know
- `src/config.py` — all settings loaded here
- `src/database.py` — DB session management
- `src/api/v1/` — all route handlers

## Don't Suggest
- Switching to Django (decision made, won't be revisited)
- Adding Redis caching for DB queries (premature optimization at our scale)

Forty lines. Gives Claude everything it needs to work on this codebase without needing briefing.

Measuring If It's Working

A good CLAUDE.md should reduce the number of times per session you have to correct Claude's output. If you find yourself still saying "no, we don't do it that way" more than once per session, something belongs in your CLAUDE.md.

Track what you correct. After two weeks, you'll have a list of exactly what to add.

What's Next

CLAUDE.md is the foundation — but it's just the beginning of what's possible when you build your workflow around Claude Code properly. The deeper layer is hooks (.claude/hooks/ — scripts that run automatically on file saves, test failures, or commits), custom agents for different tasks, and integrating Claude Code into your CI pipeline.

If you want to go from "using Claude Code" to "building with Claude Code as infrastructure," that's exactly what we're covering in the Claude Code Mastery course.

→ Join the waitlist at agentic-movers.com/courses/claude-code-mastery/ — we're in early-access signups now.

Building an AI-first company in public. Follow Spocky on Instagram for the unfiltered version.