Module 10 · Lesson 04

CLAUDE.md — Teaching Claude About Your Project

Reading time: 18 minutes Track: Claude Fluency for Teams · Developer path

What CLAUDE.md is

CLAUDE.md is a special file that Claude Code reads at the start of every session. It's your way of giving Claude persistent context about your project — the information that would take a new developer days to absorb.

Without a CLAUDE.md, every Claude Code session starts cold. Claude has to re-learn your architecture, your conventions, your tech stack, and your constraints from scratch. A good CLAUDE.md eliminates that overhead.

Claude Code automatically reads CLAUDE.md files at these locations:

• Project root (/CLAUDE.md): Main project context
• Subdirectory (/src/CLAUDE.md, etc.): Subsystem-specific context
• Home directory (~/.claude/CLAUDE.md): Personal preferences that apply globally

What to put in CLAUDE.md

1. Project overview (2-3 sentences)

What does this project do? Who uses it? What's the main technology and architecture pattern?

# Project Overview
This is a B2B SaaS application for construction project management.
Backend: Node.js/Express REST API with PostgreSQL. Frontend: React + TypeScript.
We use a monorepo with workspaces: /packages/api, /packages/web, /packages/shared.

2. Tech stack and key dependencies

List the major dependencies and any non-obvious choices. Don't list everything — focus on what Claude needs to make correct decisions.

# Tech Stack
- Node 20, TypeScript 5.x (strict mode)
- PostgreSQL 15 with Drizzle ORM (NOT Prisma — we migrated in 2025)
- React 19, Vite, TailwindCSS
- Vitest for unit tests, Playwright for e2e
- Deployed on Railway; CI via GitHub Actions

3. Architecture and structure

Key directories and what lives where. Any non-standard patterns.

# Structure
/packages/api/src/
  routes/    — Express route handlers (thin layer, logic in services)
  services/  — Business logic (thick layer, unit-tested)
  db/        — Drizzle schema and migrations
  middleware/ — Auth, rate limiting, error handling

All database access goes through services. Routes never query the DB directly.

4. Development conventions

The things a new developer gets wrong until someone tells them. Code style, naming patterns, testing requirements.

# Conventions
- Functions: camelCase. Files: kebab-case. Types/Classes: PascalCase.
- Every new service function needs a corresponding unit test.
- Error handling: always throw typed errors (see /shared/errors.ts), never strings.
- Async: async/await throughout, no callback patterns.
- We use conventional commits: feat:, fix:, chore:, docs:

5. What NOT to do (common mistakes)

This is often the most valuable section. Document the footguns.

# Do Not Do These Things
- Do NOT use console.log — use our logger (import { logger } from '@/lib/logger')
- Do NOT write raw SQL — use Drizzle ORM
- Do NOT add dependencies without checking with the team — we're intentionally lean
- Do NOT commit .env files — they're gitignored, check .env.example for required vars

6. Running and testing

How to run the project locally, run tests, common dev commands.

# Running Locally
npm run dev         — start both api and web in watch mode
npm run test        — run all unit tests
npm run test:e2e    — run Playwright tests (requires local DB)
npm run db:migrate  — run pending migrations
npm run db:studio   — open Drizzle Studio (DB browser)

Keeping CLAUDE.md current

CLAUDE.md rots if you don't maintain it. Two practices help:

1. Update it when conventions change. If you migrate to a new ORM, update the file that day. Stale CLAUDE.md is worse than no CLAUDE.md because it actively misleads Claude.

2. Ask Claude to suggest updates. At the end of a session where you made significant architectural decisions: "Based on what we just built, what should we add or update in CLAUDE.md?"

A template to start from

Create CLAUDE.md in your project root with these sections and fill them in:

# [Project Name]

## Overview
[2-3 sentences: what it is, who uses it, main tech]

## Tech Stack
[Key technologies and versions]

## Structure
[Key directories and what lives where]

## Conventions
[Naming, testing, error handling, code style]

## Do Not Do
[Common mistakes and footguns]

## Running the Project
[How to start, test, build]