Claude Code CLAUDE.md — Best Practices Template

Tech Stack

• TypeScript, Next.js 14 (App Router), Tailwind CSS, Prisma ORM
• Testing: Vitest + Playwright
• Package manager: pnpm

Coding Conventions

• Use functional components with TypeScript interfaces
• Prefer named exports
• Use server components by default, "use client" only when needed
• Error handling: try/catch with proper error types, never swallow errors

File Structure

• app/ — Next.js app router pages and layouts
• components/ — Reusable UI components (PascalCase.tsx)
• lib/ — Utilities, API clients, helpers
• types/ — Shared TypeScript types

Testing Requirements

• Run pnpm test after any code changes
• Write tests for new functions (vitest)
• E2E tests for user-facing flows (playwright)

Git Workflow

• Branch naming: feature/, fix/, refactor/*
• Commit messages: conventional commits (feat:, fix:, refactor:)
• Never force push to main

Do NOT

• Modify files in /vendor/ or /generated/
• Add dependencies without asking
• Create .env files or hardcode secrets
• Add comments to obvious code

## What is CLAUDE.md?

CLAUDE.md is a project-level configuration file that tells Claude Code how to work in your codebase. It is the equivalent of `.cursorrules` for Cursor — project-specific AI instructions that improve code quality, enforce conventions, and reduce hallucination. Claude Code reads CLAUDE.md automatically from your project root and any parent directories.

**Answer-Ready**: CLAUDE.md is the project config file for Claude Code. Defines tech stack, coding conventions, testing requirements, and constraints. Claude Code reads it automatically. Equivalent of .cursorrules for Cursor. Essential for consistent AI-generated code.

**Best for**: Any team using Claude Code for development. **Works with**: Claude Code (all versions). **Setup time**: Under 5 minutes.

## Template Sections

### 1. Project Overview

```markdown

## Project

Brief description of what this project does.
Deployed at: https://example.com
Repo: github.com/org/repo

2. Tech Stack & Architecture

## Stack

- Frontend: React 19, Next.js 15, Tailwind CSS
- Backend: Python 3.12, FastAPI, SQLAlchemy
- Database: PostgreSQL 16
- Cache: Redis 7
- Deploy: Docker + AWS ECS

3. Commands

## Commands

- `pnpm dev` — Start dev server
- `pnpm test` — Run unit tests
- `pnpm lint` — Lint + format check
- `pnpm build` — Production build
- `pnpm db:migrate` — Run database migrations

4. Conventions

## Conventions

- Use absolute imports (@/components/Button)
- Prefer Zod for runtime validation
- API routes return { data, error } shape
- Use date-fns for date operations (not moment)

5. Constraints (Critical)

## Do NOT

- Modify the auth middleware without review
- Add new npm dependencies without discussion
- Write to the /public directory at runtime
- Use any environment variable not in .env.example

Multi-Level CLAUDE.md

Claude Code reads CLAUDE.md from multiple locations:

~/.claude/CLAUDE.md              # Global (all projects)
~/projects/CLAUDE.md             # Workspace level
~/projects/my-app/CLAUDE.md      # Project level (highest priority)
~/projects/my-app/src/CLAUDE.md  # Subdirectory level

Best Practices

1. Start small — 20-30 lines covering the essentials
2. Be specific — "Use date-fns" beats "use a date library"
3. Include commands — Claude Code runs tests/lint automatically
4. Update regularly — CLAUDE.md should evolve with your codebase
5. Add constraints — Tell Claude what NOT to do
6. Keep it DRY — Don't repeat what is obvious from package.json

FAQ

Q: Where should I put CLAUDE.md? A: Project root. Claude Code also reads from parent directories and ~/.claude/CLAUDE.md for global settings.

Q: How long should it be? A: 30-100 lines is the sweet spot. Too short lacks context, too long wastes context window.

Q: Does it work with Cursor too? A: No, Cursor uses .cursorrules. But the concept is identical — you can maintain both with similar content.

Q: Can I use it for team standardization? A: Yes, commit CLAUDE.md to git. All team members get the same AI behavior.