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 multiple locations, with a clear precedence order. Understanding this hierarchy is essential for teams:

Level	Location	Scope	Purpose
Enterprise	System directories	All org users	Organization-wide standards
Project	./CLAUDE.md or ./.claude/CLAUDE.md	Team via git	Shared project knowledge
Project Rules	./.claude/rules/*.md	Team via git	Modular topic-specific rules
User	~/.claude/CLAUDE.md	Individual	Personal preferences
Local	./CLAUDE.local.md	Individual	Personal project overrides

Precedence flows from top to bottom: Enterprise settings override project settings, which override user settings, which override local settings. This means your organization can enforce standards while still allowing personal customization.

The CLAUDE.local.md file is automatically gitignored, making it perfect for personal preferences that shouldn't be shared with the team.

Enterprise Locations

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

• macOS: /Library/Application Support/ClaudeCode/
• Linux: /etc/claude-code/
• Windows: C:\ProgramData\ClaudeCode\

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`

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