Writing Effective CLAUDE.md Files

# CLAUDE.md

## Project Overview
E-commerce platform built with Next.js 14 (App Router).
Static export deployed to Vercel. ~50 pages, ~200 components.
Revenue: $2M ARR. Any downtime or bugs directly impact revenue.

## Tech Stack
- Next.js 14 with App Router and static export (output: "export")
- TypeScript in strict mode — never use 'any' type
- Tailwind CSS — no CSS modules, no styled-components
- Supabase for database and auth
- Stripe for payments
- Vercel for hosting

## Directory Structure
- app/ — Next.js app router pages
- app/components/ — shared React components
- app/lib/ — utility functions and data files
- app/hooks/ — custom React hooks
- public/ — static assets
- supabase/ — database migrations and seed files

## Coding Conventions
- Functional components only, no class components
- Named exports, not default exports
- "use client" only when component needs browser APIs or state
- Components: PascalCase (UserCard.tsx)
- Utilities: camelCase (formatPrice.ts)
- Types: defined in the same file unless shared, then in app/types/
- Prefer composition over inheritance
- No barrel files (index.ts re-exports)
- Error boundaries around every page-level component

## State Management
- Server state: React Server Components (default)
- Client state: useState/useReducer for local, Zustand for global
- No Redux, no Context API for state (only for dependency injection)

## Testing
- Framework: Vitest + React Testing Library
- Run all tests: npm test
- Run single file: npx vitest path/to/file.test.ts
- Coverage: npm run test:coverage
- Every component needs a test. Every utility function needs a test.
- Test file location: co-located (Button.tsx + Button.test.tsx)

## Common Commands
- Dev: npm run dev (port 3000)
- Build: npm run build
- Lint: npm run lint
- Type check: npx tsc --noEmit
- Format: npx prettier --write .

## Important: Known Pitfalls
- The pricing logic in app/lib/pricing.ts has tax rules that vary
  by state. Do NOT simplify or refactor without understanding the
  tax implications.
- The Supabase RLS policies are critical for security. Never
  bypass them with service_role key in client-side code.
- Image optimization is disabled because we use static export.
  Use regular img tags with width/height, not next/image.
- The checkout flow has a specific order of operations that Stripe
  requires. Do not reorder the steps in CheckoutWizard.tsx.

# CLAUDE.md

## Project Overview
REST API for a healthcare scheduling platform.
Built with FastAPI + PostgreSQL. Handles PHI (Protected Health
Information) — security and HIPAA compliance are critical.

## Tech Stack
- Python 3.12 with FastAPI
- PostgreSQL 16 with SQLAlchemy ORM (async)
- Alembic for migrations
- Redis for caching and rate limiting
- Celery for background tasks
- Docker for local development and deployment

## Directory Structure
- app/ — main application code
- app/api/ — route handlers organized by domain
- app/models/ — SQLAlchemy models
- app/schemas/ — Pydantic request/response schemas
- app/services/ — business logic layer
- app/core/ — config, security, database setup
- tests/ — mirrors app/ structure
- migrations/ — Alembic migration files

## Coding Conventions
- Type hints on ALL functions (params and return types)
- Async functions for all database operations
- Business logic in services/, not in route handlers
- Route handlers only: parse request, call service, return response
- Use dependency injection for database sessions
- Pydantic models for ALL request/response validation
- Never expose internal IDs — use UUIDs in API responses

## Security Rules (CRITICAL)
- All PHI fields must be encrypted at rest (use app/core/encryption.py)
- Never log patient names, SSNs, or medical record numbers
- All endpoints require authentication except /health and /docs
- Use parameterized queries only — no string concatenation for SQL
- Rate limit all endpoints (configured in app/core/rate_limit.py)

## Testing
- Run tests: pytest
- Run with coverage: pytest --cov=app
- Fixtures in tests/conftest.py
- Use factory_boy for test data generation
- Integration tests use a real test database (Docker)

## Common Commands
- Dev server: uvicorn app.main:app --reload
- Run migrations: alembic upgrade head
- Create migration: alembic revision --autogenerate -m "description"
- Docker: docker-compose up -d
- Lint: ruff check . && ruff format --check .

# CLAUDE.md

## Project Overview
Monorepo for the Acme platform. Contains web app, mobile app,
shared component library, and backend API.

## Structure
- apps/web — Next.js web application
- apps/mobile — React Native mobile app
- apps/api — Node.js Express API
- packages/ui — shared component library (used by web and mobile)
- packages/shared — shared types, utils, and constants
- packages/config — shared ESLint, TypeScript, and Prettier configs

## Package Manager
- pnpm workspaces (DO NOT use npm or yarn)
- Install: pnpm install (from root)
- Add dependency: pnpm add -w package (root) or pnpm add package --filter @acme/web

## Cross-Package Rules
- packages/shared — NO React dependencies, pure TypeScript only
- packages/ui — React components, but no Next.js or React Native specifics
- When adding types used by multiple packages, put them in packages/shared/types/
- All packages use the shared tsconfig from packages/config

## Working in Specific Apps
- When working in apps/web, read apps/web/CLAUDE.md for web-specific conventions
- When working in apps/api, read apps/api/CLAUDE.md for API conventions
- Always check if a change affects shared packages

## Common Commands
- Dev all: pnpm dev (runs all apps concurrently)
- Dev web only: pnpm dev --filter @acme/web
- Build all: pnpm build
- Test all: pnpm test
- Lint: pnpm lint
- Type check: pnpm typecheck

# Pro tip: Ask Claude to help maintain its own instructions
> Review our CLAUDE.md and suggest improvements based on the current
  state of the codebase. Are there any conventions mentioned that we
  no longer follow? Any patterns in the code that should be documented
  but are not?

# Claude will compare the CLAUDE.md against actual code and suggest updates