Back to Workflows
Claude Code SaaS Workflow
Production-ready AI coding workflow for Next.js SaaS projects using Claude Code, Cursor and modern repo standards.
Overview
This workflow is designed for AI-assisted SaaS development using:
Next.js App RouterTypeScriptTailwind CSSSupabaseStripeClaude CodeCursor
The goal is to keep AI-generated code predictable, maintainable and consistent across long-term projects.
Recommended Repo Structure
Feature-based architecture prevents AI tools from generating duplicated logic and inconsistent folder structures.
/app /(marketing) /(dashboard) /api /components /ui /shared /features /auth /billing /dashboard /settings /lib /db /stripe /auth /utils /prompts /rules /tests memory.md rules.md
Architecture Principles
Feature-First Structure
Each business feature owns:
- components
- hooks
- actions
- schemas
- tests
Avoid global business logic.
Server-First Architecture
Prefer:
- Server Components
- Server Actions
- async data fetching on server
Avoid unnecessary client-side state.
Shared UI Layer
Reusable UI primitives belong inside /components/ui
Business-specific UI belongs inside /features/*
rules.md
# AI Coding Rules ## Architecture - Use feature-based architecture - Keep business logic inside features/ - Shared UI belongs inside /components/ui - Avoid global utilities unless reusable --- ## React - Prefer Server Components by default - Use Client Components only for interactivity - Never fetch directly inside client components - Avoid unnecessary useEffect usage --- ## API - Prefer Server Actions over REST APIs - Keep route handlers thin - Centralize validation schemas --- ## Components - Keep components under 200 lines - Prefer composition over abstraction - Avoid deeply nested props --- ## Naming - Use explicit names - Avoid generic folders like helpers/, misc/, temp/ - Use feature-oriented naming --- ## Styling - Use Tailwind utilities - Reuse shared UI primitives - Avoid duplicated utility patterns --- ## State Management - Prefer server state - Avoid unnecessary global state - Keep local state isolated --- ## Performance - Avoid unnecessary client bundles - Lazy load heavy components - Prefer streaming when possible --- ## Code Quality - Avoid duplicated hooks - Avoid duplicated validation logic - Keep functions focused and small
memory.md
# Project Memory ## Stack - Next.js App Router - TypeScript - Tailwind CSS - Supabase - Stripe --- ## Architecture - Feature-first structure - Server Components by default - Shared UI primitives - Minimal client-side state --- ## Important Constraints - Never fetch inside client components - Never create duplicated hooks - Never create duplicate folder structures - Avoid introducing alternative architecture patterns --- ## UI Rules - Reuse shared UI primitives - Keep spacing consistent - Avoid inline styles - Prefer accessibility-first components --- ## Testing Standards - Use React Testing Library - Test user behavior - Avoid snapshot-heavy tests --- ## Code Style - Prefer readability over abstractions - Keep components composable - Prefer explicit naming
File Organization Standards
Feature Structure
/features/auth /components /hooks /actions /schemas /tests
Shared UI
/components/ui contains:
buttonsinputsdialogscardstables
Shared Logic
/lib contains:
database clientsauth helpersintegrationsutilities
Prompt Workflow
Generate New Feature
Generate a new dashboard feature following the existing project architecture.
Requirements:
- Use feature-based folder structure
- Prefer Server Components
- Reuse shared UI components
- Add loading states
- Add error states
- Keep components small and composable
Refactor Existing Feature
Refactor this feature without changing business logic.
Requirements:
- Remove duplicated logic
- Improve readability
- Keep server-first architecture
- Preserve folder structure
- Reuse existing patterns
Generate Tests
Generate tests following existing testing standards.
Requirements:
- Use React Testing Library
- Prefer user behavior testing
- Avoid snapshots
- Cover loading states
- Cover error states
AI Constraints
- Never create duplicate folder structures
- Never fetch directly inside client components
- Never introduce new UI patterns without reuse
- Avoid unnecessary abstractions
- Avoid giant utility files
- Keep feature boundaries strict
- Prefer explicit naming over generic naming
- Avoid business logic inside shared components
Testing Workflow
All AI-generated features must include:
- loading states
- error states
- empty states
- accessibility checks
- unit tests
Testing Stack
React Testing LibraryVitestPlaywright
Testing Rules
- Test behavior instead of implementation
- Avoid excessive mocking
- Prefer integration-style tests
Pull Request Workflow
Before merging AI-generated code:
- Check for duplicated logic
- Check for duplicated hooks
- Verify folder consistency
- Verify naming consistency
- Ensure tests are included
- Ensure server-first architecture is preserved
PR Guidelines
- Keep PRs focused
- Avoid mixed concerns
- Prefer incremental refactors
- Keep PRs under 300 LOC when possible
Before Applying Workflow Standards
- duplicated hooks
- mixed server/client logic
- inconsistent folder structures
- large components
- duplicated utility files
- scattered business logic
- predictable architecture
- reusable UI patterns
- cleaner AI-generated code
- smaller components
- consistent folder structure
- easier long-term maintenance
Recommended Stack
Frontend
Next.js App RouterTailwind CSSshadcn/ui
Backend
SupabasePostgreSQL
Payments
Stripe
Deployment
Vercel
AI Tools
Claude CodeCursor
Workflow Goals
This workflow is designed to:
- reduce inconsistent AI output
- improve long-term maintainability
- keep repo structure predictable
- improve AI-assisted collaboration
- reduce duplicated logic
- scale AI coding across teams
Copy This Workflow
Save these files to your repo and reference them in your AI tool configuration.