CLAUDE.md Template That Actually Works

The Problem

You create a CLAUDE.md file in your project root. You document your stack, list conventions, add helpful context. Then you ask Claude to build a feature and it... completely ignores everything you wrote. Or worse, it reads the file but the information is so generic it doesn't help. "Use TypeScript" - Claude already knows TypeScript. "Follow best practices" - which ones?

The issue: Most CLAUDE.md files are either too vague to help or structured in a way AI can't effectively use. Context without actionable guidance is noise.

AI needs specific, project-relevant instructions: what makes YOUR codebase different, what patterns you follow that aren't universal, what mistakes to avoid.

The Core Insight

Effective CLAUDE.md files answer three questions: What is our stack? What are our specific conventions? What are our common anti-patterns? Everything else is documentation, not configuration.

Think of CLAUDE.md as a configuration file, not a README. It's not teaching AI what React is - it's teaching AI how YOUR team uses React. The more specific and actionable, the better.

The Template Structure

Section 1: Stack Declaration (Required)

Start with exact versions and key architectural decisions:

# CLAUDE.md

## Stack

**Framework:** Next.js 14 (App Router, NOT Pages Router)
**Language:** TypeScript 5.3 (strict mode enabled)
**Styling:** Tailwind CSS 3.4
**State Management:**
  - Zustand for global client state
  - React Query for server state
  - NO Redux, NO Context for state
**Database:** PostgreSQL 16 with Prisma ORM
**Auth:** Clerk
**Deployment:** Vercel
**Testing:** Vitest + Testing Library

Section 2: File Structure (Required)

Show where things go with examples:

## File Structure

```
app/
  (auth)/              # Route group for auth pages
    login/
    signup/
  (dashboard)/         # Route group for protected pages
    dashboard/
    settings/
  api/                 # API routes (use sparingly, prefer Server Actions)
components/
  ui/                  # Shadcn components (don't modify these)
  features/            # Feature-specific components
lib/
  db.ts               # Prisma client instance
  utils.ts            # Shared utilities
  types.ts            # Shared TypeScript types
```

**Key conventions:**
- Route groups for layout sharing: `(auth)`, `(dashboard)`
- Server Components by default (no 'use client' unless needed)
- UI components in `components/ui/` (from Shadcn, don't edit)
- Feature components in `components/features/[feature-name]/`

Section 3: Common Commands (Helpful)

Commands developers run frequently:

## Common Commands

```bash
# Development
npm run dev              # Start dev server (localhost:3000)
npm run build            # Production build
npm run lint             # ESLint
npm run test             # Run Vitest tests

# Database
npx prisma studio        # Open Prisma Studio
npx prisma migrate dev   # Create and apply migration
npx prisma generate      # Regenerate Prisma Client

# Deployment
git push origin main     # Auto-deploys to Vercel

# Type checking
npm run typecheck        # Run tsc --noEmit
```

**Before committing:** Always run `npm run lint` and `npm run typecheck`.

Section 4: Coding Conventions (Critical)

This is where most CLAUDE.md files fail. Be extremely specific:

## Coding Conventions

### TypeScript
- **No `any` types** - use `unknown` if type is truly unknown
- **Strict null checks** - handle null/undefined explicitly
- **Interface over type** for object shapes (team convention)
- **Zod for runtime validation** of external data (APIs, forms)

### React Patterns
- **Server Components by default** in App Router
- Use 'use client' ONLY for:
  - Event handlers (onClick, onChange, etc.)
  - Browser APIs (localStorage, window, etc.)
  - React hooks (useState, useEffect, etc.)
- **Async Server Components** for data fetching (NO useEffect for API calls)
- **Server Actions** for mutations instead of API routes when possible

### Component Organization
```typescript
// components/features/user/UserProfile.tsx
// 1. Imports
import { type User } from '@/lib/types'

// 2. Types
interface UserProfileProps {
  userId: string
}

// 3. Component
export function UserProfile({ userId }: UserProfileProps) {
  // Component implementation
}
```

### Naming Conventions
- **Files:** PascalCase for components (`UserProfile.tsx`), camelCase for utils (`formatDate.ts`)
- **Components:** PascalCase (`UserProfile`)
- **Functions:** camelCase (`formatUserName`)
- **Constants:** SCREAMING_SNAKE_CASE (`MAX_RETRIES`)
- **Types/Interfaces:** PascalCase with descriptive names (`UserProfileData`, not `IUserProfile` or `UserProfileType`)

Section 5: Anti-Patterns (Critical)

Tell AI what NOT to do:

## Anti-Patterns (DO NOT DO THESE)

### Next.js App Router
- ❌ **DON'T** use `getServerSideProps` or `getStaticProps` (Pages Router only)
- ❌ **DON'T** import from `next/router` (use `next/navigation` instead)
- ❌ **DON'T** create API routes for Server Component data (fetch directly)
- ❌ **DON'T** use 'use client' at the top level unless necessary

### State Management
- ❌ **DON'T** use Context API for global state (use Zustand)
- ❌ **DON'T** use Redux (we migrated away from it)
- ❌ **DON'T** fetch in useEffect (use React Query or Server Components)

### Database
- ❌ **DON'T** write raw SQL (use Prisma)
- ❌ **DON'T** create migrations manually (use `prisma migrate dev`)
- ❌ **DON'T** modify Prisma Client types (they're generated)

