CLAUDE.md Patterns That Actually Work

If you've used Claude Code for more than a few sessions, you've probably noticed something: Claude performs dramatically better when it understands your project. That understanding doesn't come from magic—it comes from CLAUDE.md.

CLAUDE.md is a special file that Claude Code automatically reads when starting a conversation. As Anthropic's engineering team puts it: "The better you document your workflows, tools, and expectations, the better Claude Code performs."

This isn't just configuration. It's context engineering—deliberately shaping what Claude knows about your project so it can make better decisions.

What CLAUDE.md Actually Is

Think of CLAUDE.md as persistent memory for Claude Code. Every time you start a session, Claude reads these files and incorporates them into its understanding of your project. Unlike chat history that fades, CLAUDE.md persists across sessions and team members.

You can create one instantly with the /init command, which analyzes your codebase and generates a starting point. But the real power comes from understanding the hierarchy and crafting it deliberately.

The File Hierarchy

Claude Code reads CLAUDE.md files from several locations. The table below lists them in load order, broadest scope first:

Scope	Location	Shared with
Managed policy	System directories (see below)	All users in the organization
User	~/.claude/CLAUDE.md	Just you, every project
Project	./CLAUDE.md or ./.claude/CLAUDE.md	Your team, via source control
Project rules	./.claude/rules/*.md	Your team, via source control
Local	./CLAUDE.local.md	Just you, this project

These files are concatenated, not overridden. This is the most misunderstood thing about the system, and an earlier version of this article got it wrong too. There is no precedence cascade where one file wins and the rest are discarded. Everything discovered goes into context in order, from the filesystem root down to your working directory, so instructions closer to where you launched Claude are read last. Within a directory, CLAUDE.local.md is appended after CLAUDE.md.

The practical consequence: if two files contradict each other, Claude may pick one arbitrarily. A contradiction is a bug in your configuration, not a precedence question to reason about. Review your files periodically and delete the conflict rather than relying on load order to resolve it.

One more correction. CLAUDE.local.md is not automatically gitignored. You add it to .gitignore yourself, and if you forget, your personal sandbox URLs and test data go to the whole team.

In a large monorepo where other teams' files get picked up, claudeMdExcludes in your settings skips specific paths or globs. Managed policy files are the exception and cannot be excluded.

Enterprise Locations

For organizations deploying Claude Code at scale, enterprise policy files live in system directories:

• macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
• Linux and WSL: /etc/claude-code/CLAUDE.md
• Windows: C:\Program Files\ClaudeCode\CLAUDE.md

What to Include

The most effective CLAUDE.md files share common patterns. Here's what belongs in yours:

1. Build and Test Commands

Claude needs to know how to verify its work. Document your commands explicitly:

## Development Commands

- `npm run dev` - Start development server
- `npm run build` - Build for production
- `npm run test` - Run test suite
- `npm run lint` - Check code style
- `npm run type-check` - TypeScript validation

Always run `npm run build` after making changes to verify no errors.

2. Code Style Guidelines

Be specific. "Format code properly" means nothing. "Use 2-space indentation and single quotes" is actionable:

## Code Style

- Use 2-space indentation (not tabs)
- Single quotes for strings
- No semicolons (we use Prettier)
- Prefer `const` over `let`
- Use TypeScript strict mode

3. Git Workflow

Document your team's conventions:

## Git Conventions

- Branch naming: `feature/description` or `fix/description`
- Commit messages: Start with verb (Add, Fix, Update, Remove)
- Always rebase, never merge
- Squash commits before merging to main

4. Project Architecture

Help Claude understand your codebase structure:

## Architecture

- `/src/app` - Next.js App Router pages
- `/src/components` - Reusable React components
- `/src/lib` - Utility functions and configurations
- `/src/types` - TypeScript type definitions
- `/database` - SQL migrations and schema

5. Environment Setup

Document what Claude needs to know about your environment:

## Environment

- Node.js 20+ required
- Use `pyenv` for Python version management
- Database runs in Docker: `docker compose up -d`
- Environment variables in `.env.local`

Advanced Features

Import Syntax

CLAUDE.md supports importing other files using the @ syntax:

# Project Guidelines

See @README for project overview.
Check @package.json for available npm scripts.

Development workflow: @docs/DEVELOPMENT.md
Git conventions: @docs/git-workflow.md

Imports work recursively up to 5 levels deep. This enables modular documentation where each file focuses on one topic.

Path-Specific Rules

For large codebases, you can create rules that only apply to certain paths using YAML frontmatter:

---
paths: src/api/**/*.ts
---

