CLAUDE.md Quick Start: 10 Rules Every New Project Needs

If you just discovered CLAUDE.md, here's the short version: it's a file Claude Code reads on every session. Whatever you put in it becomes persistent project context — no more re-explaining your stack, conventions, or constraints every time you open a new chat.

The problem is that most CLAUDE.md files start as a vague wishlist. "Write clean code." "Follow best practices." "Be careful." Those rules do nothing — Claude already tries to do all of that. What actually moves the needle is rules that are specific, testable, and enforce decisions your project has already made.

Here are 10 rules that belong in almost every CLAUDE.md. Copy them, adapt the specifics to your stack, and you'll have a working starting template in 10 minutes.

1. Declare the stack in one block

Claude guesses at your stack from file extensions and imports. Guessing gets it wrong often enough to matter.

## Stack
- Runtime: Node.js 20, TypeScript 5.4
- Framework: Next.js 14 (app router)
- Database: Postgres 16 via Prisma
- Styling: Tailwind CSS v3
- Tests: Vitest + Playwright
- Package manager: pnpm (NOT npm)

Put the package manager in there. It's the single most common source of "why did it just run npm install and wreck my lockfile" friction.

2. Ban the things you know you don't want

Negative rules are more useful than positive ones. "Use TypeScript" is obvious. "Do not add any types" is actionable.

## Do not
- Do not use `any` — use `unknown` and narrow it
- Do not add `console.log` statements to committed code
- Do not install new dependencies without asking first
- Do not modify files under `migrations/` — they are append-only
- Do not run `git push --force` on shared branches

Each line represents a past incident. If your team has been burned by something, it belongs here.

3. Specify the test command exactly

Claude will invent plausible-looking test commands if you don't tell it the real one. Then it reports "tests pass" based on a command that ran zero tests.

## Commands
- Install: `pnpm install --frozen-lockfile`
- Dev server: `pnpm dev` (port 3000)
- Type check: `pnpm typecheck`
- Lint: `pnpm lint`
- Unit tests: `pnpm test`
- E2E tests: `pnpm test:e2e` (requires dev server running)

Bonus: include the port. It prevents Claude from spawning a second dev server on a different port when one is already running.

4. Tell it what "done" means

"Done" is the most abused word in software. Define it concretely so Claude doesn't declare victory too early.

## Definition of done
A task is only complete when:
1. New code has tests (unit for logic, E2E for flows)
2. `pnpm typecheck` passes with zero errors
3. `pnpm lint` passes with zero warnings
4. All new/modified tests pass
5. Manual sanity check of the changed UI (if applicable)

Now "it works on my machine" isn't enough. Claude has an explicit checklist.

5. Point to the folders that matter

Claude does not need to explore your whole repo. Tell it where things live.

## Project layout
- `app/` — Next.js routes (app router)
- `lib/` — shared utilities, no framework imports
- `components/` — React components (PascalCase files)
- `db/` — Prisma schema + seed scripts
- `scripts/` — one-off CLI scripts (TypeScript)
- `tests/e2e/` — Playwright specs

This replaces 5 minutes of ls and grep calls at the start of every session.

6. Lock in naming conventions

Once a team drifts on naming, every new file becomes a decision. Eliminate the decision.

## Naming
- React components: PascalCase, one component per file (`UserCard.tsx`)
- Hooks: camelCase, prefixed with `use` (`useAuth.ts`)
- API route files: kebab-case (`app/api/user-profile/route.ts`)
- Database tables: snake_case, plural (`user_sessions`)
- Env vars: SCREAMING_SNAKE_CASE

These are boring rules. That's why they work — there's no room to interpret them creatively.

7. Define the git workflow

"Just commit it" produces junk drawer commits. Spell out the workflow.

## Git workflow
- Branch from `main`, name it `type/short-description` (e.g. `fix/login-redirect`)
- Commits use conventional format: `type(scope): summary`
- One logical change per commit — split if needed
- Never commit `.env*`, `*.pem`, or files in `/secrets`
- Do not push directly to `main` — open a PR

Add Do not commit without asking if you prefer to review diffs yourself before they hit git.

8. Encode the data layer rules

The database is where cleverness becomes expensive. Be explicit.

## Database
- All schema changes go through Prisma migrations — never edit the DB directly
- Every new table needs: `id`, `created_at`, `updated_at`
- Foreign keys always cascade on delete — document exceptions in the schema
- Never write raw SQL in application code — use Prisma or a repository helper
- Seed scripts live in `db/seed/` and must be idempotent

This one rule alone prevents half the "why is staging broken" Slack threads.

9. Set a policy for new dependencies

Left alone, an AI assistant will happily add a 4MB library to parse a date string.

## Dependencies
- Do not add a new dependency without asking first
- Prefer the standard library and existing project dependencies
- If a new dep is justified, add it with `pnpm add <pkg>` (exact version pinned)
- Dev-only tools go under `devDependencies`
- Check bundle impact for anything added to client-side code

This one rule keeps node_modules from becoming a junk drawer.

10. Write a "when stuck, ask" clause

The worst outcome is Claude silently doing something wrong for 20 minutes. Give it an explicit escape hatch.

## When stuck
- If a task is ambiguous, ask before coding
- If an approach isn't working after 2 attempts, stop and explain what you tried
- If a requirement conflicts with an existing rule in this file, flag the conflict
- Never mock a failing test just to make it green — fix the underlying cause
- Never delete a test without explaining why it's no longer relevant

This is the most important rule in the whole file. It converts silent failure into a conversation.

Putting it together

A minimal CLAUDE.md built from these 10 rules is maybe 80 lines. That's enough to turn a fresh Claude session into a project-aware collaborator without any preamble.

Two quick tips once you have the basics in place:

1. Treat CLAUDE.md like code. Commit it. Review changes to it in PRs. Remove rules that have become obsolete.
2. One rule per incident. Every time Claude does something you have to correct, ask whether a rule would have prevented it. If yes, add it.

Want 50+ production-tested rules?

The 10 rules above are a starting point. Real projects end up with 40–60 rules covering edge cases across frameworks, databases, deployment, security, and team conventions.

I maintain a curated pack of 50+ CLAUDE.md rules — organized by category, with explanations and example snippets for each — pulled from shipping real products with Claude Code. If you want to skip the trial-and-error phase:

CLAUDE.md Rules Pack →

Drop it into your repo, trim the rules you don't need, and you have a battle-tested CLAUDE.md in a few minutes.