CLAUDE.md — Your Project's AI Constitution

What CLAUDE.md actually does

CLAUDE.md loads at the start of every session, giving Claude persistent context without spending any conversation history on it. It's the difference between re-explaining your project on every fresh start and Claude simply already knowing your conventions, architecture, and preferences.

Anatomy of an effective CLAUDE.md

A strong file is organized into focused sections: what the system is, what it's built with, how to write code in it, how git works here, what to do on every change, and how to compact a long session. Concrete and actionable beats long and vague every time.

# Project: PaymentAPI

## Architecture
- Monorepo with packages/api, packages/worker, packages/shared
- PostgreSQL (primary) + Redis (cache/queues)
- REST API with Express, BullMQ for background jobs

## Tech Stack & Preferences
- TypeScript strict mode throughout — no `any` types
- Zod for all runtime validation (never raw type assertions)
- Prisma ORM — always use transactions for multi-table writes
- Jest + Supertest for testing — minimum 80% coverage per PR

## Coding Conventions
- Functions < 40 lines; extract helpers if longer
- Errors: always use our AppError class from packages/shared/errors
- Logging: use our structured logger, never console.log in production code
- Environment variables: validate at startup using our config schema

## Git Workflow
- Conventional commits: feat/fix/chore/docs/test/refactor
- No commits to main — always PR through staging
- PR descriptions: use the template in .github/pull_request_template.md

## When Making Changes
- Run `npm test` after every change set
- Check types with `npm run typecheck` before committing
- Never modify migration files — create new ones

## Compact Instructions
When compacting, preserve: architecture decisions, current task context,
any decisions made about approach, file paths of files being modified.

Don't skip: The Compact Instructions section is what keeps long sessions coherent — it tells Claude what must survive when the context window is summarized.

The loading hierarchy

Claude loads CLAUDE.md files in order, from broadest to most specific. Nested files can override or extend their parents — ideal for a monorepo where conventions differ by package.

Path-specific rules with .claude/rules/

For conventions that only apply to certain files, drop them into .claude/rules/. Each rule activates automatically when Claude edits a matching path — powerful in large codebases where different modules follow different conventions.

.claude/rules/
  api-routes.md       # Rules that apply when editing src/api/
  migrations.md       # Rules that apply when editing db/migrations/
  tests.md            # Rules that apply when editing *.test.ts files

Org-wide deployment

Teams want one source of truth for standards. There are three common ways to share a CLAUDE.md across every repo in an organization:

What NOT to put in CLAUDE.md

Try it: Write a CLAUDE.md for a real project, then test it — start a fresh session, ask Claude to implement a small feature, and check whether it follows your conventions without any reminders.

Related tutorials

• Skills — Repeatable Workflows — the on-demand counterpart to always-on CLAUDE.md context.
• Hooks — Automating Claude's Actions — enforce rules programmatically alongside CLAUDE.md.
• Browse the full Claude Code tutorial series.

CLAUDE.md FAQ