# API Development Rules

- All endpoints must include input validation with Zod
- Use proper HTTP status codes (201 for creation, 204 for deletion)
- Include rate limiting headers
- Log all errors to monitoring service

This file would only activate when Claude is working with files matching the src/api/**/*.ts pattern.

The Rules Directory

For complex projects, a single CLAUDE.md becomes unwieldy. Use the .claude/rules/ directory for modular organization:

.claude/
├── CLAUDE.md           # Core project context
└── rules/
    ├── api.md          # API development standards
    ├── testing.md      # Testing requirements
    ├── security.md     # Security policies
    └── database.md     # Database conventions

Claude loads all files in the rules directory, applying each based on their frontmatter paths.

Real-World Examples

Minimal CLAUDE.md (Startup/Small Project)

# Project: TaskFlow

A React + Node.js task management app.

## Commands
- `npm run dev` - Start development
- `npm test` - Run tests

## Style
- TypeScript strict mode
- Prettier for formatting
- ESLint for linting

## Git
- Feature branches off main
- Squash and merge PRs

Comprehensive CLAUDE.md (Enterprise)

# Enterprise Platform

B2B SaaS platform with React frontend and Python backend.

## Architecture
See @docs/architecture.md for full system design.

## Development
- Frontend: `cd frontend && npm run dev`
- Backend: `cd backend && poetry run uvicorn main:app --reload`
- Database: `docker compose up postgres redis -d`

## Code Standards
- Frontend: @docs/frontend-standards.md
- Backend: @docs/python-standards.md
- API Design: @docs/api-guidelines.md

## Testing Requirements
- All PRs require passing tests
- Coverage threshold: 80%
- Integration tests for all API endpoints

## Security
- Never commit secrets
- Use environment variables for configuration
- All user input must be validated
- SQL queries use parameterized statements

## Git Workflow
- Branch from `develop`, not `main`
- PR template: @.github/PULL_REQUEST_TEMPLATE.md
- Require 2 approvals before merge
- CI must pass before merge

## Deployment
- Staging: auto-deploy from `develop`
- Production: manual deploy from `main`
- Rollback procedure: @docs/rollback.md

Best Practices

1. Start Small, Iterate Often

Don't try to document everything at once. Start with the essentials—build commands, code style, git conventions—and add more as you discover gaps.

Use the # key in Claude Code to have Claude suggest additions based on your conversation. If you find yourself repeating instructions, that's a sign to add them to CLAUDE.md.

2. Be Specific, Not Vague

Instead of...	Write...
"Format code properly"	"Use 2-space indentation and Prettier"
"Follow best practices"	"Use TypeScript strict mode, no any types"
"Write good tests"	"Test files go in __tests__/ with .test.ts extension"

3. Keep It Maintainable

Review your CLAUDE.md periodically. Outdated instructions confuse Claude just as they'd confuse a new team member. When you change build tools, update testing approaches, or modify git workflows—update CLAUDE.md too.

4. Use Team CLAUDE.md for Shared Standards

Check ./CLAUDE.md or ./.claude/CLAUDE.md into git so the entire team benefits. Personal preferences go in ~/.claude/CLAUDE.md (global) or ./CLAUDE.local.md (project-specific, gitignored).

5. Document Unusual Behaviors

Every project has quirks. Document them:

## Known Quirks

