What is CLAUDE.md?
Every time Claude Code starts in a project, it automatically reads any CLAUDE.md files it finds. Think of it as a standing brief you give Claude — your coding style, your preferred tools, things you never want it to do, and how the project is structured.
Without it, you'd have to repeat yourself every session. With it, Claude just knows.
The two layers
~/.claude/CLAUDE.md ← your personal rules, all projects
./CLAUDE.md ← this specific project's rules
Project rules stack on top of your global ones. So you write personal preferences once globally, and only add project-specific things per repo.
Step 1: Create your global CLAUDE.md
mkdir -p ~/.claude
Open it:
code ~/.claude/CLAUDE.md
Here's a solid starting template:
# My Global Rules
You are pair-programming with me. Optimize for clear, maintainable, shippable code.
## Rules
- Extendable over clever. Strong types. Small coherent modules.
- Avoid large rewrites unless I ask.
- Ask before adding major tools, dependencies, or CI/CD.
- Use Bun by default. Never npm/yarn/pnpm/npx unless I allow it.
- Never ask for or use an OpenAI API key.
- Use conventional commits (feat:, fix:, chore:, docs:, etc.).
- Keep changes incremental — patches under ~70 lines.
- Don't add Co-Authored-By to commits unless I ask.
## Default commands
| Command | Purpose |
|---------|---------|
| `bun install` | Install dependencies |
| `bun run dev` | Start dev server |
| `bun run build` | Build |
| `bun test` | Run tests |
| `bun x tsc --noEmit` | Type check |
| `bun x biome check .` | Check formatting/linting |
## Git
- Check `git status` before changing files.
- Use medium-sized commits.
- Don't push unless I ask.
## Debugging
1. Types first.
2. Temporary logs only when useful — remove them after fixing.
3. If the bug is systemic, rethink the architecture instead of patching.
Make it yours
This is a template. Edit it to match how you actually work. Add rules when you notice Claude making the same mistake twice. Remove rules that don't apply to you.
Step 2: Create a project CLAUDE.md
In any repo, run:
/init
This tells Claude to generate a starter CLAUDE.md for that project based on what it finds. Then edit it to add your specific rules.
Or create one manually:
# Project Instructions
## What this is
[Describe the project in 1-2 sentences]
## Stack
- Framework: Next.js (App Router)
- Package manager: Bun
- Styling: Tailwind CSS v4
- Database: [your DB]
## Commands
| Command | Purpose |
|---------|---------|
| `bun run dev` | Start local dev |
| `bun x tsc --noEmit` | Type check |
## Architecture
- Route-specific code lives near the route in `app/`
- Shared utilities go in named files in `lib/`
- No junk-drawer `utils.ts`
- Server-only code must never enter client bundles
## Do not
- Add dependencies without asking
- Rewrite large files for small fixes
- Use npm/yarn/pnpm/npx
Step 3: Good first prompts to try
Once CLAUDE.md is in place, try these prompts inside claude:
Read CLAUDE.md and summarize the project. Don't edit anything yet.
Implement this feature incrementally. Explain which files you plan to touch before editing anything. Keep changes small and follow CLAUDE.md.
Review the current diff, identify any risks, then suggest a conventional commit message. Don't commit until I say so.
In the next lesson we'll configure Claude's statusline so you can always see what model you're using and how much context you've used.