scaffolding project-setup architecture boilerplate

Project Scaffolding: Starting New Projects with AI

Learn how to use AI to scaffold entire projects from scratch. From choosing architecture to generating boilerplate, this guide covers the art of AI-assisted project initialization.

· VibeWerks

Project Scaffolding: Starting New Projects with AI

Starting a new project used to mean hours of setup: choosing frameworks, configuring build tools, setting up folder structures, writing boilerplate—all before a single line of actual application code.

With vibecoding, you can collapse this setup time from hours to minutes. But speed isn’t the only benefit. AI-assisted scaffolding helps you make better architectural decisions and produces more consistent, well-structured codebases.

What you'll learn: How to have productive architecture conversations with AI, generate project scaffolds efficiently, and avoid common scaffolding mistakes.

Quick Reference

Project TypeBest ApproachTime
Standard web appFramework CLI + AI customize15 min
Custom stackFull AI scaffold30 min
Prototype/MVPAI scaffold everything10 min
Enterprise appFramework CLI + manual review1 hour

The Decision: Template vs. Custom Scaffold

Before you start, decide your approach:

Option A: Framework Templates + AI Customization

Most frameworks provide CLI tools that generate solid starting points:

# React/Next.js
npx create-next-app@latest my-app --typescript --tailwind --eslint --app

# Astro
npm create astro@latest my-site

# Python FastAPI
pip install cookiecutter
cookiecutter https://github.com/tiangolo/full-stack-fastapi-template

# Go
go mod init myapp

Then use AI to customize the template:

I just ran `npx create-next-app my-app` with TypeScript, Tailwind, and App Router.
I need to customize it:

1. Add Prisma with PostgreSQL
2. Add NextAuth.js with Google OAuth
3. Reorganize folders for a large application
4. Add a proper component library structure

Start with Prisma setup. Show me exactly what to run and what files to create.

When to use: Standard web apps, when you want battle-tested configs.

Option B: Full AI Scaffold

For custom projects or unusual stacks, have AI scaffold everything:

Create a Rust CLI tool for batch image processing:

- Clap for argument parsing
- Image crate for manipulation
- Rayon for parallel processing
- Indicatif for progress bars

Include:
- Cargo.toml with all dependencies
- src/main.rs with CLI skeleton
- src/lib.rs for core functionality
- Basic error handling with thiserror
- A README with usage examples

Make it handle: resize, convert format, and compress operations.

When to use: CLI tools, unusual stacks, highly custom projects.

The Pre-Scaffolding Conversation

This is where vibecoding shines. Before generating code, have an architectural discussion.

Step 1: Dump Your Requirements

Be comprehensive. Include constraints.

I'm building a SaaS for managing restaurant reservations.

FEATURES:
- Restaurant owners create accounts and list their restaurants
- Diners search restaurants and make reservations
- Automated email/SMS reminders
- Dashboard for managing bookings
- Stripe integration for deposits

CONSTRAINTS:
- Solo developer, bootstrap budget
- Need MVP in 6 weeks
- Mobile-responsive web (no native apps yet)
- Expect <1000 users initially, need to scale later
- I know React well, less familiar with backend patterns

What tech stack would you recommend?

Step 2: Get Options, Not Answers

Good AI responses give you options with trade-offs. If you get a single recommendation, push back:

You recommended Next.js. What about Remix or Astro? When would those be better choices?
For the database, you mentioned PostgreSQL. But we'll have complex availability
queries (overlapping time slots). Is Postgres still the right choice? What about
a time-series database?

Step 3: Challenge the Complexity

This stack has 8 different technologies. Can we simplify? What's the
minimal stack that still meets my requirements?

AI often over-engineers. Push for simplicity.

Step 4: Document the Decision

Once you’ve decided, have AI create documentation:

Create a DECISIONS.md file documenting:
1. Final tech stack with one-sentence justifications
2. Key trade-offs we discussed
3. What we deliberately chose NOT to use and why
4. Migration paths if we need to change later

Complete Scaffolding Examples

Example 1: Full-Stack Web App

Here’s a real scaffolding prompt that works:

Scaffold a Next.js 14 project for a task management SaaS.

FOLDER STRUCTURE:
/app
  /(auth)           # Login, signup, password reset
    /login/page.tsx
    /signup/page.tsx
  /(dashboard)      # Protected routes
    /layout.tsx     # Dashboard layout with sidebar
    /page.tsx       # Dashboard home
    /projects/[id]/page.tsx
  /api              # API routes
/components
  /ui               # Primitive components (Button, Input, etc.)
  /features         # Feature-specific components