### TypeScript
- ❌ **DON'T** use `any` (use `unknown` or proper types)
- ❌ **DON'T** use `@ts-ignore` (fix the type error)
- ❌ **DON'T** use enums (use const objects with `as const`)

### General
- ❌ **DON'T** install new dependencies without asking
- ❌ **DON'T** modify files in `components/ui/` (Shadcn managed)
- ❌ **DON'T** commit to main (use feature branches)

Real-World Examples

Example: Rails Monolith

# CLAUDE.md

## Stack
- **Framework:** Ruby on Rails 7.1
- **Ruby:** 3.3.0
- **Database:** PostgreSQL 16
- **Frontend:** Hotwire (Turbo + Stimulus)
- **CSS:** Tailwind CSS
- **Testing:** RSpec + Capybara

## Conventions

### Model Layer
- Fat models, skinny controllers
- Use concerns for shared behavior (`app/models/concerns/`)
- Scopes for common queries
- Validations in model, not database
- Use `find_by!` (raises) over `find_by` (returns nil)

### Controller Layer
```ruby
# Standard controller action structure:
class PostsController < ApplicationController
  before_action :authenticate_user!
  before_action :set_post, only: [:show, :edit, :update, :destroy]

  def index
    @posts = Post.all
  end

  private

  def set_post
    @post = Post.find_by!(slug: params[:id])
  end

  def post_params
    params.require(:post).permit(:title, :content)
  end
end
```

### Service Objects
- Use for complex business logic
- Location: `app/services/[domain]/[action]_service.rb`
- Example: `app/services/posts/publish_service.rb`

### Hotwire Patterns
- Use Turbo Frames for partial page updates
- Use Turbo Streams for live updates
- Stimulus controllers for client-side interactions only
- Keep Stimulus controllers small (< 100 lines)

## Anti-Patterns
- ❌ **DON'T** put logic in views
- ❌ **DON'T** use `find()` (use `find_by!` for error handling)
- ❌ **DON'T** skip validations with `save(validate: false)`
- ❌ **DON'T** write raw SQL (use ActiveRecord)
- ❌ **DON'T** use callbacks for business logic (use service objects)

Example: Vanilla JS Site

# CLAUDE.md

## Stack
- **No framework** - vanilla HTML/CSS/JavaScript
- **No build step** - edit and refresh
- **Target:** Modern browsers only (no IE11)
- **Deploy:** AWS S3 + CloudFront

## Structure
```
index.html           # Main landing page
about.html
contact.html
styles.css           # Single stylesheet, organized by component
script.js            # Main JS file
assets/
  images/
  fonts/
```

## Conventions

### HTML
- Semantic HTML5 elements (`
`, `
`, `

Maintenance Tips

Keep It Updated

Your CLAUDE.md should evolve with your codebase:

# Add to your pull request template:
- [ ] Update CLAUDE.md if this PR introduces new patterns or conventions

Test It

Periodically ask Claude to build something and see if it follows conventions:

# Test prompt:
"Build a new user profile page following the patterns in CLAUDE.md"

# Review the output:
- Did it use the right stack?
- Did it follow file structure?
- Did it avoid anti-patterns?
- If no, update CLAUDE.md to be more explicit

# CLAUDE.md

## Stack
[Framework + version]
[Language + version]
[Key libraries with versions]
[Deployment platform]

## File Structure
[Directory layout with explanations]

## Conventions
[How we use the stack differently]
[Naming patterns]
[Code organization]

## Common Commands
[Dev, test, build, deploy]

## Anti-Patterns
[What NOT to do]
[Deprecated patterns we migrated from]