Rules & Config
CLAUDE.md
Project-level memory file that tells Claude Code your stack, conventions, and commands every session
What these rules do
CLAUDE.md is a markdown file at your project root that Claude Code reads at the start of every session. Without it, Claude guesses your stack, your conventions, and your test commands from scratch each time. With a configured CLAUDE.md, Claude follows your team's patterns from the first prompt and runs your actual build and test commands instead of generic defaults.
The file loads automatically. No setup beyond creating it and committing it to your repo.
The config
# Project
TypeScript React application using Next.js 14 App Router with Tailwind CSS and Prisma ORM.
## Commands
- `npm run dev` - Start dev server on port 3000
- `npm run build` - Production build
- `npm test` - Run Vitest unit tests
- `npm run test:e2e` - Run Playwright end-to-end tests
- `npm run lint` - ESLint + Prettier check
- `npm run db:migrate` - Run Prisma migrations
- `npm run db:seed` - Seed development database
## Architecture
- `/app` - Next.js App Router pages, layouts, and API routes
- `/components` - React components organized by feature
- `/lib` - Shared utilities, hooks, and type definitions
- `/prisma` - Database schema and migrations
- `/tests` - E2E test files (unit tests colocate with source)
## Conventions
- TypeScript strict mode. No `any` types. Use `unknown` and narrow.
- Named exports only. No default exports.
- Error handling uses Result<T, E> pattern for business logic. Try/catch only at API boundaries.
- React components use functional style with hooks. No class components.
- API routes validate input with Zod schemas before processing.
- Commit messages follow Conventional Commits format.
## Do Not
- Never commit .env files or hardcode secrets in source
- Never use barrel files (index.ts re-exports)
- Never mock internal modules in tests. Mock external services only.
- Never modify `/lib/auth/` without running the full e2e suite first
## When Unsure
- For Stripe integration details, read docs/stripe-guide.md
- For auth flow details, read docs/authentication.md
- For deployment, read docs/deploy-runbook.mdLine by line
Project Section
A single sentence naming your stack. Claude uses this to make framework-aware decisions from the first prompt. Without it, Claude infers the stack from file extensions and package.json, which works but costs a few seconds of orientation on every session.
Commands Section
The highest-value section in any CLAUDE.md. When Claude needs to verify its work, it runs these exact commands. Inaccurate or missing commands mean Claude either guesses wrong or asks you every time. Listing db:migrate and db:seed separately prevents Claude from running migrations in the wrong order during setup.
Architecture Section
Tells Claude where files belong so it creates new files in the right directories and structures imports correctly. The note about colocated unit tests prevents Claude from building a parallel /tests/unit/ tree when your convention is test files next to their source.
Conventions Section
These rules prevent the most common AI coding mistakes in TypeScript projects. The “no any types” rule alone eliminates roughly 40% of the type safety issues in AI-generated TypeScript. The Result pattern rule prevents Claude from wrapping everything in try/catch, which is its default behavior without guidance. Zod validation at API boundaries stops Claude from writing unvalidated request handlers.
Do Not Section
Negative rules are more effective than positive ones for LLMs. Claude remembers “never do X” more reliably than “prefer Y.” The auth module restriction exists because authentication code has the highest blast radius in most applications. One broken change in auth can cascade into session failures across the entire app.
When Unsure Section
This replaces embedding long reference docs directly in CLAUDE.md. Instead of importing 500 lines of Stripe integration notes into every session, Claude reads the referenced file only when it encounters a Stripe-related task. This keeps the always-loaded context lean and saves roughly 2,000 tokens per session compared to inlining the content.
Adapt it for your team
Adapting for Code Review Workflows
Add a Review Standards section below Conventions that tells Claude what to flag during code review. These rules integrate with the /code-review skill. When the skill runs, it reads your CLAUDE.md and includes these standards in its review criteria alongside its default checks.
## Review Standards
- Flag any function longer than 50 lines
- Flag any file with more than 3 levels of nesting
- Flag missing error handling on async operations
- Flag hardcoded values that should be environment variables
- Check that new API routes have Zod input validationAdapting for Python Projects
Replace the TypeScript-specific sections with your Python toolchain. The structure stays the same. Commands first, architecture second, conventions third.
## Conventions
- Python 3.12+. Type hints on all function signatures.
- Formatting with Ruff. Do not add Black or isort separately.
- Tests with pytest and fixtures. No unittest.TestCase.
- Imports absolute only. No relative imports across packages.If you use uv instead of pip, specify that in the Commands section so Claude stops generating pip install commands.
Adapting for Monorepos
Place a root CLAUDE.md with shared conventions and the top-level commands. Add per-package CLAUDE.md files in each workspace directory with package-specific overrides. Claude loads the root file at session start and picks up package-level files on demand when you work in those directories.
# Root CLAUDE.md
## Commands
- `pnpm -r test` - Run all package tests from root
- `pnpm -r build` - Build all packages
## Rules
- Changes to /packages/shared/ must not break dependent packages
- Run root-level tests after any cross-package changePer-package instructions override the root where they conflict. More specific rules always take precedence.
Frequently Asked Questions
In your project root directory, next to package.json or pyproject.toml. Claude Code detects it automatically when you start a session. You can also place a global CLAUDE.md at ~/.claude/CLAUDE.md for preferences that apply across all projects, like your personal coding style or editor conventions.
Under 200 lines. Every line consumes context tokens on every session, and instruction adherence drops as the file grows. Most effective CLAUDE.md files run 50 to 100 lines. If yours grows past 200, move detailed reference material into .claude/rules/ files or separate docs that Claude reads on demand.
Cursor uses .cursorrules and Windsurf uses .windsurfrules. The formats are similar but loaded differently. AGENTS.md is a cross-tool standard that Claude Code, Codex, and others all read. You can import AGENTS.md into CLAUDE.md with a single line to maintain one source of truth across tools.
Code style rules that a linter or formatter already enforces. If ESLint handles semicolons and Prettier handles indentation, repeating those rules wastes context tokens and can conflict with the deterministic tool. Personality instructions like 'be a senior engineer' also add no measurable improvement. Save space for project-specific conventions and commands.