What should a one-page spec include before I ask an AI to build a web app with a database, and how detailed should the d

A one-page specification for an AI coder needs to be clear about intent, boundaries, and structure, while leaving minor implementation details flexible.

Here is what that one-page spec should cover, along with how deep to go on the data model.

---

1. What the One-Page Spec Should Include

Keep it scannable using these four core sections:

• Core Purpose & MVP Scope:
  • One or two sentences on what the app does and who it is for.
  • Crucial: A brief "Out of Scope" line (e.g., "No email verification or payment processing in this version"). This stops the AI from over-engineering.
• Tech Stack & Libraries:
  • Specific choices: framework (e.g., Next.js 14 App Router, Vite + React), database/ORM (e.g., PostgreSQL with Prisma/Drizzle, or Supabase), styling (e.g., Tailwind CSS), and auth provider.
  • If you have no preference, explicitly tell the AI: "Choose the simplest, standard modern stack (e.g., Next.js + SQLite/Postgres)."
• Key User Flows & Pages:
  • Bullet out 2 to 4 primary user actions from start to finish.
  • Example: "User signs in -> sees a dashboard of their active tasks -> clicks 'New Task' modal -> submits form -> task appears instantly."
• Access Rules & Logic:
  • Who can see or edit what? (e.g., "Users can only view and mutate their own records" or "Public can read, only admin can write").

---

2. How Detailed Should the Data Model Be?

The sweet spot is high conceptual detail, not raw SQL boilerplate.

AI models are great at generating syntax, migrations, and standard fields (like id or created_at), but they are prone to guessing wrong on relationships, cardinalities, and business statuses.

What you should specify:

1. Entities & Relationships: Explicitly state how tables link (e.g., User has many Projects; Project has many Tasks).
2. Key Non-Obvious Fields & Types: Strings, numbers, booleans, and especially Enums/States (e.g., status: 'draft' | 'pending' | 'published').
3. Foreign Keys & Cascades: Note parent-child dependencies (e.g., "Deleting an organization deletes all its projects").

What you can leave to the AI:

• Exact primary key types (UUID vs. CUID vs. Auto-increment).
• Standard boilerplate (updated_at, index naming).
• Writing the actual migration script (ask the AI to generate the Prisma schema, Drizzle tables, or SQL DDL from your spec).

---

A Good Example of the Data Section in a 1-Page Spec

Instead of a vague sentence or 200 lines of SQL, aim for something like this:

Data Entities:

• users: id, email (unique), full_name, role ('admin' | 'member')
• workspaces: id, name, slug (unique), owner_id (FK -> users.id)
• workspace_members: workspace_id, user_id, joined_at
• documents: id, workspace_id (FK), title, content (text), status ('draft' | 'archived' | 'live')

Rules:

• A user can belong to multiple workspaces.
• Deleting a workspace deletes its documents.

---

Pro-Tip Before You Send It

Ask the AI to review and confirm the schema first before writing any application code:

"Here is my spec. First, output only the proposed database schema/migration and highlight any assumptions you made. Do not write frontend code yet."

This gives you a chance to catch structural misunderstandings before they ripple through the rest of the app.