How to write a CLAUDE.md file that actually makes Claude Code useful

Claude Code reads one file before it does anything else: your CLAUDE.md. This file sits in your project root and tells Claude how to behave in your specific codebase. What conventions to follow. What tools to use. What mistakes to avoid.

Most developers either skip this file entirely or write a few generic lines that add nothing. Both approaches waste the most powerful configuration option Claude Code offers.

After running Claude Code as the operational layer of a real business for over 30 days, here is what actually works in a CLAUDE.md file and what is just noise.

What CLAUDE.md does under the hood

When you start a Claude Code session, the first thing it does is look for CLAUDE.md files. It checks three locations in order:

1. ~/.claude/CLAUDE.md - Your personal global instructions. Apply to every project.
2. Your project root CLAUDE.md - Project-specific instructions. This is the one that matters most.
3. Any .claude/rules/*.md files - Additional rules files for organizing large instruction sets.

Claude loads all of these into its context window before your first message. They act as system-level instructions that shape every response, every edit, every terminal command Claude runs during the session.

This means two things. First, your CLAUDE.md is extremely powerful because Claude treats it as authoritative instructions. Second, every line costs tokens. A 500-line CLAUDE.md that is mostly filler actively hurts you by consuming context that could go toward understanding your actual code.

The structure that works

After iterating through dozens of versions, here is the structure that consistently produces good results:

1. Identity and context (3-5 lines)

Tell Claude what the project is and who it is working for. This is not documentation. It is calibration.

# My Project - System Instructions

You are working on [Project Name], a [type of project] built with [stack].
The primary user is [role]. The codebase prioritizes [key value: speed, safety, simplicity].

Why this matters: Claude makes thousands of micro-decisions during a session. Should it add error handling or keep it simple? Should it use a class or a function? These decisions should align with your project's values, and this section calibrates that.

2. Architecture overview (10-15 lines)

Not a complete architecture document. Just enough that Claude knows where things live.

## Architecture
- Frontend: React + TypeScript in src/components/
- API: Express routes in src/api/
- Database: PostgreSQL, migrations in db/migrations/
- Tests: Jest, co-located with source files as *.test.ts
- Config: Environment variables in .env (never commit this)

The goal is to prevent Claude from guessing. Without this section, Claude will explore your filesystem to figure out the structure, burning tokens and sometimes getting it wrong. With it, Claude goes straight to the right directory.

3. Hard rules (5-10 lines)

These are the things Claude must always or never do. Write them as commands, not suggestions.

## Rules
- NEVER delete files. Move to .trash/ instead.
- NEVER push to main without confirmation.
- Always run tests before committing.
- Use snake_case for Python, camelCase for TypeScript.
- Do not add comments unless the logic is non-obvious.

This is the highest-value section. Every rule here prevents a class of mistakes permanently. One line like "NEVER delete files" saves you from the moment Claude decides to clean up by removing something important.

4. Workflow patterns (5-10 lines)

How you want Claude to approach common tasks. Not every possible task, just the recurring ones where Claude's default behavior does not match your preference.

## Workflows
- Before editing a file, always read it first.
- When fixing a bug, write a failing test first, then fix.
- For new features, check if a similar pattern exists before creating new abstractions.
- Prefer editing existing files over creating new ones.

5. External systems (only if relevant)

If Claude interacts with APIs, deployment tools, or external services, document the connection points. Skip this section if your project is self-contained.

What to leave out

Knowing what not to include is as important as knowing what to include. These are common CLAUDE.md mistakes:

• Obvious conventions. You do not need to tell Claude to use proper indentation or write valid syntax. It already does this.
• Full API documentation. Claude can read your source code. Do not paste API specs into CLAUDE.md. Point to the file instead.
• History and changelogs. CLAUDE.md is for instructions, not a journal. Keep historical context in git commits or separate docs.
• Aspirational rules you do not enforce. If you write "always write unit tests" but you do not actually run tests, Claude will follow the rule and you will spend sessions debugging test failures for code that never needed tests.
• Duplicate information. If your README already explains the project structure, do not copy it into CLAUDE.md. Reference it: "Read README.md for project setup details."

Advanced patterns

Rules files for organization

If your CLAUDE.md grows past 100 lines, split rules into separate files under .claude/rules/. Each file is a focused set of instructions for a specific domain:

.claude/
  rules/
    guardrails.md      # Safety rules
    testing.md         # How to write and run tests
    deployment.md      # Deploy procedures
    code-style.md      # Formatting and naming conventions

Claude loads all of these automatically. This keeps your root CLAUDE.md clean and focused on the big picture while rules files handle the details.

Tiered context loading

For larger projects, tell Claude to load context on demand rather than reading everything upfront:

## Context Loading
- Read context/INDEX.md first to determine which files are relevant.
- Load only the files needed for the current task.
- Never load all context files at once.

This pattern can cut token usage by 40-60% in projects with extensive documentation or configuration.

Model routing

If you use Claude Code with API billing, you can route different types of work to different models:

## Model Routing
- Use Haiku for simple file searches and formatting tasks.
- Use Sonnet for code generation and refactoring.
- Use Opus for architecture decisions and complex debugging.

A real example

Here is a condensed version of a CLAUDE.md that runs a production business. This is not a template to copy. It is a reference for the kind of specificity that makes Claude Code genuinely useful:

# Project - System Handbook

## Identity
You are the operational AI for a SaaS business. You make decisions and execute.

## Architecture
- Skills (.claude/skills/) - Workflow packages with scripts
- Context (context/) - Domain knowledge, voice guide, ICP
- Data (data/) - SQLite databases for persistence
- Args (args/) - Runtime configuration (YAML)

## Rules
- NEVER use rm. Move to .trash/ instead.
- Never send external communications without confirmation.
- Never commit .env files.
- Check existing scripts before writing new ones.
- When uncertain about intent, ask rather than guess.

## How to Operate
1. Find the skill first. Check .claude/skills/ before starting any task.
2. No skill? Create one if the task is repeatable.
3. Apply args before running. Read args/ files for runtime behavior.
4. Log decisions to daily log: memory/logs/YYYY-MM-DD.md

Notice what is not here: no long explanations, no obvious rules, no history. Every line either prevents a mistake or directs Claude to the right place.

Measuring if your CLAUDE.md works

A good CLAUDE.md reduces three things:

1. Corrections per session. If you constantly tell Claude "no, not like that," your CLAUDE.md is missing a rule.
2. Exploration time. If Claude spends the first minute of every session reading random files to understand the project, your architecture section is too thin.
3. Token waste. If sessions are expensive because Claude loads too much context, your CLAUDE.md might be too long or missing a tiered loading instruction.

Track these informally. When you notice a recurring correction, add it as a rule. When Claude consistently goes to the wrong directory, update the architecture section. Your CLAUDE.md should evolve with your project.

Getting started

If you do not have a CLAUDE.md yet, start with this minimal version:

# [Project Name]

## Stack
[One line describing your tech stack]

## Structure
[3-5 lines showing where things live]

## Rules
- [Your biggest recurring frustration with Claude, stated as a rule]
- [Your second biggest frustration]
- [One safety rule about destructive operations]

Three rules are better than zero. You can always add more as patterns emerge. The important thing is having the file at all, because without it Claude Code starts every session blind.

If you want a complete, production-tested CLAUDE.md template along with the full skill system, memory architecture, and workflow automation that goes with it, the AI OS Blueprint includes everything we use to run this business. Tested in production. Not theoretical.

And if you are finding that Claude Code costs more than you expected, our free cost analyzer shows exactly where your tokens go. Upload a session log and see the breakdown in seconds.