Add CLAUDE.md Files in Subdirectories for Module-Specific Instructions

A single root CLAUDE.md works great for small projects, but larger codebases have modules with their own conventions, dependencies, and quirks. Subdirectory CLAUDE.md files let you layer context so Claude gets the right instructions for whichever part of the code it's working in.

my-project/
├── CLAUDE.md                    # Global rules: coding style, commit conventions
├── app/
│   ├── CLAUDE.md                # Backend rules: use form requests, never raw SQL
│   └── Services/
│       └── CLAUDE.md            # Service layer: always inject dependencies
├── resources/views/
│   └── CLAUDE.md                # Frontend: use Flux UI components, Tailwind v4
└── tests/
    └── CLAUDE.md                # Testing: use Pest, always use factories

When Claude works on a file, it reads CLAUDE.md files from the project root down to the file's directory — instructions stack and get more specific as you go deeper.

This means your root CLAUDE.md handles the universal stuff:

# Root CLAUDE.md
- Use strict types in all PHP files
- Run `vendor/bin/pint --dirty` after PHP changes
- Commit messages: imperative mood, under 72 chars

And subdirectory files handle module-specific context:

# tests/CLAUDE.md
- Use Pest, not PHPUnit directly
- Always use model factories, never create models manually
- Use RefreshDatabase trait on all feature tests
- Run tests with: php artisan test --compact

This keeps each CLAUDE.md focused and short — Claude only loads what's relevant to the files it's touching, rather than wading through a massive root file with sections for every module.

It's especially powerful for monorepos where packages have completely different tech stacks — your Go service and your React frontend can each have their own CLAUDE.md with the right language, framework, and tooling instructions.

One CLAUDE.md per module keeps instructions focused — Claude gets exactly the context it needs, right where the code lives.

via Claude Code