CLAUDE.md Template Collection

Ready-to-use CLAUDE.md templates you can copy and paste. Pick the one that fits your project and overwrite the file generated by /init, or edit it directly.

💡 CLAUDE.md works best when it's short. The longer it gets, the more likely Claude is to start ignoring the rules. Keep the root to 50–100 lines and split details into per-folder CLAUDE.md files.

---

Template 1 — Next.js + Supabase (Typingroom baseline)

# Project Name

## Stack
- Next.js App Router, TypeScript
- Supabase (DB + Edge Functions)
- Zustand (state management), TanStack Query (async)

## Common Commands
- Dev server: `npm run dev`
- Build: `npm run build`
- Type check: `npm run type-check`
- Supabase local: `supabase start`

## Coding Rules
- Language: TypeScript strict mode
- Components: functional, arrow functions
- Styling: Tailwind CSS
- Hook return values: unified as { data, isLoading, error }

## Supabase Rules
- Client: use createClientComponentClient() from @/lib/supabase.ts
- Do NOT use the @supabase/ssr package
- Edge Function: Deno runtime, ESM imports, Deno.env.get()
- RLS: must be enabled for all new tables

## Do Not Touch
- .env, .env.local
- supabase/migrations/ (migrations require separate discussion)

## Workflow Rules
- Read TODO.md at the start of each session to understand current state
- Update TODO.md after each feature is completed
- Log important technical decisions in the TODO.md notes section with a date

---

Template 2 — General Node.js / Express API

# Project Name API

## Stack
- Node.js 20+, TypeScript
- Express.js
- PostgreSQL + Prisma ORM

## Common Commands
- Dev server: `npm run dev`
- Build: `npm run build`
- DB migration: `npx prisma migrate dev`
- Test: `npm run test`

## Coding Rules
- Language: TypeScript strict
- Package manager: pnpm (do not use npm or yarn)
- Route file location: src/routes/
- Error handling: always use try-catch, pass errors via next(err)

## IMPORTANT: Never Do This
- Do not modify .env files
- Do not modify Prisma schema directly (use migration files only)
- Use the logger module instead of console.log

---

Template 3 — React Component Library

# Component Library

## Stack
- React 18, TypeScript
- Storybook
- Vitest + Testing Library

## Common Commands
- Storybook: `npm run storybook`
- Test: `npm run test`
- Build: `npm run build`

## Component Rules
- File structure: ComponentName/index.tsx + ComponentName.stories.tsx + ComponentName.test.tsx
- Props types: must be explicitly typed; optional props must have default values
- Exports: use named exports (no default exports)

## Style Rules
- CSS-in-JS: styled-components
- Design tokens: refer to src/tokens/
- Responsive: mobile-first

## YOU MUST: Include a Storybook story file for every component

---

Per-Folder CLAUDE.md Templates

These are intended to be split out from the root CLAUDE.md and placed inside the relevant folder.

/supabase/CLAUDE.md

# Supabase Folder Rules

## Edge Functions
- Runtime: Deno (not Node.js)
- Imports: ESM, npm: prefix
- Environment variables: Deno.env.get()
- File location: supabase/functions/[function-name]/index.ts

## Migrations
- Create files with: `supabase migration new [name]`
- Do not create SQL files manually

## RLS
- New tables: must ENABLE ROW LEVEL SECURITY
- Policy naming: [table]_[action]_[role] format

/src/features/auth/CLAUDE.md

# Auth Domain Rules

## Authentication Method
- Use Supabase Auth
- JWT is managed by Supabase (do not parse directly)
- Session check: supabase.auth.getSession()

## File Structure (FSD)
- UI: features/auth/ui/
- API hooks: features/auth/api/
- Types: features/auth/model/types.ts

## IMPORTANT
- Do not store auth tokens directly in localStorage
- Never print passwords to logs