CLAUDE.md: The Complete Guide to Claude Code's Most Important File

73% of engineering teams now use AI coding tools daily. Yet most Claude Code users skip the one file that turns every session from a cold start into an informed conversation. That file is CLAUDE.md. And if you are not maintaining it, you are onboarding your AI pair programmer from scratch every single time.

CLAUDE.md is a markdown file that Claude Code reads at the start of every conversation. It lives in the root of your repository and acts as persistent memory for your project. Your architecture decisions, naming conventions, build commands, testing preferences, and workflow constraints all go here.

Without it, Claude has zero knowledge of your codebase when a session begins. It does not know your stack. It does not know your conventions. It does not know which branch strategy your team follows. Every session is a blank slate.

With it, every session starts informed.

The /init command was upgraded in March 2026 to do more than scan files. It now asks questions about your workflow, suggests skills that could become slash commands, and recommends hooks for operations that should be blocked. Run /init once and you get a solid starting point. Then refine it by hand over the next few sessions.

Most engineers drop one file in the project root and stop there. But CLAUDE.md supports three scopes, and understanding them changes how you configure everything.

ScopeLocationShared via Git?Use CaseUser~/.claude/CLAUDE.mdNoPersonal preferences across all projectsProject./CLAUDE.mdYesTeam standards and project contextDirectory./src/api/CLAUDE.mdYesModule specific conventions (monorepos)

The load order is Global, then Project, then Directory. More specific files take priority. This means your team can set project defaults while individual developers override them locally without affecting anyone else.

For monorepos, directory scoping is a game changer. Your frontend folder gets React conventions. Your API folder gets Express conventions. Your infra folder gets Terraform conventions. None of them leak into each other.

The biggest mistake engineers make with CLAUDE.md is writing too much. Research from HumanLayer found that frontier models can reliably follow about 150 to 200 instructions. Claude Code’s own system prompt already consumes roughly 50 of those. That leaves you with around 100 to 150 instructions before quality starts dropping.

The golden rule: keep your CLAUDE.md under 200 lines.

Here is what earns its place in the file:

Build, test, and lint commands are the single most valuable content. Claude needs to know how to verify its own work. Things like npm run test, make build, and npx eslint . should be right at the top.

Architecture decisions that Claude cannot infer from code alone come next. “We use a monorepo with Turborepo.” “All API endpoints must have rate limiting.” “TypeScript strict mode is on.”

Non obvious gotchas and naming conventions round it out. Import paths, error handling patterns, environment variable sources, and anything where Claude would otherwise guess wrong.

Here is what does NOT belong:

Code style rules that a linter can enforce. Never send an LLM to do a linter’s job. LLMs are expensive and slow compared to Prettier or ESLint. Instead, set up a PostToolUse hook that runs your formatter every time Claude writes a file.

Here is a template that works for a typical TypeScript project. Adapt it to your stack.

# ProjectTask management API built with Node.js, TypeScript, and PostgreSQL.

# Commands- npm run dev: Start development server- npm run build: Production build- npm test: Run Jest test suite (use single tests, not the full suite)- npm run lint: ESLint + Prettier check

# Architecture- src/routes: Express route handlers- src/services: Business logic (no direct DB calls from routes)- src/db: Prisma schema and migrations- src/types: Shared TypeScript interfaces

# Conventions- Named exports only, no default exports- Error handling: use Result types, not try/catch- All environment variables come from .env (never hardcode)- Tests colocated with source as *.test.ts

# When CompactingPreserve the full list of modified files and current test status.

That is 25 lines. It covers everything Claude needs. No fluff.

Long sessions accumulate context fast. When your context window fills up, Claude auto compacts and critical details can get lost. Here is the trick: add compaction instructions directly inside CLAUDE.md.

A line like “When compacting, always preserve the full list of modified files and any test commands” tells Claude what to prioritize during summarization. This one sentence can save you from losing track of 30 minutes of work.

The senior engineers running 13KB+ CLAUDE.md files in production monorepos are not writing prose. They are writing targeted instructions that survive compaction and inform every session. Version control the file alongside your code. Review changes in PRs just like you would review architecture decisions.

Found this useful? A like goes a long way.

For more simple explanations, useful insights on coding, system design and tech trends, Subscribe To My Newsletter! 🚀

Follow me on Youtube · LinkedIn · X · Instagram to stay updated.

See you next week with more exciting content!

Signing Off, Scortier