CLAUDE.md in Project Workspaces

Claude
UK /klɔːd/ 🕪
US /klɑːd/ 🕪

CLAUDE.md is a special file used with Claude Code (Anthropic’s command-line coding tool) that acts as a persistent set of instructions Claude reads whenever it works on your project. Think of it as a “README for Claude” — it tells Claude how to understand and work within your codebase.

What is CLAUDE.md?

CLAUDE.md is a critical file for providing project-specific context to Claude Code. It serves as an onboarding guide for the AI to your project requirements and codebase. Claude reads it at the start of every conversation, so it always has the right context about how your project works — without you having to repeat yourself.

Think of it this way: LLMs are stateless functions with frozen weights, so they don’t learn over time. The only thing the model knows about your codebase is the tokens you put into it. CLAUDE.md solves this by being the one file that’s automatically included every session.

Where to Place CLAUDE.md

You can place CLAUDE.md files in several locations:

  • Your home folder (~/.claude/CLAUDE.md) which applies to all sessions.
  • Your project root (./CLAUDE.md) which you can check into git to share with your team.
  • Parent directories (useful for monorepos).
  • And child directories which Claude pulls in on demand when working with files in those directories.

CLAUDE.md files can be hierarchical — you can have one at the project level and others in nested directories. Claude looks at them all and prioritizes the most specific, most nested one when relevant.

Best Practices for Writing a Great CLAUDE.md

1. Start with /init, then refine

The /init command analyzes your codebase to detect build systems, test frameworks, and code patterns, giving you a solid foundation to refine. The output tends to be bloated though — if you can’t explain why a line is there, delete it.

2. Cover the WHAT, WHY, and HOW

Tell Claude about the tech, your stack, and the project structure — give it a map of the codebase. This is especially important in monorepos. Then explain the purpose of the project and what everything does. Finally, tell Claude how it should work — for example, do you use bun instead of node? Include how Claude can verify its changes, run tests, typechecks, and compilation steps.

3. Keep it ruthlessly concise

This is the single most important principle. For every line in your CLAUDE.md, ask: would Claude make a mistake without this? If Claude already does something correctly on its own, the instruction is noise. Every unnecessary line dilutes the ones that matter.

Research suggests frontier thinking LLMs can follow roughly 150–200 instructions with reasonable consistency, and the Claude Code system prompt already uses about 50 of those. That means your CLAUDE.md should stay well under 100–150 instructions.

Keep your file small — less than 200 lines — and link it to any skills it may require on demand using imports.

4. Only include universally applicable instructions

CLAUDE.md is loaded every session, so only include things that apply broadly. For domain knowledge or workflows that are only relevant sometimes, use skills instead — Claude loads them on demand without bloating every conversation.

5. Use the @import syntax for longer docs

CLAUDE.md files can import additional files using @path/to/import syntax, like @README.md for the project overview or @docs/git-instructions.md for Git workflow details. This keeps the main file lean while still providing access to deeper context.

6. Document what Claude gets wrong, not everything

Don’t @-file entire docs (which embeds the whole file on every run). Instead, write something like “For complex usage or FooBarError, see path/to/docs.md.” Also, don’t just say “Never use –foo-bar flag” — instead say “Never use –foo-bar; prefer –baz instead,” so the agent doesn’t get stuck.

7. Use emphasis for critical rules

You can tune instructions by adding emphasis (e.g., “IMPORTANT” or “YOU MUST”) to improve adherence.

8. Treat it like code — iterate and version it

Check CLAUDE.md into git so your team can contribute. The file compounds in value over time. Treat it like code: review it when things go wrong, prune it regularly, and test changes by observing whether Claude’s behavior actually shifts.

Example Structure

Here’s a practical template based on the official recommendations:

# Project Overview
Brief one-liner about what this project is.

# Tech Stack
- Next.js 14 (App Router), TypeScript, Tailwind CSS
- Database: PostgreSQL with Prisma ORM
- Testing: Vitest + Playwright

# Key Commands
- Build: `npm run build`
- Test single file: `npx vitest run path/to/test.ts`
- Typecheck: `npx tsc --noEmit`
- Lint: `npm run lint`

# Code Style
- Use ES modules (import/export), not CommonJS (require)
- Destructure imports when possible
- All new components go in `src/components/`

# Workflow
- IMPORTANT: Always run typecheck after making code changes
- Prefer running single tests, not the whole suite
- Never commit secrets or .env files
- When compacting, preserve the full list of modified files

# References
- See @README.md for full project overview
- See @docs/api-conventions.md for API patterns

The golden rule: if Claude keeps making a mistake you’ve told it not to, your file is probably too long and the instruction is getting lost. Trim everything else first.

References:

You may also like...