Every time you start a new Claude Code session, Claude begins with zero context about your project. Without a CLAUDE.md file, you spend the first 10-15 minutes of every session re-explaining your architecture, coding conventions, file structure, and business context. With a well-crafted CLAUDE.md, Claude picks up exactly where you left off — knowing your folder structure, your preferred patterns, your Pakistani client context, and the specific tools and APIs in your stack. This lesson teaches you to write CLAUDE.md files that make Claude dramatically more effective from the very first message.

Section 1: What CLAUDE.md Is and How It Works

CLAUDE.md is a Markdown file placed in your project's root directory. When you run claude in a project folder, Claude automatically reads CLAUDE.md before responding to any message. It serves as persistent memory that survives across sessions.

Claude also reads CLAUDE.md files in subdirectories — this is useful for monorepos where different parts of the codebase have different conventions. A backend CLAUDE.md can specify FastAPI patterns while a frontend CLAUDE.md specifies Next.js conventions.

The hierarchy:

/project-root/
  CLAUDE.md          <- Global project context (read in every session)
  /backend/
    CLAUDE.md        <- Backend-specific conventions
  /frontend/
    CLAUDE.md        <- Frontend-specific conventions
  /tests/
    CLAUDE.md        <- Testing conventions and patterns

Section 2: The Anatomy of a Great CLAUDE.md

A professional CLAUDE.md covers seven sections:

1. Project Overview (2-4 sentences): What does this project do? Who uses it? What is the business context? Include Pakistani context where relevant.

## Project Overview
This is a WhatsApp chatbot API for Karachi restaurant chains. It handles
order intake, customer queries, and reservation management via WATI's
WhatsApp Business API. The system serves 12 restaurant clients, processes
~500 messages/day, and integrates with each restaurant's POS system.

2. Tech Stack (Bulleted list): Every technology, framework, library, and version in use. Claude uses this to generate correct imports, avoid deprecated APIs, and suggest compatible packages.

## Tech Stack
- Python 3.12, FastAPI 0.115, Pydantic v2
- SQLite (development), PostgreSQL 16 (production)
- WATI WhatsApp API (webhook endpoint: /webhook/wati)
- Claude Sonnet via Anthropic SDK (not OpenAI)
- Deployed on: Contabo VPS, Ubuntu 24.04, Docker + Nginx

3. Architecture & File Structure: The most important section. Claude needs to know where things live to make edits without creating duplicate files or misplacing new code.

## Architecture
├── main.py              — FastAPI app entry point
├── routers/             — API endpoints (one file per domain)
│   ├── webhook.py       — WATI webhook receiver
│   └── admin.py         — Restaurant admin endpoints
├── services/            — Business logic (no HTTP, no DB)
│   ├── message_router.py— Routes messages to correct handler
│   └── order_processor.py
├── models/              — SQLAlchemy ORM models
├── db.py                — Database session management
└── .env                 — Loaded by python-dotenv, NEVER committed

4. Coding Conventions: Patterns Claude must follow. Without this, Claude may introduce inconsistencies that break your code style or worse, your CI checks.

## Conventions
- All database operations go in services/ — never in routers/
- Use Pydantic models for ALL request/response validation
- Errors: raise HTTPException with detail dict, never plain strings
- Logging: use structlog, not print() — logger.info("event", key=value)
- Tests: pytest, fixtures in conftest.py, all test files prefix with test_
- Never use f-strings for SQL — always use parameterized queries

5. Key Commands: The commands Claude should know to run tests, start the server, deploy, etc.

## Commands
- Run dev server: `uvicorn main:app --reload --port 8000`
- Run tests: `pytest tests/ -v --cov=app`
- Deploy: `docker-compose up -d --build` (auto-deploys to Contabo)
- DB migration: `alembic upgrade head`

6. Current Work (Updated Frequently): What are you currently building? What decisions were recently made? What's broken? This section is your session handoff note.

## Current Work (updated 2026-03-26)
- Building: order confirmation flow (message_router.py -> order_processor.py)
- Decided: Use Redis for session state (not SQLite — too slow for concurrent users)
- Known issue: WATI webhook signatures not verified (security TODO)
- Next session: Add JWT auth to /admin endpoints

7. Do Not Touch (Critical for Agency Work): Files or patterns Claude must never modify without explicit instruction.

## Do Not Touch
- migrations/ — never edit manually, always use `alembic revision --autogenerate`
- .env — never print, log, or commit values from this file
- The existing webhook signature format — clients depend on this structure

Section 3: CLAUDE.md vs README.md — Know the Difference

Many beginners confuse CLAUDE.md with README.md. They serve completely different audiences and purposes. Here is the breakdown:

README.md is for humans. It tells a new developer (or a GitHub visitor) what the project does, how to install it, and how to contribute. It is public-facing documentation.

CLAUDE.md is for Claude. It tells Claude Code how to behave inside your project — what conventions to follow, what files to avoid, what your current work is, and what patterns you enforce. It is an instruction manual for your AI pair programmer.

A real-world example: your README.md might say "This is a WhatsApp chatbot for restaurants" while your CLAUDE.md says "All message handlers go in services/handlers/ — never create a new handler file in routers/. Use structlog for logging, not print(). The WATI webhook format must not change — 12 restaurant clients depend on the current payload shape."

Pro tip for Pakistani freelancers: If you are building projects for Upwork/Fiverr clients, keep a clean README.md for the client handoff but maintain a detailed CLAUDE.md for your own development speed. The client never needs to see your CLAUDE.md — it is your private productivity tool.

Section 4: How CLAUDE.md Files Cascade in a Monorepo

When you work on large projects with multiple apps or services in one repository, CLAUDE.md files cascade from root to subdirectory. Claude reads them top-down, and subdirectory files override or extend the root file. Here is how it works visually:

 MONOREPO ROOT
 ┌─────────────────────────────────────────────────────┐
 │  CLAUDE.md  (root)                                  │
 │  - "Use TypeScript strict mode everywhere"          │
 │  - "All commits must be conventional commits"       │
 │  - "Never commit .env files"                        │
 │  - "Currency: PKR, Payment: JazzCash/EasyPaisa"     │
 ├─────────────────────────────────────────────────────┤
 │                                                     │
 │  ┌──────────────────────┐  ┌──────────────────────┐ │
 │  │  frontend/           │  │  backend/            │ │
 │  │  CLAUDE.md           │  │  CLAUDE.md           │ │
 │  │  - "Next.js 15"      │  │  - "FastAPI 0.115"   │ │
 │  │  - "Tailwind v4"     │  │  - "Pydantic v2"     │ │
 │  │  - "No default       │  │  - "All DB ops in    │ │
 │  │    exports"          │  │    services/"        │ │
 │  │  - "Framer Motion    │  │  - "structlog, not   │ │
 │  │    for animations"   │  │    print()"          │ │
 │  └──────────────────────┘  └──────────────────────┘ │
 │                                                     │
 │  ┌──────────────────────┐  ┌──────────────────────┐ │
 │  │  mobile/             │  │  shared/             │ │
 │  │  CLAUDE.md           │  │  CLAUDE.md           │ │
 │  │  - "React Native"    │  │  - "Shared types     │ │
 │  │  - "Expo SDK 52"     │  │    only — no logic"  │ │
 │  │  - "NativeWind for   │  │  - "Export all types │ │
 │  │    styling"          │  │    from index.ts"    │ │
 │  └──────────────────────┘  └──────────────────────┘ │
 └─────────────────────────────────────────────────────┘

 WHAT CLAUDE SEES when editing backend/services/order.py:
   1. Root CLAUDE.md    -> "TypeScript strict, conventional commits, PKR"
   2. backend/CLAUDE.md -> "FastAPI, Pydantic v2, structlog"
   (Both applied. Backend rules ADD to root rules.)

The key insight: root-level rules apply everywhere, and subdirectory rules add specificity. You never need to repeat root-level conventions in subdirectory files. If your root says "never commit .env files," that rule applies in every subdirectory automatically.

Section 5: Pakistan Case Study — 0213 Solutions, Karachi

Background: 0213 Solutions is a 4-person digital agency in Karachi's I.I. Chundrigar Road area. They build WhatsApp bots, Shopify stores, and SEO audits for local businesses — restaurants, clinics, and retail shops across Clifton, DHA, and Saddar. Their lead developer, working solo on 6 client projects simultaneously, was spending 15-20 minutes at the start of every Claude Code session re-explaining project context.

The problem: With 6 active client projects, each session started with messages like "This is the WhatsApp bot for Cafe Aylanto, it uses WATI API, the webhook is at /webhook/wati, we use FastAPI, the database is SQLite, the payment integration is JazzCash..." Every. Single. Time.

The fix: They created a CLAUDE.md for each client project. Here is what the WhatsApp bot CLAUDE.md included:

• Project Overview: "WhatsApp ordering bot for 3 Karachi restaurant chains (Cafe Aylanto, Kolachi, BBQ Tonight). WATI Business API. ~500 messages/day."
• Tech Stack: Python 3.12, FastAPI, SQLite, WATI API, JazzCash payment callbacks
• Architecture: Full file tree with every service, router, and model file listed
• Conventions: "All menu prices in PKR. Never hardcode restaurant names — use config.RESTAURANT_NAME. All WhatsApp templates must be WATI-approved before deploy."
• Current Work: Updated after every session with what was built, what broke, and what is next
• Do Not Touch: "Never modify the WATI webhook payload format — all 3 restaurants have live integrations depending on the current structure"

The result after 4 weeks:

• Session startup time dropped from 15 minutes to under 30 seconds
• Claude stopped suggesting OpenAI SDK (the CLAUDE.md specified Anthropic SDK)
• Zero incidents of Claude accidentally modifying webhook formats
• The developer estimated saving 15+ hours per week across all 6 projects
• Client delivery speed increased — they took on 2 additional clients the following month

The takeaway: For Pakistani freelancers juggling multiple client projects on Upwork or Fiverr, a CLAUDE.md per project is not optional — it is a competitive advantage. Your competitors are wasting 15 minutes per session. You are shipping code in 30 seconds.

Section 6: Common CLAUDE.md Mistakes

Even experienced developers make these mistakes when writing CLAUDE.md files. Here is a table of the most common ones and how to fix them:

Exercise 1: Write a CLAUDE.md for your most recent project (or a project you have been working on throughout this course). Include all 7 sections. Make it specific — not "uses Python" but "Python 3.12 with FastAPI 0.115." Not "stores data" but "SQLite in development, PostgreSQL 16 in production with 3 tables: users, sessions, messages."

Exercise 2: Open a new Claude Code session in your project directory (without telling Claude anything). Ask Claude: "What is this project? What's the tech stack? What should I be working on?" Compare Claude's answers to what you wrote in CLAUDE.md. If Claude misses anything, the CLAUDE.md section for that topic needs more detail.

Exercise 3: Add a Pakistani business context section to your CLAUDE.md. Write 2-3 sentences explaining: who the end users are (Pakistani freelancers, Karachi restaurant owners, etc.), what currency and payment methods are involved (PKR, JazzCash, EasyPaisa), and any local compliance or cultural considerations. This makes Claude's suggestions and generated copy dramatically more relevant to your actual users.

Exercise 4: Take a monorepo or multi-folder project and create a cascading CLAUDE.md setup. Write a root CLAUDE.md with global conventions (commit style, language, security rules). Then create at least two subdirectory CLAUDE.md files with specific conventions for each part of the codebase. Start a Claude Code session inside one of the subdirectories and verify that Claude knows both the root rules and the subdirectory rules by asking: "What conventions should I follow when writing code in this directory?" If Claude only knows one level, your cascade structure needs adjustment.

Key Takeaways

• CLAUDE.md survives across sessions — it is your project's "brain handoff" document that prevents Claude from starting every session with zero context
• The architecture and file structure section is the most important — it prevents Claude from creating duplicate files, misplacing new code, or breaking existing patterns
• The "Current Work" section should be updated at the end of every session — treat it as your own project journal as much as Claude's memory file
• Subdirectory CLAUDE.md files allow different conventions for different parts of a monorepo — a powerful pattern for large projects with mixed tech stacks
• CLAUDE.md is for Claude, README.md is for humans — never confuse the two, and never skip CLAUDE.md just because you have a good README
• Pakistani freelancers managing multiple Upwork/Fiverr client projects should maintain a separate CLAUDE.md per project — the 15+ hours/week saved is a real competitive edge
• Always include Pakistani business context (PKR, JazzCash/EasyPaisa, local audience) so Claude generates locally relevant code, copy, and pricing instead of defaulting to USD and Stripe
• The "Do Not Touch" section is critical for agency work — one accidental edit to a live webhook format or migration file can break client integrations and cost you the contract
• Keep your CLAUDE.md lean and direct — it is an instruction manual, not a blog post. If it exceeds 200 lines, split it into cascading subdirectory files