The CLAUDE.md configuration checklist: 15 items every project needs

Every time Claude Code does something you have to correct, a CLAUDE.md rule would have prevented it. The file in the wrong directory, the test command that does not exist, the import style that does not match your codebase. Each correction is a signal that your config is missing something.

This checklist covers the 15 items that matter most. Some take 30 seconds to add. None are optional if you want Claude to work the way you expect.

Category 1: Project structure (items 1-3)

1. Tech stack declaration

One line that tells Claude what it is working with.

React 19 + TypeScript 5.4, Vite, Tailwind CSS 4, PostgreSQL via Prisma.

This seems obvious, but without it Claude infers your stack from file extensions and package.json. That works most of the time, but fails when you have multiple languages or frameworks in the same repo.

2. Directory map

Where key directories live and what goes in them.

- src/components/  — React components (one per file, PascalCase)
- src/hooks/       — Custom hooks (use* prefix)
- src/lib/         — Utility functions (pure, no React imports)
- src/routes/      — Page components (maps to URL path)
- prisma/          — Database schema and migrations

Without this, Claude reads your directory listing and makes educated guesses. The guesses are right 80% of the time. The other 20% creates files you have to move.

3. Important files

Files that Claude should know about but might not find on its own.

- src/lib/db.ts          — Database client singleton
- src/middleware/auth.ts  — Auth middleware (used by all protected routes)
- .env.example            — Template for environment variables

Listing key files prevents Claude from creating duplicates. If Claude does not know about your database singleton, it might create a new one.

Category 2: Architecture (items 4-6)

4. Layer separation

How your code is organized into layers and what each layer does.

- Routes handle HTTP (request parsing, response formatting)
- Services handle business logic (no HTTP concepts)
- Models handle data access (Prisma queries only here)

Without layer rules, Claude puts business logic in route handlers. It works, but it violates your architecture and makes future changes harder.

5. Data flow patterns

How data moves through your application.

Route → Service → Model → Database
Routes never import Models directly.
Services return plain objects, never Prisma types.

This prevents the most common architecture violation: Claude bypassing a layer because the direct path is shorter.

6. State management approach

For frontend projects, how state is handled.

- Global state: Zustand store in src/stores/
- Server state: TanStack Query (never fetch in useEffect)
- Form state: React Hook Form
- No prop drilling beyond 2 levels — use context or store

State management is where Claude's training data creates the most inconsistency. It knows five different approaches and will pick whichever feels most natural for the current component, regardless of what the rest of your app uses.

Category 3: Coding conventions (items 7-10)

7. Naming rules

- Files: kebab-case (user-profile.tsx, not UserProfile.tsx)
- Components: PascalCase
- Functions: camelCase
- Constants: UPPER_SNAKE_CASE
- Database columns: snake_case

Naming conventions are the rules Claude breaks most often without explicit instructions. It defaults to its training data patterns, which are a mix of every convention.

8. Import ordering

- Built-in modules first (node:fs, node:path)
- External packages second (react, prisma)
- Internal modules third (@/lib, @/components)
- Relative imports last (./utils, ../hooks)
- Blank line between each group

This is a small detail that shows up in every code review if Claude does not follow it.

9. Error handling pattern

- Use custom AppError class (extends Error, has statusCode)
- Services throw AppError, routes catch and format response
- Never swallow errors silently (no empty catch blocks)
- Log errors with structured logger, not console.error

Without a defined error handling pattern, Claude uses try/catch inconsistently and sometimes creates bare catch (e) blocks that hide bugs.

10. Component pattern (frontend)

- Functional components only (no class components)
- Props interface named ComponentNameProps (exported)
- No default exports. Use named exports everywhere.
- Colocate styles: component.tsx + component.module.css

If you use React, this is one of the highest-impact convention rules. Claude alternates between default and named exports, between inline styles and CSS modules, and between props types and props interfaces unless you tell it which one to use.

Category 4: Testing (items 11-13)

11. Test framework and run command

- Framework: Vitest
- Run all: npm test
- Run single: npx vitest run src/routes/users.test.ts
- Watch mode: npx vitest

The run command is the single most impactful testing rule. Without it, Claude either skips tests or tries npm test and hopes it works.

12. Test file location and naming

- Test files: same directory as source, named *.test.ts
- Test fixtures: tests/fixtures/ (shared test data)
- Test helpers: tests/helpers/ (factory functions, mock setup)

Co-located tests vs. a separate test directory is a project-level decision that Claude cannot infer. Tell it which one you use.

13. What to test and how

- Test behavior, not implementation
- Mock external services (HTTP, database). Never mock internal modules.
- Every route needs at least: success case, validation error, not found
- Use describe blocks per function/route, it blocks per scenario

Without testing conventions, Claude writes tests that test implementation details (checking that a specific function was called) rather than behavior (checking that the response is correct). These tests break every time you refactor.

Category 5: Guardrails (items 14-15)

14. Destructive action prevention

- Never force-push to main/master
- Never delete files with rm (use mv to .trash/)
- Never run git reset --hard without confirmation
- Never skip pre-commit hooks (--no-verify)
- Never drop database tables without confirmation

These five rules prevent the most common irreversible mistakes. They take 30 seconds to write and save hours of recovery time.

15. Scope boundaries

- Do not add dependencies without asking
- Do not modify CI/CD configuration
- Do not change the database schema without creating a migration
- Do not refactor code outside the scope of the current task

Scope boundaries prevent Claude from "helpfully" fixing things you did not ask about. Refactoring a function while fixing a bug is how regressions happen.

How to use this checklist

Go through the 15 items above. For each one, write 1-3 lines in your CLAUDE.md. The whole process takes about 15 minutes for a new project.

For existing projects, check which items you already cover. Most CLAUDE.md files cover 4-6 of the 15 items. The gaps are where Claude makes the mistakes you keep correcting.

You do not need to write these from scratch. The ContextKit Generator produces a CLAUDE.md that covers all 15 items. Pick your stack, answer five questions, and export the result.

To measure your coverage, paste your existing CLAUDE.md into the ContextKit Analyzer. It scores you across the five categories (structure, architecture, conventions, testing, guardrails) and highlights exactly which items are missing.

Most files score between 3 and 5 out of 10 before using the checklist. After adding the missing items, scores typically jump to 7-9. The difference is measurable in fewer corrections per coding session.

For teams, run npx contextkit score in your CI pipeline. It exits with code 1 when the score drops below 5, catching regressions when someone removes rules during refactoring. The checklist is not a one-time exercise. It is a living baseline that grows as your project does.