How to Write a Spec an AI App Builder Can Actually Ship

AI app builders can now produce a working full-stack app from a description. The catch is the description. "Build me a CRM" gets you a pretty demo with fake data. A short, structured spec gets you something close to a real product.

Here's the spec format that consistently produces usable Next.js apps on the first or second try.

Why vague prompts fail

An AI builder has to make hundreds of decisions: data model, auth, routes, validation, empty states. Every decision you leave out, it guesses. Guesses compound. By the time you notice the data model is wrong, three screens are built on top of it.

A spec doesn't need to be long. It needs to answer the questions the builder would otherwise guess.

The one-page spec

1. One sentence on who it's for and what they do

A booking tool for independent yoga teachers to publish class times and let students reserve a spot.

This single line decides tone, layout and which features matter.

2. Users and roles

List each role and what it can do:

• Teacher: creates classes, sees bookings, cancels classes.
• Student: browses classes, books, cancels own booking.
• No admin panel in v1.

Saying what's out of scope is just as useful as what's in.

3. Data model in plain words

Teacher has many Classes. Class has title, start time, duration, capacity, price. Student has many Bookings. Booking belongs to one Class and one Student; status is booked or cancelled.

You don't need SQL. Nouns, relationships and key fields are enough for the builder to produce a sane schema.

4. The three to five core flows

Write each as steps:

1. Student opens a teacher's public page, sees upcoming classes.
2. Student picks a class, signs in with email, confirms booking.
3. Teacher sees the booking count update on their dashboard.

If a flow isn't listed, assume it won't be built well.

5. Rules and edge cases

This is where most generated apps break:

• A class can't be booked past capacity.
• A student can't book the same class twice.
• Cancelling within 12 hours of start is not allowed.
• All times are shown in the viewer's timezone.

6. Stack and integrations

If you have preferences, state them: Next.js App Router, Postgres, email magic-link auth, Stripe Checkout for paid classes. If you don't, say "use sensible defaults" so the builder doesn't invent something unusual.

7. What "done" looks like

Done when a teacher can create a class and a student can book and cancel it end to end, with capacity enforced.

This gives the builder, and you, a clear test.

Iterate in small steps

After the first build, resist rewriting the whole spec. Ask for one change at a time:

• "Add a waitlist when a class is full."
• "Send the teacher an email when a booking is cancelled."

Small requests keep the existing structure intact. Big rewrites tend to regenerate working parts and break them.

Check the boring parts

Before you show anyone the app, test:

• Empty states (no classes yet).
• Error states (payment declined, invalid input).
• A second account, to confirm users can't see each other's data.

These are the places AI-generated code is most likely to cut corners.

A template to copy

Product: [one sentence]
Roles: [role: can do X, Y; out of scope: Z]
Data: [nouns, relationships, key fields]
Core flows: [3 to 5 numbered flows]
Rules: [limits, permissions, edge cases]
Stack: [preferences or "sensible defaults"]
Done when: [one end-to-end test]

Where to try it

Paste the template into any AI app builder. If you want a full-stack Next.js app with database and auth generated from a spec like this, Massvai is an AI full-stack app builder built for exactly that workflow.

The better your spec, the less you fight the generator. One page of clear decisions beats fifty follow-up prompts.