ai-coding-starter-kit/CLAUDE.md

AI Coding Starter Kit

A Next.js template with an AI-powered development workflow using specialized skills for Requirements, Architecture, Frontend, Backend, QA, and Deployment.

Tech Stack

• Framework: Next.js 16 (App Router), TypeScript
• Styling: Tailwind CSS + shadcn/ui (copy-paste components)
• Backend: Supabase (PostgreSQL + Auth + Storage) - optional
• Deployment: Vercel
• Validation: Zod + react-hook-form
• State: React useState / Context API

Project Structure

src/
  app/              Pages (Next.js App Router)
  components/
    ui/             shadcn/ui components (NEVER recreate these)
  hooks/            Custom React hooks
  lib/              Utilities (supabase.ts, utils.ts)
features/           Feature specifications (PROJ-X-name.md)
  INDEX.md          Feature status overview
docs/
  PRD.md            Product Requirements Document
  production/       Production guides (Sentry, security, performance)

Development Workflow

1. /requirements - Create feature spec from idea
2. /architecture - Design tech architecture (PM-friendly, no code)
3. /frontend - Build UI components (shadcn/ui first!)
4. /backend - Build APIs, database, RLS policies
5. /qa - Test against acceptance criteria + security audit
6. /deploy - Deploy to Vercel + production-ready checks

Feature Tracking

All features tracked in features/INDEX.md. Every skill reads it at start and updates it when done. Feature specs live in features/PROJ-X-name.md.

Key Conventions

• Feature IDs: PROJ-1, PROJ-2, etc. (sequential)
• Commits: feat(PROJ-X): description, fix(PROJ-X): description
• Single Responsibility: One feature per spec file
• shadcn/ui first: NEVER create custom versions of installed shadcn components
• Human-in-the-loop: All workflows have user approval checkpoints
• Tests: Unit tests co-located next to source files (useHook.test.ts next to useHook.ts). E2E tests in tests/.

Build & Test Commands

npm run dev          # Development server (localhost:3000)
npm run build        # Production build
npm run lint         # ESLint
npm run start        # Production server
npm test             # Vitest unit/integration tests
npm run test:e2e     # Playwright E2E tests
npm run test:all     # Both test suites

Product Context

@docs/PRD.md

Feature Overview

@features/INDEX.md