CLAUDE.md — Project Memory

The file the agent reads before doing anything

CLAUDE.md is a markdown file Claude Code loads automatically at the start of every session. Think of it as the first message you don't have to type. Anything that's true about your project for the long term — stack, architecture, commands, conventions, hard constraints — belongs here, not in the chat.

The hierarchy: ~/.claude/CLAUDE.md (your global preferences) → repo-root CLAUDE.md (team standards) → src/.../CLAUDE.md (subdirectory-specific rules). All matching files merge into the system prompt; closer-to-cwd files take precedence on conflict. That's how you give a payments service tighter rules than the rest of the repo without copy-paste.

Bootstrap with /init: it scans the project, reads package.json / pyproject.toml / framework configs, and drafts a starting CLAUDE.md. Then iterate. Mid-session, prefix any message with # and Claude appends that fact to the appropriate CLAUDE.md — no need to context-switch into your editor.

Code

A CLAUDE.md that actually pays for itself·markdown

# myproject — CLAUDE.md

## What this is
TypeScript REST API on Node 22 + Postgres 16, deployed via Fly.io.
Frontend lives in ../myapp-frontend (separate repo).

## Standard commands
npm run dev          # localhost:3000, hot reload
npm test             # vitest
npm run db:migrate   # prisma migrate dev
npm run lint         # eslint + prettier

## Architecture
- src/routes/        Express handlers (one per resource)
- src/services/      business logic (no DB calls here)
- src/repositories/  Prisma queries (the only place DB is touched)
- src/middleware/    auth, validation, error envelope

## Conventions
- TS strict, no `any` (use `unknown` and narrow)
- async/await only, never callbacks
- Validate all inputs with Zod before processing
- Response envelope: { data, error, meta }

## Do not
- Modify schema.prisma without a migration
- Commit .env (use direnv)
- Use console.log in app code (use src/lib/logger.ts)

Subdirectory rules layered on top·markdown

# src/payments/CLAUDE.md

## Payments — additional rules
This service handles PCI-DSS regulated data. Treat everything here
as SENSITIVE.

- NEVER log card numbers, CVVs, or full PANs (debug code included)
- All encryption goes through src/lib/crypto.ts (AES-256-GCM)
- All Stripe calls go through src/clients/stripe.ts
- Rate limiting is MANDATORY on every public payment endpoint

## Verify before committing
npm run pci-check

CLAUDE.md — Project Memory

The file the agent reads before doing anything

Code

External links

Exercise

Progress

Comments 0