Learn Claude Skills
Guide

Crafting the Perfect CLAUDE.md

Structure, size, and maintain your project's CLAUDE.md memory file so Claude knows your project without wasting context.

~7 min read

The first impulse many teams have when adopting Claude Code is to dump their entire engineering wiki into CLAUDE.md. They paste 800 lines of API documentation, database schemas, coding philosophies, and meeting notes into a single file at the root of the repository.

Two weeks later, they wonder why Claude has gotten sluggish, why simple edits hallucinate, and why rules from line 650 are routinely ignored. The issue is not the model. The issue is context pollution.

CLAUDE.md is not an encyclopedia: it is an operational memory file. It is injected into every single conversation turn. If your CLAUDE.md is bloated, you pay a tax in tokens, speed, and model attention on every message you exchange.

What CLAUDE.md is, and what it is not

Understanding the boundaries of CLAUDE.md is the fundamental skill that separates disciplined operators from frustrated users:

  • It IS: A concise map of commands, architecture, non-obvious conventions, and known traps that cannot be deduced by reading the code alone.
  • It is NOT: An instruction manual for occasional tasks (that is what skills are for).
  • It is NOT: A security boundary or access control policy (that is what permissions and hooks are for).
  • It is NOT: A replacement for good code comments and clean repository structure.

The four essential sections of a high-signal CLAUDE.md

Over hundreds of hours benchmarking agent workflows in client repositories, I have found that the most effective CLAUDE.md files stay under 100 lines and organize around four specific sections:

You type: /init
Output: Scanning repository architecture and build tools...
Output: Detected: TypeScript, Fastify, Vitest, Prisma PostgreSQL.
Output: Wrote starting CLAUDE.md to project root (82 lines).
Note: Always open the generated file and trim verbose generic prose before committing.
Run /init to generate your starting project memory.
  1. Commands: The exact, copy-pasteable commands for building, testing, linting, and running migrations.
  2. Architecture: A brief index of directories and responsibilities so Claude does not have to wander through 50 files to find where business logic lives.
  3. Code conventions: Non-negotiable team rules (such as error handling patterns, naming schemas, or library choices).
  4. Gotchas: Known traps, forbidden functions, or historical quirks that routinely catch new contributors.
File: # Architecture & Directory Map
Output: Node.js service with Fastify and PostgreSQL via Prisma.
Output: src/routes/ HTTP handlers and Zod request/response validation schemas
Output: src/services/ Core business logic (controllers never call Prisma directly)
Output: src/db/ Prisma client, schema, and migration scripts
File: # Verification Commands
Command: npm test # Run Vitest test suite
Command: npm run lint # Check linter and formatting
Command: npm run db:migrate # Apply pending migrations locally
File: # Strict Conventions & Gotchas
Output: - All database timestamps must be stored as UTC in ISO-8601 format.
Output: - Never import raw express libraries; use Fastify plugins.
Output: - Do not modify files in src/db/migrations manually; run the migration script.
A clean, high-signal CLAUDE.md file for a modern backend service.

The dividing line: CLAUDE.md vs skills vs hooks

When you want Claude to follow a rule, ask yourself how frequently that rule applies:

  • Always applies across all code turns: Put it in CLAUDE.md (for example: "Always use Vitest, never Jest").
  • Applies only during a specific, repeatable workflow: Put it in a skill (for example: "How to draft a release note" or "How to conduct a security review"). Skills load on demand and consume zero tokens when not in use.
  • Must be enforced deterministically regardless of model compliance: Put it in a hook (for example: "Prevent editing .env files" or "Run prettier on save").

How CLAUDE.md interacts with auto-memory

Recent versions of Claude Code include an automatic memory system alongside CLAUDE.md. While CLAUDE.md is written and edited directly by you, auto-memory is managed by the model itself. When you correct Claude during a session (for example: "Remember to use bun instead of npm in this repo"), Claude records that preference in `~/.claude/projects/<project>/memory/MEMORY.md`.

You type: /memory
Output: Active Memory Sources:
Output: - ./CLAUDE.md (Project instructions, 54 lines)
Output: - ~/.claude/projects/my-app/memory/MEMORY.md (Auto-memory, 18 lines)
Note: CLAUDE.md provides the baseline team standard; auto-memory records personal corrections.
Inspect your active memory hierarchy during a session.

Review `/memory` periodically. If auto-memory captures a team-wide standard, graduate that rule into CLAUDE.md so every developer benefits from it, then clear the duplicate from auto-memory.

Stay updated

Get new guides in your inbox

One task, one guide, done fast. Practical Claude Code skills, zero noise.

Keep learning

Related guides and paths

Claude Code Slash Commands for Beginners

This guide covers the slash commands that matter on day one, grouped by job. It also covers what command lists skip: your own skills are invokable as /name.

  • ~7 min