- The `legacy/` directory uses old ESLint config (don't change it)
- Tests must run sequentially: `npm test -- --runInBand`
- Hot reload sometimes fails; restart with `npm run dev:clean`

Auto Memory: The Half Most People Missed

The biggest change since this guide first published is that CLAUDE.md is no longer the only memory system. Auto memory runs alongside it, and Claude writes it rather than you.

	CLAUDE.md	Auto memory
Who writes it	You	Claude
What it holds	Instructions and rules	Learnings and corrections
Scope	Project, user, or org	Per repository
Use it for	Standards, workflows, architecture	Your preferences and the corrections you keep repeating

Claude saves four kinds of note, tagged by type in the file's frontmatter: user for your role and working preferences, feedback for corrections you gave and approaches you confirmed, project for work and decisions it cannot read out of the code or git history, and reference for where to find things outside the project.

It deliberately skips anything derivable from the codebase, and anything your CLAUDE.md already says. It also does not save something every session; it decides what is worth keeping.

Memory lives at ~/.claude/projects/<project>/memory/, with a MEMORY.md index and one file per topic. Only the index loads at session start, capped at the first 200 lines or 25KB, whichever comes first. Topic files are read on demand. Auto memory is machine-local and is not shared across machines.

It is on by default. Toggle it with /memory, per project with autoMemoryEnabled in settings, or globally with the CLAUDE_CODE_DISABLE_AUTO_MEMORY environment variable.

The practical upshot for anyone who wrote a careful CLAUDE.md a year ago: some of what you hand-maintain now accumulates by itself. Ask Claude to remember something and it goes to auto memory. Ask it to add something to CLAUDE.md and it goes there instead. Knowing which one you want is the new skill.

Instructions Are Not Enforcement

This deserves its own section because it is the most expensive misunderstanding in the whole system.

CLAUDE.md is delivered as context, not as enforced configuration. Claude reads it and tries to follow it. There is no guarantee of compliance, particularly for vague or conflicting instructions.

If something must happen at a specific moment, write it as a hook instead. Hooks run as shell commands at fixed lifecycle events, regardless of what Claude decides. "Run the formatter after every edit" belongs in a hook. "Prefer named exports" belongs in CLAUDE.md.

The rule of thumb: if you would be genuinely upset when it does not happen, it is not an instruction, it is a hook.

Keep It Under 200 Lines

Current guidance is explicit: target under 200 lines per CLAUDE.md file. Longer files consume more context and measurably reduce adherence. Claude Code will load a file up to 4 MiB, but loading it and following it are different things.

If your file is growing, the fix is not to shorten sentences. It is to move content somewhere that loads conditionally:

• A multi-step procedure belongs in a skill, which loads only when invoked or judged relevant.
• Something that only matters in one part of the codebase belongs in a path-scoped rule under .claude/rules/, which loads only when Claude touches matching files.
• Anything Claude can derive from the code itself, like directory layouts and dependency lists, should be deleted. Running /doctor proposes exactly these trims.

Note that @path imports help organisation but do not reduce context, because imported files still load at launch. That trips people up.

Already Have an AGENTS.md?

Claude Code reads CLAUDE.md, not AGENTS.md. If your repository already has one for other coding agents, import it rather than maintaining two copies:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

A symlink works too if you have nothing Claude-specific to add:

ln -s AGENTS.md CLAUDE.md

Either way, run /context afterwards and confirm CLAUDE.md appears under Memory files. That command is also the answer to "is Claude actually reading my file?", which is the most common support question about this whole system and is usually answered in about three seconds.

Measuring Success

How do you know your CLAUDE.md is working? Look for these signals:

• Fewer corrections: You're not constantly telling Claude about your conventions
• Better first attempts: Claude's initial code matches your style
• Reduced context-setting: You can jump straight to the task without preamble
• Team consistency: Different team members get consistent Claude behavior

What's Next

This is Part 1 of our Claude Code Mastery series. Now that you understand how to configure Claude's memory, you're ready to automate its behavior with hooks.

Up next: Part 2: Hooks & Automation Deep Dive — Learn how to create automated quality gates that run before and after Claude's actions.

---

Sources

• Claude Code Official Documentation
• Claude Code Best Practices — Anthropic Engineering Blog
• Claude Code GitHub Repository

---

How This Article Was Made

This article is a live example of the AI-enabled content workflow we build for clients.

This is a refresh of a December 2025 guide, rewritten in place rather than republished at a new URL.

Stage	Who	What
Audit	Tom Hundley	Flagged the page from search data; the memory system had gained a second half since publication
Research	Claude Opus 5	Current memory documentation, read in full rather than skimmed for deltas
Editing	Claude Opus 5	Corrected the errors, added what was missing, left the working parts alone
Verification	Human + AI	Every replacement asserted by count; the first attempt failed an assertion on a backslash in a Windows path rather than silently doing nothing
Editorial	Tom Hundley	Final review for accuracy, tone, and value

What the refresh corrected. Three factual errors, all of which would have cost a team real time. The article described a precedence cascade in which enterprise overrides project overrides user; the files are actually concatenated in load order and nothing overrides anything. It listed the Windows managed-policy location as C:\ProgramData\ClaudeCode\, which is wrong. And it stated that CLAUDE.local.md is automatically gitignored, which it is not, so anyone trusting that line was committing personal configuration to a shared repository.

What was added. Auto memory, which did not exist when this published and is now half the system. The distinction between instructions and enforcement, and why a hook is the right home for anything that must actually happen. The current size guidance. Interoperability with AGENTS.md. The documentation link also moved domains.

Want to build this capability for your team? Let's talk about AI enablement →

---