The AIDD Framework

Workshop AI-Driven Development — Session 1

4 hours

From idea to working prototype with a rigorous methodology

Session Agenda

4 intensive hours

Part 1 — Lecture (1h30)

  • Vibe coding vs AIDD
  • The AIDD framework
  • Advanced prompt engineering
  • Tools & ecosystem

Part 2 — Lab (2h30)

  • Environment setup
  • Specs & vision.md
  • Full-stack scaffolding
  • 3 features + auth + deploy

Vibe Coding vs AI-Driven Development

The difference between “it works” and “it’s well built”

Vibe CodingAIDD
Approach“Build me an app”Specs → Plan → Execute → Test
PromptsVague, one-shotStructured, contextual, iterative
QualityIt compiles = good enoughTests, review, architecture
Debugging“Fix this” in a loopRoot cause analysis, stack traces
ResultThrowaway prototypeMaintainable & deployable code

Workshop goal: give you a methodology so that AI makes you 10x more productive, not 10x more dangerous.

The AIDD Framework

6 steps for each feature — repeat for every issue

YOU decide (1-3) AI executes (4) — YOU verify (5-6) 1 Discover Read code & context 2 Plan Specs & criteria 3 Review Check before code 4 Execute CRAFT → code 5 Commit Message & push 6 Test Verify & edges repeat for each feature

Golden rule: never merge code you don’t understand. The AI proposes, the engineer decides.

Technical Specifications

The vision.md: your contract with the AI

vision.md

  • Project name & description
  • Chosen tech stack
  • Architecture (pages, API, DB)
  • Prioritized user stories
  • Non-functional constraints

Architecture Decision

  • Why Next.js vs something else?
  • Database: SQL, NoSQL, JSON?
  • Auth: Firebase, NextAuth, custom?
  • Hosting: Vercel, AWS, other?
  • Documented trade-offs

User Stories

  • Format: As a [who], I want [what], so that [why]
  • Precise acceptance criteria
  • MoSCoW priority
  • 1 story = 1 GitHub Issue
  • Estimated by complexity (S/M/L)

Writing AI-Ready User Stories

The spec IS the prompt — vague specs = vague code

BAD — Too vague for AI “As a user, I want to manage my tasks” ✗ No acceptance criteria ✗ No technical constraints ✗ No definition of “manage” ✗ No expected behavior on error → AI will guess everything. You’ll spend more time fixing than you saved. GOOD — AI-executable spec Title: Create task with title, priority, due date As a logged-in user, I want to create a task to track work Acceptance criteria: ✓ Form: title (required), description, priority, due date ✓ Validation: title min 3 chars, due date future ✓ Submit: save to Firestore user collection, toast ✓ Error: message below form, keep fields ✓ Redirect to /dashboard on success Technical notes: File: src/app/dashboard/new/page.tsx Stack: React client + Firestore Type: Task { id, title, priority, dueDate, ... }

From User Story to GitHub Issue

Each issue is a self-contained instruction for the AI

## Create task with title, priority, due date

**As a** logged-in user
**I want to** create a task with details
**So that** I can track my work

### Acceptance Criteria
- [ ] Form: title (required, min 3 chars),
      description (optional), priority
      (high/medium/low select), due date (future)
- [ ] Save to Firestore: `tasks/{taskId}`
      with userId from AuthContext
- [ ] Show success toast, redirect to /dashboard
- [ ] On validation error: red text below field
- [ ] On Firestore error: generic error message

### Technical Notes
- File: `src/app/dashboard/new/page.tsx`
- "use client", Tailwind, existing Task type
- Use `addDoc` from firebase/firestore
- Priority badge colors: high=red, med=yellow, low=green

Why this format works for AI

  • Checkbox criteria — each is independently verifiable
  • File path — AI knows exactly where to write
  • Type reference — AI uses correct types, no guessing
  • Error behavior — defined, not left to AI imagination
  • Visual details — colors, layout prevent follow-up iterations

Rule of thumb: if the AI needs to ask “what should happen when...”, your spec is incomplete.

Task Decomposition for AI

Break features into atomic, AI-sized tasks

Feature: Task Management Issue #1: Create Task 1 file: src/app/dashboard/new/page.tsx ✓ Form with validation ✓ Save to Firestore ✓ Error handling ✓ Success redirect 1 prompt = 1 complete feature ~25 min with AI Issue #2: List & Filter 2 files: TaskList.tsx + TaskFilters.tsx ✓ Display user’s tasks ✓ Filter by priority & status ✓ Search by title ✓ Empty state message Depends on Issue #1 (needs data) ~20 min with AI Issue #3: Authentication 3 files: login, register, AuthContext ✓ Login page + error handling ✓ Register page ✓ Route protection ✓ Redirect logic Can be done in parallel with #1 ~25 min with AI

