CLAUDE.md: the file every developer should have in their projects

There's a reason Claude Code writes great code in some projects and generic boilerplate in others.

It's not the model. It's CLAUDE.md. It's also the single biggest reason I can code roughly 3x faster with Claude Code — the convention file is what removes the back-and-forth.

What it is

CLAUDE.md is a plain markdown file that Claude Code reads at the start of every session. Think of it as the onboarding doc you'd give a senior contractor on day one: stack, conventions, rules, context.

Without it, Claude infers patterns from what it sees in the codebase. Sometimes it infers correctly. Often it doesn't — especially for implicit conventions your team just "knows".

With a good CLAUDE.md, Claude outputs code that follows your rules without being told each time.

What to put in it

1. Stack and versions

## Stack
- Next.js 16 (App Router), React 19
- TypeScript strict
- Tailwind 4 + Shadcn/ui
- next-safe-action for server actions

Simple but important. Claude will use the right APIs, the right imports, and won't reach for patterns from older versions.

2. Architecture overview

## Architecture
src/
├── app/          # Routes (App Router)
├── components/   # UI primitives + layout
├── domain/       # Domain entities + errors
├── lib/          # Shared utilities
└── actions/      # next-safe-action server actions

This tells Claude where things live and where to put new things.

3. Hard conventions

The rules that aren't obvious from reading the code:

## Conventions
 
### Imports — single block, no blank lines between imports
### Actions — always next-safe-action, never raw async functions
### Errors — services throw DomainError, actions never return { success: false }
### Logging — single-line format: log.info(`Message | key=${value}`)

These are exactly the rules that a new contributor (human or AI) gets wrong first. Put them here.

4. What not to do

This is the most underrated section:

## Never do this
- No console.log (use logger)
- No try/catch in actions
- No { success: true, data } return shape
- No blank lines between imports

Explicit prohibitions are more effective than implied conventions. Claude will follow them.

5. Code examples

For patterns that are hard to describe, just show them:

## Action pattern (always use this)
 
\`\`\`ts
export const myAction = authenticatedAction
  .schema(MySchema)
  .action(async ({ parsedInput, ctx }) => {
    return await myService.doThing(ctx.userId, parsedInput);
  });
\`\`\`

Examples outperform rules. If you have one canonical way to write something, show it.

Where to put it

• /CLAUDE.md — project root, checked into git
• ~/.claude/CLAUDE.md — global, applies to all projects (for your personal cross-project standards)

You can also use @path/to/file.md inside CLAUDE.md to include other files. Good for splitting out large rule sets.

Keep it honest

The worst CLAUDE.md is one that describes how the codebase should be, not how it is. Claude will follow the instructions and generate code inconsistent with the existing patterns.

Write it by reading the actual code, not your ideal state. Update it when conventions change.

The compounding return

The first CLAUDE.md takes an hour to write. After that, every AI-assisted session in that project costs less context overhead. You stop re-explaining things. Code review gets faster because the generated code already follows your rules.

It's the highest-leverage file you can add to a project right now.

The CLAUDE.md Starter Kit gives you a production-ready template for Next.js + TypeScript projects. Adapt it to your stack in 10 minutes.