CLAUDE.md Best Practices for Projects
The Problem
You have a CLAUDE.md file but Claude Code does not consistently follow your instructions. Rules get ignored, the file has grown unwieldy, and your team members have conflicting configurations.
Quick Fix
Keep CLAUDE.md under 200 lines. Use specific, verifiable instructions instead of vague guidance:
# CLAUDE.md
- Use 2-space indentation for TypeScript
- Run `pnpm test` before committing
- API handlers go in src/api/handlers/
- Never import from src/internal/ in public modules
What’s Happening
CLAUDE.md files are loaded into the context window at the start of every session, consuming tokens alongside your conversation. Claude treats them as context rather than enforced configuration. The more specific and concise your instructions, the more consistently Claude follows them.
Longer files consume more context and reduce adherence because Claude must balance more instructions against the actual task. Vague instructions like “format code properly” give Claude no clear criteria to verify against, while “use 2-space indentation” is unambiguous.
Claude Code supports CLAUDE.md files at multiple scopes, each with different loading behavior. Understanding this hierarchy is key to effective configuration.
Step-by-Step Fix
Step 1: Choose the right location
| Scope | Location | Use for |
|---|---|---|
| Managed policy | /Library/Application Support/ClaudeCode/CLAUDE.md |
Org-wide standards |
| Project | ./CLAUDE.md or ./.claude/CLAUDE.md |
Team-shared instructions |
| User | ~/.claude/CLAUDE.md |
Personal preferences |
| Local | ./CLAUDE.local.md |
Personal project overrides |
Project CLAUDE.md files are shared via version control. Local files are gitignored for personal preferences.
Step 2: Generate a starting point
Run /init in Claude Code to auto-generate a CLAUDE.md based on your codebase:
/init
Claude analyzes your project and creates a file with build commands, test instructions, and conventions it discovers. If a CLAUDE.md already exists, /init suggests improvements.
Step 3: Write specific, verifiable instructions
Every instruction should be concrete enough to verify:
# Build & Test
- Build: `pnpm build`
- Test: `pnpm test`
- Lint: `pnpm lint`
- Type check: `pnpm tsc --noEmit`
# Code Conventions
- Use 2-space indentation
- Prefer named exports over default exports
- Error types extend AppError from src/errors/base.ts
- All API endpoints must validate input with zod schemas
# Architecture
- src/api/handlers/ - HTTP request handlers
- src/services/ - Business logic
- src/models/ - Database models
- src/utils/ - Shared utilities (never import from services/)
Step 4: Use imports for large documentation
Instead of cramming everything into CLAUDE.md, import files:
See @README for project overview and @package.json for npm commands.
# Additional Instructions
- git workflow @docs/git-instructions.md
- API conventions @docs/api-conventions.md
Imported files are expanded and loaded at launch. Relative paths resolve relative to the CLAUDE.md file.
Step 5: Use .claude/rules/ for scoped instructions
For instructions that only apply to specific file types or directories, use rules files:
Create .claude/rules/typescript.md:
---
paths:
- "**/*.ts"
- "**/*.tsx"
---
- Use strict TypeScript: no `any` types
- All functions must have explicit return types
- Use `interface` over `type` for object shapes
Rules with paths: frontmatter load only when Claude reads matching files, keeping baseline context small.
Step 6: Handle monorepo CLAUDE.md files
In large monorepos, CLAUDE.md files from other teams get picked up when Claude walks the directory tree. Use claudeMdExcludes to skip irrelevant files:
{
"claudeMdExcludes": [
"packages/team-b/**",
"services/legacy/**"
]
}
Add this to your settings to prevent other teams’ CLAUDE.md files from loading.
Step 7: Understand compaction behavior
After compaction, project-root CLAUDE.md and auto memory re-inject from disk automatically. Path-scoped rules and subdirectory CLAUDE.md files are lost until Claude reads a matching file again.
If a rule must persist across compaction, remove the paths: frontmatter or move it to the project-root CLAUDE.md.
Step 8: Separate personal from team instructions
Use CLAUDE.local.md for personal preferences that should not affect your team:
# CLAUDE.local.md (gitignored)
- I prefer verbose error messages in test output
- Always show me the full diff before committing
- My sandbox URL: http://localhost:3001
Prevention
Review CLAUDE.md quarterly. Remove outdated instructions and consolidate duplicates. When Claude makes the same mistake twice, add a specific rule. When a code review catches something Claude should know, add it to CLAUDE.md.
Target under 200 lines per file. Use .claude/rules/ files for type-specific instructions and skills for multi-step procedures. This keeps the per-session context overhead minimal.
Level Up Your Claude Code Workflow
The developers who get the most out of Claude Code aren’t just fixing errors — they’re running multi-agent pipelines, using battle-tested CLAUDE.md templates, and shipping with production-grade operating principles.
Get Claude Code Mastery — included in Zovo Lifetime →
16 CLAUDE.md templates · 80+ prompts · orchestration configs · workflow playbooks. $99 once, free forever.