/lib
  /db.ts            # Prisma client
  /auth.ts          # Auth utilities
  /utils.ts         # General utilities
/prisma
  /schema.prisma
/public
/styles

CONFIGURATION:
- TypeScript (strict mode)
- Tailwind CSS
- Prisma with SQLite (easy local dev, swap to Postgres later)
- Next-Auth with credentials provider
- ESLint + Prettier

INCLUDE:
- .env.example with all required variables
- README.md with setup instructions
- Basic User and Project models in Prisma
- One working protected page that requires auth

DON'T INCLUDE YET:
- Actual business logic
- Production database setup
- Deployment configuration

Create each file with working code. I want to run `npm install && npm run dev`
and see a working login page.

Example 2: Python API Service

Scaffold a Python FastAPI service for a URL shortener.

STRUCTURE:
/app
  /api/v1
    /endpoints
      /urls.py       # URL shortening endpoints
      /health.py     # Health check
    /router.py       # API router
  /core
    /config.py       # Pydantic settings
    /security.py     # Auth utilities (placeholder)
  /models
    /url.py          # Pydantic schemas
    /database.py     # SQLAlchemy models
  /services
    /shortener.py    # URL shortening logic
  /db
    /session.py      # Database session
  main.py            # FastAPI app

ROOT FILES:
- pyproject.toml (use Poetry)
- Dockerfile
- docker-compose.yml (app + PostgreSQL)
- Makefile with: install, dev, test, lint, format
- .env.example
- README.md with API docs

DEPENDENCIES:
- FastAPI + Uvicorn
- SQLAlchemy + asyncpg
- Pydantic Settings
- Python-dotenv
- pytest + pytest-asyncio

The shortener should:
- Accept a URL, return a short code
- Redirect short codes to original URLs
- Track click counts

Create working code. After setup I should be able to run:
`make install && make dev` and hit http://localhost:8000/docs

Example 3: CLI Tool

Scaffold a Node.js CLI tool called "quicknote" for capturing quick notes.

STRUCTURE:
/src
  /commands
    /add.ts          # Add a note
    /list.ts         # List notes
    /search.ts       # Search notes
    /delete.ts       # Delete a note
  /lib
    /storage.ts      # JSON file storage
    /formatter.ts    # Output formatting
  index.ts           # CLI entry point
/tests
  /commands
  /lib

PACKAGE.JSON:
- Name: quicknote
- bin: { "qn": "./dist/index.js" }
- Scripts: build, dev, test, lint

DEPENDENCIES:
- commander (CLI framework)
- chalk (colors)
- ora (spinners)
- conf (config/storage)

TYPE DEFINITIONS:
- Proper TypeScript throughout
- Interface for Note { id, content, tags, createdAt }

After building, I should be able to run:
- qn add "My first note" --tags work,important
- qn list
- qn search "first"
- qn delete <id>

Notes stored in ~/.quicknote/notes.json

The Incremental Scaffolding Pattern

For complex projects, don’t scaffold everything at once.

Phase 1: Minimal Viable Structure

Create the basic Next.js structure with just:
- App Router setup
- TypeScript config
- Tailwind working
- One test page at /app/page.tsx that says "Hello World"

Nothing else. I want to verify the foundation works.

Then run:

npm install
npm run dev
# Verify localhost:3000 works

Phase 2: Add Database

Add Prisma to the existing project:
1. Install dependencies
2. Create prisma/schema.prisma with a User model
3. Add db utility at /lib/db.ts
4. Add scripts to package.json
5. Update .env.example

Don't add auth yet. Just database connectivity.

Then verify:

npx prisma generate
npx prisma db push
# Check no errors

Phase 3: Add Authentication

Add NextAuth to the existing project:
1. Install next-auth
2. Create /app/api/auth/[...nextauth]/route.ts
3. Create auth config at /lib/auth.ts
4. Add middleware.ts for protected routes
5. Create a basic /app/(auth)/login/page.tsx

Use credentials provider for now. We'll add OAuth later.

Then verify:

npm run dev
# Visit /login, ensure the page loads

This approach catches errors early and keeps context manageable.

CLAUDE.md: Your Project’s AI Instructions

Create a CLAUDE.md file in your project root. AI tools like Claude Code read this automatically.

# CLAUDE.md

## Project Overview
Task management SaaS built with Next.js 14.

## Tech Stack
- **Framework:** Next.js 14 (App Router)
- **Language:** TypeScript (strict)
- **Database:** PostgreSQL via Prisma
- **Auth:** NextAuth.js with credentials + Google OAuth
- **Styling:** Tailwind CSS
- **Testing:** Vitest + Testing Library

