Project Template

Every project gets the same foundation. This is the CLAUDE.md template, the folder structure, and the design setup we use across 40+ projects.

CLAUDE.md Template

This file goes in the root of every project. It's the first thing Claude reads when you start a session in that directory.

# Project Name

Brief description of what this project does.

## Tech Stack
- Next.js (latest stable, App Router)
- Tailwind CSS 4 with shadcn/ui
- Convex for database/backend
- Vercel for hosting

## Development
- Run `npm run dev` for Next.js dev server
- Run `npx convex dev` for Convex in development mode
- Local dev server runs on port XXXX

## Commands
- `vercel` - Deploy to Vercel
- `npx convex deploy` - Deploy Convex functions

## Project Structure
- `/app` - Next.js App Router pages and layouts
- `/components` - React components
- `/components/ui` - shadcn/ui primitives
- `/convex` - Convex schema, queries, mutations
- `/lib` - Utilities and shared logic
- `/docs` - Project documentation, changelog, progress logs
- `/public` - Static assets

## Documentation
- Always update `docs/changelog.md` when committing features or fixes
- Write build logs and decisions to `docs/progress/{date}_{time}--{slug}.md`
- Keep documentation in-app under the /docs route

## Design
- Theme generated with tweakcn
- [Include your theme details here]

What Makes a Good CLAUDE.md

  • Short and scannable - Claude reads this every session. Don't write an essay.
  • Commands first - The most useful thing is knowing how to run, build, and deploy.
  • Stack declaration - Prevents Claude from suggesting incompatible libraries.
  • Project structure - Helps Claude find things without exploring.
  • Conventions - Documentation habits, naming patterns, anything you want enforced.

Folder Structure

The standard starting structure for a new project:

project-root/
  app/                    # Next.js App Router
    layout.tsx           # Root layout
    page.tsx             # Home page
    globals.css          # Tailwind imports + theme
    docs/                # In-app documentation route
      layout.tsx
      page.tsx
      changelog/
        page.tsx         # Renders docs/changelog.md
  components/
    ui/                  # shadcn/ui components
  convex/
    schema.ts            # Database schema
    _generated/          # Auto-generated types
  lib/
    utils.ts             # cn() helper and utilities
  docs/                  # Working documentation (source files)
    changelog.md
    progress/            # One file per session/decision/review
      2026-02-03_1400--initial-scaffold.md
      2026-02-03_1900--chose-convex-over-supabase.md
  public/                # Static assets
  context/               # Handoff documents (gitignored)
  CLAUDE.md              # Agent instructions
  .gitignore
  package.json

Design Setup with tweakcn

tweakcn is a visual theme editor for shadcn/ui. Instead of manually tweaking CSS variables, you design your theme visually and get an npx command to apply it.

The Workflow

  1. Go to tweakcn.com and design your theme
  2. Customize colors, border radius, fonts, spacing
  3. Copy the CSS variables or the npx command it generates
  4. Tell Claude: "Apply this theme to my project" and paste the CSS or command

Example: Applying a Theme

Here's my theme from tweakcn. Apply it to my project:

[paste the CSS variables or npx command here]

Update globals.css with these theme variables.

Claude will update your globals.css with the new CSS custom properties, handling both light and dark mode variants.

What tweakcn Gives You

  • Color palette (primary, secondary, accent, destructive, etc.)
  • Border radius values
  • CSS variables for both light and dark mode
  • Compatible with all shadcn/ui components out of the box

The .gitignore

Make sure these are in your .gitignore:

# Dependencies
node_modules/

# Environment
.env
.env.local
.envrc

# Claude Code working files
context/

# Build
.next/
out/

# OS
.DS_Store

The important additions beyond a standard Next.js gitignore:

  • .envrc - Credential file managed by your deployment tooling
  • context/ - Handoff documents are ephemeral, not part of the codebase

Scaffolding a New Project

Here's the prompt to give Claude when starting from scratch:

Create a new Next.js project with:
- App Router
- Tailwind CSS 4
- TypeScript
- shadcn/ui (install with npx shadcn@latest init)
- Create a CLAUDE.md with our standard template
- Create docs/changelog.md and docs/devlog.md
- Set up the folder structure for components, lib, convex
- Set the dev server to port [YOUR_PORT]
- Apply this theme from tweakcn: [paste theme]

And for adding Convex:

Add Convex to this project:
- npx convex init
- Create a basic schema.ts
- Set up the ConvexProvider in the root layout
- Add convex dev and deploy commands to CLAUDE.md