Place CLAUDE.md Files in Subdirectories for Scoped, Context-Specific Rules

Your root CLAUDE.md sets project-wide rules, but different parts of your codebase often need different instructions. Drop a CLAUDE.md into a subdirectory and it takes effect only when Claude touches files there.

project/
├── CLAUDE.md                  # project-wide rules
├── src/
│   ├── api/
│   │   └── CLAUDE.md          # API-specific rules
│   ├── frontend/
│   │   └── CLAUDE.md          # frontend-specific rules
│   └── payments/
│       └── CLAUDE.md          # strict rules for payments code

Each subdirectory CLAUDE.md adds to (or overrides) the parent. The rules are additive — Claude sees the root file plus the local one when working in that directory.

Here's what a payments module CLAUDE.md might look like:

All changes in this directory require a corresponding test.
Never modify the transaction log format — it's consumed by
the audit system. Use decimal arithmetic for all money
calculations, never floats. Every new public method needs
explicit input validation.

And a frontend CLAUDE.md:

Use React Server Components by default. Client components
must have the "use client" directive. All components need
a corresponding Storybook story. Use CSS modules, not
inline styles.

This is powerful for:

• Monorepos — different rules for each package or service
• Sensitive modules — extra caution around auth, billing, or data access
• Generated code — "don't modify files in this directory, they're auto-generated"
• Legacy vs modern — different patterns for old code vs new code

The best CLAUDE.md isn't one giant file — it's a tree of focused instructions that match your codebase structure.

via Claude Code