Advanced Prompt Engineering

The CRAFT framework

C — Context

Stack, project state, existing files, conventions. The richer the context, the better the result.

R — Requirement

What you want precisely. Paste the GitHub issue, acceptance criteria, mockups.

A — Action

The concrete action: create a file, modify a function, add a component. One verb, one object.

F — Format

The expected output format: TypeScript, React component, API route, Jest test. Be explicit.

T — Test

How to verify: expected behavior, edge cases, what must NOT happen.

CRAFT Prompt Example

Structured prompt vs vague prompt

Context: Next.js 14 + TypeScript + Tailwind project.
Auth via Firebase.
Existing file: src/lib/firebase.ts (config initialized).
Layout: src/app/layout.tsx with AuthProvider.

Requirement: Create an email/password login page
with:
- Email + password fields with validation
- "Sign in" button + "Create an account" link
- Firebase error handling
  (wrong-password, user-not-found)

Action: Create src/app/login/page.tsx

Format: React client component ("use client"),
Tailwind for styling,
signInWithEmailAndPassword from Firebase.

Test: The user can sign in and is redirected
to /dashboard. On error, a red message appears
below the form.

Bad: “Add a login form”

Good: structured CRAFT prompt →

Each section of the prompt has a role:

  • Context — what already exists
  • Requirement — what we want
  • Action — which file to create
  • Format — technical constraints
  • Test — how to verify

AI Development Tools

Choosing the right tool for the right task

ToolStrengthsIdeal Use
Claude CodeLong context, reasoning, refactoringArchitecture, complex features, debugging
CursorIDE-integrated, file context, fastContinuous editing, completion, inline changes
GitHub CopilotFast autocompletion, patternsBoilerplate, standard implementations
ChatGPT / Claude.aiFree conversation, explorationDesign, brainstorming, concept explanation
v0 / BoltFull UI generationRapid component prototyping

For this workshop: we will mainly use Cursor or Claude Code for development.

Workshop Tech Stack

The tools we will use today

Frontend

  • Next.js 14+ — Full-stack React framework
  • TypeScript — Static typing
  • Tailwind CSS — Utility-first styling

Backend & Data

  • API Routes — Next.js endpoints
  • Firebase — Auth + Firestore
  • Prisma or JSON — Depending on the project

DevOps

  • Git + GitHub — Versioning + issues
  • Vercel — Continuous deployment
  • ESLint — Code quality

Feature Workflow

The lifecycle of a feature with AIDD