## Commands
```bash
npm run dev      # Start development server
npm run build    # Production build
npm test         # Run tests
npm run lint     # Lint code
npm run db:push  # Push schema changes
npm run db:seed  # Seed database

Project Structure

  • /app/(auth) - Public auth pages
  • /app/(dashboard) - Protected pages
  • /app/api - API routes
  • /components/ui - Primitive UI components
  • /components/features - Feature components
  • /lib - Utilities and shared code

Conventions

  • Use server components by default
  • Client components only for interactivity
  • All API responses: { data, error } format
  • Use Zod for input validation
  • Prefer named exports

Current Focus

Building the project dashboard and task list views.

Known Issues

  • Auth session not persisting on mobile Safari
  • Need to add rate limiting to API routes

This context makes AI dramatically more helpful because it knows your patterns.

## Common Scaffolding Mistakes

### ❌ The Kitchen Sink

**Bad:**

Create a complete e-commerce platform with auth, products, cart, checkout, payments, admin panel, analytics, email, SMS, push notifications, social login, 2FA, rate limiting, caching, CDN, SEO, accessibility…


This overwhelms the AI and produces incomplete, buggy code.

**Good:** Start with the core. Add features incrementally.

### ❌ Accepting Without Understanding

**Bad:** Copy-paste AI output without reading it.

**Good:** After scaffolding, ask:

Walk me through the folder structure. Why is it organized this way? What does each key file do?


### ❌ Never Verifying Builds

**Bad:** Generate thousands of lines, then try to run them.

**Good:** After each scaffolding phase:
```bash
npm install && npm run build && npm run dev

Catch issues while context is fresh.

❌ Over-Engineering MVPs

Bad:

Set up Kubernetes, microservices, event sourcing, CQRS, GraphQL
federation, and service mesh for my todo app.

Good: Ask about right-sizing:

I'm building an MVP todo app. Should I use microservices or monolith?
What's the simplest architecture that can scale later if needed?

Post-Scaffolding Checklist

Run through this after scaffolding:

□ npm install succeeds
□ npm run build succeeds
□ npm run dev starts without errors
□ npm run lint passes (or has expected warnings)
□ npm test runs (even if no tests yet)
□ .env.example exists and is complete
□ README.md has setup instructions
□ .gitignore covers dependencies, builds, .env
□ Git initialized with initial commit
□ Can deploy (even if not deploying yet)

Quick Reference: Scaffolding Prompts by Project Type

Project TypeKey TechnologiesPrompt Focus
Web AppNext.js, Prisma, AuthFolder structure, auth flow, database models
API ServiceFastAPI/Express, ORM, DockerEndpoints, error handling, documentation
CLI ToolCommander/Click, file I/OCommands, argument parsing, output formatting
Mobile AppReact Native, ExpoNavigation, state management, native modules
Static SiteAstro, Markdown, CMSContent structure, build optimization
LibraryTypeScript, Rollup/esbuildPackage config, exports, documentation

What’s Next

Your project is scaffolded. Now learn the core rhythm of vibecoding:

Iterative Development →

The “vibe loop”: prompt, generate, review, refine. Master this and you’ll build faster than ever.

Key Takeaways

  • Discuss architecture before coding — Have a planning conversation first
  • Use framework templates — They’re battle-tested; customize with AI
  • Scaffold incrementally — Build in phases, verify each one works
  • Create CLAUDE.md — Give AI context about your project
  • Verify builds frequently — Don’t generate lots of unverified code
  • Understand what’s generated — Ask AI to explain the structure
  • Right-size for your stage — Don’t over-engineer an MVP

Good scaffolding sets you up for success. Bad scaffolding creates technical debt from day one.

Starter Templates to Try

SaaS Starter

Scaffold a SaaS starter with:
- Next.js 15 with App Router
- Tailwind CSS + shadcn/ui
- Prisma + PostgreSQL
- NextAuth with magic link login
- Stripe subscriptions
- Basic dashboard layout

API Service

Create a REST API with:
- FastAPI (Python) or Express (Node)
- PostgreSQL with an ORM
- JWT authentication
- Rate limiting
- OpenAPI documentation
- Docker Compose for local dev

Chrome Extension

Scaffold a Chrome extension with:
- Manifest V3
- TypeScript
- Popup UI with React
- Content script for page injection
- Background service worker
- Local storage for settings

🎯 Scaffold Something Now

  1. Pick a project from the starter prompts above or first project ideas
  2. Copy the scaffold prompt
  3. Customize for your needs
  4. Run it in your AI tool
  5. Build on top of it

The best way to learn scaffolding is to do it. Start a project today.

Guides:

Cheatsheets:

Practice: