project/
├── CLAUDE.md                    # Injected for everything
├── modules/
│   ├── CLAUDE.md                # Injected when reading modules/*
│   └── payments/
│       ├── CLAUDE.md            # Injected when reading modules/payments/*
│       └── lib/
│           └── CLAUDE.md        # Injected when reading modules/payments/lib/*

## API Reference
### createUser(email, name, options)
Creates a new user in the database.
Parameters:
- email: string - The user's email address
- name: string - The user's full name
- options: object - Additional options
  - sendWelcomeEmail: boolean - Whether to send welcome email
...

## How It Works
User creation flows through `UserService` which validates input, creates the DB record,
and triggers async welcome emails via the job queue.

## Why This Design
We use a job queue for emails because Stripe webhooks have a 30s timeout — synchronous
email sending caused webhook failures.

## Gotchas
- Never call `createUser` without validating email format first
- Always wrap user operations in `withTransaction()`
- Don't import from `internal/` — use public exports only

## Error Handling Pattern
try {
  const result = await service.doThing();
  return { success: true, data: result };
} catch (error) {
  logger.error('Operation failed', { error });
  return { success: false, error: error.message };
}

## Error Handling
Follow the pattern in `src/services/UserService.ts:45-60`

- Never use the --force flag

- Never use `--force`, use `--force-with-lease` instead

## Code Style
- Use 2 spaces for indentation
- Always use semicolons
- Prefer const over let
- Use single quotes for strings

# [Module Name]

[1-2 sentences: what this does and its role in the system]

## Commands
[Put runnable commands at the top — agents need these most]
- Test: `pnpm test:module-name`
- Dev: `pnpm dev`
- Lint: `pnpm lint`

## How It Works
[Architecture, data flow, key components — enough to understand the module]

## Why This Design
[Rationale, constraints, tradeoffs — helps agent make consistent decisions]

## Key Patterns
[Patterns to follow when adding code here]
[Reference canonical examples: "See `UserService.ts:45-60`"]

## Gotchas
[Things that aren't obvious and cause mistakes]
- Never [X], use [Y] instead
- [Common mistake] → [How to fix]

# MyProject

E-commerce platform for digital products.

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test`
- Build: `pnpm build`
- Lint: `pnpm lint`

## Stack
Next.js 14, TypeScript, Prisma, PostgreSQL, Stripe

## Architecture
- `src/app/` — Next.js app router pages
- `src/services/` — Business logic (each has its own CLAUDE.md)
- `src/lib/` — Shared utilities

## Conventions
- All database operations use Prisma — no raw SQL
- Environment variables in `.env.local`, never commit secrets

# Payments Module

Handles Stripe integration for subscriptions and one-time payments.

## Commands
- Test: `pnpm test:payments`
- Test watch: `pnpm test:payments --watch`

## How It Works
`PaymentService` wraps all Stripe API calls. Webhooks are processed async via
`WebhookProcessor` which validates signatures and dispatches to handlers.

## Why This Design
Stripe webhooks timeout at 30s. We immediately acknowledge and process async
to avoid retry storms. Handlers are idempotent using event ID deduplication.

## Gotchas
- Never call Stripe API directly — use `PaymentService`
- All amounts are in cents, not dollars
- Webhook handlers must be idempotent (check `processedEvents` table)

# Payments Module

## Overview
The payments module is responsible for handling all payment-related operations
in our application. It integrates with Stripe for processing credit card
payments, managing subscriptions, handling refunds, and...

[500 more lines explaining every function]

# Payments Module

- Don't call Stripe directly
- Use cents not dollars
- Handlers must be idempotent