Guides/CLAUDE.md

Writing the Perfect CLAUDE.md

CLAUDE.md is Claude Code's persistent memory. A well-written file eliminates repeated instructions, enforces conventions automatically, and makes every session smarter than the last.

ConfigurationBest PracticesHigh Leverage

What CLAUDE.md Does

When you run claude in a directory, Claude Code automatically reads any CLAUDE.md it finds and injects it at the top of the context window. This happens before you type a single word.

Think of it as a briefing document Claude reads every morning before sitting down to work with you. Anything in that document becomes active knowledge for the entire session.

Where to put it

./CLAUDE.md — Project-level. Committed to the repo. Shared with the team.

~/.claude/CLAUDE.md — Global. Personal preferences that apply to every project.

./CLAUDE.local.md — Local override. Gitignored. Personal dev preferences for this project.

Recommended Structure

Every effective CLAUDE.md contains these six sections in roughly this order:

Identity & Persona

Who Claude is in this project — role, tone, domain expertise

Non-Negotiable Rules

Hard constraints: never commit to main, no any types, no hardcoded secrets

Architecture

Tech stack, key files, folder structure, DB patterns

Patterns & Conventions

Naming, component size limits, import aliases, date formats

Team Conventions

Git workflow, commit format, PR process, branch naming

Persistent Memory

Known issues, decisions made, things Claude should never forget

Example Sections

Identity & Persona

# Identity

You are a Senior Full-Stack Developer embedded in the

Acme project. You specialize in Next.js App Router, TypeScript,

Tailwind CSS, and PostgreSQL. Speak in clear, direct technical

language. Prioritize UX, performance, and clean architecture.

Non-Negotiable Rules

## Rules

### Non-Negotiable

- Never commit directly to the `main` branch.

- Never use `any` type — use interfaces from `src/lib/types.ts`.

- Never hardcode secrets. Use environment variables.

- Always use the `@/` import alias (maps to `./src/*`).

- All DB queries use parameterized statements — no string interpolation.

Architecture

## Architecture

- Framework: Next.js 15 App Router (server components default)

- Styling: Tailwind CSS v4 — utility-first, no CSS modules

- Database: PostgreSQL via `src/lib/db.ts` → `getDb()`

- Auth: JWT + bcrypt via `src/lib/auth.ts`

### Key Files

- Types: `src/lib/types.ts`

- DB: `src/lib/db.ts`

- Auth: `src/lib/auth.ts`

Project vs Global CLAUDE.md

Project CLAUDE.md

→Committed to the repo — shared with all contributors
→Contains project-specific rules, architecture, and conventions
→Changes require a PR — keeps rules auditable
→Lives at ./CLAUDE.md

Global CLAUDE.md

→Personal — applies to every project on your machine
→Contains your preferred coding style, tool preferences
→Never committed — stays on your machine
→Lives at ~/.claude/CLAUDE.md

Common Mistakes

Too long

A 1,000-line CLAUDE.md fills context before any work starts. Keep it under 200 lines. Extract stable facts into separate files.

Too vague

"Write good code" is not a rule. Be specific: "All components must be under 150 lines. Extract sub-components when they grow larger."

Contradictory rules

"Always use server components" and "All pages must use useState" cannot coexist. Audit for conflicts before committing.

Missing path aliases

Always document your import aliases (e.g., @/ maps to ./src/*). Without this, Claude uses relative paths that break when files move.

No database patterns

If Claude doesn't know your DB wrapper, it will invent its own. Explain how queries are made, what parameterization looks like.

Forgetting environment variables

List which env vars exist and what they do. Claude cannot guess that JWT_SECRET lives in .env.local.

Get a Battle-Tested CLAUDE.md Template

The AI Starter Package includes a production-ready CLAUDE.md template used across real projects — with all six sections, example rules, and a memory architecture already wired up.

Download the Template Back to Basics

What CLAUDE.md Does

When you run claude in a directory, Claude Code automatically reads any CLAUDE.md it finds and injects it at the top of the context window. This happens before you type a single word.

Think of it as a briefing document Claude reads every morning before sitting down to work with you. Anything in that document becomes active knowledge for the entire session.

Where to put it

./CLAUDE.md — Project-level. Committed to the repo. Shared with the team.

~/.claude/CLAUDE.md — Global. Personal preferences that apply to every project.

./CLAUDE.local.md — Local override. Gitignored. Personal dev preferences for this project.

Recommended Structure

Every effective CLAUDE.md contains these six sections in roughly this order:

Identity & Persona

Who Claude is in this project — role, tone, domain expertise

Non-Negotiable Rules

Hard constraints: never commit to main, no any types, no hardcoded secrets

Architecture

Tech stack, key files, folder structure, DB patterns

Patterns & Conventions

Naming, component size limits, import aliases, date formats

Team Conventions

Git workflow, commit format, PR process, branch naming

Persistent Memory

Known issues, decisions made, things Claude should never forget

Example Sections

Identity & Persona

# Identity

You are a Senior Full-Stack Developer embedded in the

Acme project. You specialize in Next.js App Router, TypeScript,

Tailwind CSS, and PostgreSQL. Speak in clear, direct technical

language. Prioritize UX, performance, and clean architecture.

Non-Negotiable Rules

## Rules

### Non-Negotiable

- Never commit directly to the `main` branch.

- Never use `any` type — use interfaces from `src/lib/types.ts`.

- Never hardcode secrets. Use environment variables.

- Always use the `@/` import alias (maps to `./src/*`).

- All DB queries use parameterized statements — no string interpolation.

Architecture

## Architecture

- Framework: Next.js 15 App Router (server components default)

- Styling: Tailwind CSS v4 — utility-first, no CSS modules

- Database: PostgreSQL via `src/lib/db.ts` → `getDb()`

- Auth: JWT + bcrypt via `src/lib/auth.ts`

### Key Files

- Types: `src/lib/types.ts`

- DB: `src/lib/db.ts`

- Auth: `src/lib/auth.ts`

Project vs Global CLAUDE.md

Project CLAUDE.md

→Committed to the repo — shared with all contributors
→Contains project-specific rules, architecture, and conventions
→Changes require a PR — keeps rules auditable
→Lives at ./CLAUDE.md

Global CLAUDE.md

→Personal — applies to every project on your machine
→Contains your preferred coding style, tool preferences
→Never committed — stays on your machine
→Lives at ~/.claude/CLAUDE.md

Common Mistakes

Too long

A 1,000-line CLAUDE.md fills context before any work starts. Keep it under 200 lines. Extract stable facts into separate files.

Too vague

"Write good code" is not a rule. Be specific: "All components must be under 150 lines. Extract sub-components when they grow larger."

Contradictory rules

"Always use server components" and "All pages must use useState" cannot coexist. Audit for conflicts before committing.

Missing path aliases

Always document your import aliases (e.g., @/ maps to ./src/*). Without this, Claude uses relative paths that break when files move.

No database patterns

If Claude doesn't know your DB wrapper, it will invent its own. Explain how queries are made, what parameterization looks like.

Forgetting environment variables

List which env vars exist and what they do. Claude cannot guess that JWT_SECRET lives in .env.local.