How to Write an Effective CLAUDE.md for Claude Code (Even If You’ve Only Used It 2½ Years)

Many developers start using Claude Code or similar AI coding assistants, but they often encounter bugs or unwanted changes because the AI lacks sufficient project context; each new session begins with a blank slate.

What is CLAUDE.md? It is a Markdown file placed in the project root that Claude Code automatically reads at the start of every session, treating it as an "onboarding manual" that describes the tech stack, build commands, code style, and project‑specific conventions.

AGENTS.md is an open‑standard file used by most AI coding tools (Claude Code, Cursor, etc.). By adding @AGENTS.md inside CLAUDE.md you can import the same rules across tools.

Why write a good CLAUDE.md? A well‑crafted file reduces repeated communication, enforces consistent code style, and lowers error rates. For example, specifying a unified API response format { success, data, error } prevents the AI from generating inconsistent responses.

How to write it effectively:

Keep the file under 200 lines (the AI’s context window is limited; studies show compliance drops after ~150‑200 directives).

Include only information the AI cannot infer from the code, such as custom build commands, team Git conventions, architecture decisions, required environment variables, and common pitfalls.

Avoid items the AI can read directly (e.g., generic language rules or full API docs).

Use positive directives instead of negations (e.g., "✅ Use functional components and Hooks" rather than "❌ Do not use class components").

Make each rule specific and verifiable (e.g., "✅ Use 2‑space indentation" or "✅ Run npm test before committing").

Leverage Hooks for actions that must be enforced (e.g., auto‑run ESLint after file edits).

For large projects, split rules into .claude/rules/ files with YAML front‑matter to limit scope to specific paths.

Use progressive disclosure with @import (e.g., reference @docs/api-architecture.md only when editing API endpoints).

Keep the file alive: update it whenever the AI makes a mistake, and use the /memory command to view auto‑saved notes.

Quick creation methods:

Run the /init command in Claude Code to auto‑generate a baseline CLAUDE.md based on the repository, then manually refine it.

Let the AI summarize a completed conversation and turn the summary into rules.

Reference open‑source examples from the awesome-claude-md and awesome-claude-code GitHub repositories.

Multi‑level configuration: CLAUDE.md can exist at four scopes—organization ( /etc/claude/CLAUDE.md), user ( ~/.claude/CLAUDE.md), project ( ./CLAUDE.md), and local ( ./CLAUDE.local.md)—with priority local > project > user > organization.

Team collaboration: Store the project‑level CLAUDE.md in Git, update it after code reviews, and let the team share conventions. Important rules should always be persisted in the file rather than spoken in a transient chat.

Troubleshooting: If rules are ignored, check that the file is loaded ( /memory), ensure directives are specific, resolve any contradictory rules, and move mandatory actions to Hooks.

In summary, CLAUDE.md is a concise, AI‑focused project handbook; start with the most critical 20 lines and iteratively expand it to improve AI assistance dramatically.