Use CLAUDE.md to Set Project Context
A CLAUDE.md file in your project root is automatically loaded into every Claude Code conversation. Use it to define your stack, conventions, and common commands so you never have to re-explain them.
# CLAUDE.md
## Stack
- PHP 8.4, Laravel 13, Livewire 4, Tailwind CSS v4
## Commands
- `php artisan test --compact` — run tests
- `vendor/bin/pint --dirty` — format code
## Conventions
- All PHP files must use `declare(strict_types=1);`
- Use Pest for testing, not PHPUnit directly
- Service layer handles business logic — controllers handle HTTP only
Claude Code looks for CLAUDE.md in two places: the project root (loaded for every session in that directory) and the global ~/.claude/CLAUDE.md (loaded for every session, everywhere). Put project-specific rules in the project file and universal preferences in the global one.
You can also create nested CLAUDE.md files in subdirectories for more specific context — useful in monorepos where different packages have different conventions. Claude picks up the most relevant one based on the files you're working with.
Keep it concise — think of it as a cheat sheet for Claude, not a novel. A well-maintained 30-line CLAUDE.md beats a 300-line one nobody keeps up to date.
The best CLAUDE.md is the one that reflects how your project actually works today — not how it worked six months ago.
Log in to leave a comment.
When Claude writes error messages, button labels, validation text, or onboarding flows, it defaults to generic developer-speak. Add a "Users" section to your CLAUDE.md describing who your actual users are — their technical level, industry jargon, and what they care about — so Claude writes copy that makes sense to THEM, not to developers.
Use the --agent flag with custom markdown files in .claude/agents/ to launch purpose-built Claude sessions with restricted tools and scoped system prompts.
Every project has traps — the billing module that silently fails if you forget to queue the job, the legacy table with column names that don't match the model, the config value that must be set before tests run. Document these gotchas in your CLAUDE.md so Claude avoids the same mistakes your team spent days debugging.