1 GitHub Issue — User story with clear acceptance criteria
2 Git Branchfeature/feature-name
3 CRAFT Prompt — Context + requirement + action + format + test
4 Code Review — Read the generated code, understand every line
5 Manual Test — Verify in the browser, test edge cases
6 Commit & Push — Descriptive message, reference the issue (closes #3)
7 Deploy — Automatic Vercel deploy on push

Discipline: 1 feature = 1 branch = 1 PR. No catch-all commits.

Scaffolding with AI

Start a project in 5 minutes

Initialize the project

npx create-next-app@latest mon-projet --typescript --tailwind --app --eslint
cd mon-projet
git init && git add . && git commit -m "initial scaffold"

This command creates a complete Next.js 14 project with TypeScript, Tailwind CSS, ESLint, and the App Router. Everything is ready to go.

Scaffolding Prompt

Ask the AI to create the structure

Here is my vision.md: [paste contents]

Create the following file structure:
- src/app/page.tsx (home page)
- src/app/layout.tsx (header/footer layout)
- src/components/Header.tsx
- src/components/Footer.tsx
- src/lib/firebase.ts (Firebase config)

Use strict TypeScript, Tailwind CSS,
and Next.js 14 App Router conventions.

Why this works

  • The vision.md provides global context
  • The file list is precise
  • The conventions are explicit

Tip: including the vision.md gives the AI a big-picture view for consistent decisions.

Firebase Authentication

Step 1: Configuration

// src/lib/firebase.ts
import { initializeApp } from 'firebase/app';
import { getAuth } from 'firebase/auth';
import { getFirestore } from 'firebase/firestore';

const app = initializeApp({
  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
  authDomain: process.env.NEXT_PUBLIC_...,
  projectId: process.env.NEXT_PUBLIC_...,
  // ...
});

export const auth = getAuth(app);
export const db = getFirestore(app);

Single file

All Firebase config in src/lib/firebase.ts. Other files import auth and db from here.

Security: all keys in .env.local, never hardcoded. File in .gitignore by default.

Firebase Authentication

Step 2: AuthProvider & hook

// src/contexts/AuthContext.tsx
"use client";
import { createContext, useContext,
         useEffect, useState } from 'react';
import { onAuthStateChanged, User }
  from 'firebase/auth';
import { auth } from '@/lib/firebase';

const AuthContext = createContext<{
  user: User | null;
  loading: boolean;
}>({ user: null, loading: true });

React Context Pattern

  • "use client" — required for React hooks
  • onAuthStateChanged — Firebase listener that tracks auth state
  • The context exposes user and loading

Prompt tip: ask the AI to create the complete AuthProvider with the useAuth() hook and route protection.

Continuous Deployment with Vercel

From commit to live site in 60 seconds

Setup (once)

  1. Create a vercel.com account
  2. “Import Project” from GitHub
  3. Configure environment variables
  4. Deploy — your app is live!

Continuous Workflow

  1. Code a feature locally
  2. git push origin main
  3. Vercel builds automatically
  4. Preview URL for each PR

Engineer advantage: every push creates a preview deployment. You can showcase your progress at any time.

Git: Conventional Commits

Commit messages that make sense

feat: add login page with Firebase auth
fix: handle wrong-password error on login
refactor: extract AuthProvider to context
docs: add API documentation to README
test: add unit tests for auth helpers

Format

type: short imperative description

  • feat — new feature
  • fix — bug fix
  • refactor — restructuring without behavior change
  • docs / test / style — non-functional

Forbidden: git add . without reviewing, git push --force, “WIP” commits.

Git: Branching Strategy

1 feature = 1 branch = 1 PR — never commit directly to main

main init merge PR #1 merge PR #2 merge fix feature/login add form validation error UX PR feature/tasks CRUD filters tests PR fix/auth-bug fix + test PR main (stable) feature branch hotfix branch

Iterating with AI

The art of technical conversation

First prompt

Initial structured request using CRAFT. The AI generates a first version.

Review & feedback

“The code works but I want the form to validate the email client-side before submit. Also add a loading state on the button.”

Refine

“The loading state is good. However, the error message should disappear when the user starts typing again.”

Rule: each iteration must be specific. No “improve the code.” Say exactly what is missing or wrong.

When AI Gets It Wrong

Recognizing and correcting AI errors

Common Hallucinations

  • Non-existent or deprecated APIs
  • Made-up npm packages
  • Syntax from an older version
  • Incorrect imports

How to React

  • Read the error in the terminal
  • Copy the exact message into the prompt
  • Specify the version: “I’m using Next.js 14, not 12”
  • Check the official docs if in doubt

Red Flags

  • The AI loops on the same fix
  • The code is too complex for the task
  • You don’t understand what the code does
  • 3+ attempts with no progress = stop

Next.js App Architecture

Recommended project structure

mon-projet/
├── src/
│   ├── app/                    # App Router (pages & API)
│   │   ├── layout.tsx          # Main layout
│   │   ├── page.tsx            # Home page
│   │   ├── login/page.tsx      # Login page
│   │   ├── dashboard/page.tsx  # Protected page
│   │   └── api/                # API routes
│   │       └── tasks/route.ts  # CRUD tasks
│   ├── components/             # Reusable components
│   │   ├── Header.tsx
│   │   ├── Footer.tsx
│   │   └── TaskCard.tsx
│   ├── contexts/               # React Contexts
│   │   └── AuthContext.tsx
│   ├── lib/                    # Utilities
│   │   ├── firebase.ts
│   │   └── utils.ts
│   └── types/                  # TypeScript types
│       └── index.ts
├── public/                     # Static assets
├── .env.local                  # Environment variables
├── vision.md                   # Project specifications
└── package.json

You are the director, AI is the actor

The right mindset for AI-assisted development

Your Role (Director)

  • Define what to build
  • Make architecture decisions
  • Validate code quality
  • Understand every line
  • Decide when to cut / iterate

AI’s Role (Actor)

  • Write code according to your specs
  • Propose implementations
  • Generate boilerplate
  • Help with debugging
  • Suggest improvements

Classic trap: letting the AI make architecture decisions. That is your responsibility as an engineer, not the AI’s.

Generated Code Quality

Engineer checklist before each commit

Readability

  • Clear variable/function names
  • No dead or commented-out code
  • Short functions (< 30 lines)
  • Separation of concerns

Security

  • No hardcoded secrets in the code
  • User input validation
  • No SQL injection / XSS
  • Environment variables for API keys

Performance

  • No unnecessary re-renders
  • Optimized DB queries
  • Optimized images (next/image)
  • Lazy loading where needed

Ready for the lab?

Checklist before getting started

Required Setup

  • Node.js 18+ installed
  • Git configured
  • VS Code + Cursor or Claude Code
  • GitHub account
  • Vercel account
  • Firebase account (Google)

What you will build

  • A full-stack Next.js app
  • 3 features minimum
  • Firebase authentication
  • Deployed on Vercel
  • Following the AIDD workflow
  • In 2h30

Head to the lab → practical-work-1-guided-project.html

Slide Overview