The one-page spec to write before you prompt an AI to code

You have your idea, you’ve opened your favorite AI tool, and you type straight away: “build me an app that…”. That’s the best way to get something that looks like what you wanted without actually being it. The fix fits on one page, gets written before you open the AI, and takes fifteen minutes. Here’s how to build it.

Why one page changes everything

An engineer writing about technical specs put it well: the cheapest place to make a decision is in the document, not in code you’ve already written. Reversing a choice before you’ve typed a line costs two minutes; reversing it after the AI has built ten files around it costs a full rewrite. Writing the spec upfront forces you to face the questions that would otherwise surface too late.

An article specifically about prompting AI coding tools sums up why most tasks fail: unclear scope, hidden constraints, undefined interfaces, a “done” that means nothing precise to anyone. A one-page spec exists exactly to stop the AI from filling in those blanks with its own assumptions. Anthropic’s own documentation for Claude Code, its command-line coding tool, points the same way: it recommends naming the files and interfaces involved, stating what’s explicitly out of scope, and ending with a way to verify the result, before letting the AI write anything at all.

The 6 sections of your mini spec

You don’t need a ten-page document. Six short sections are enough for a student project: a thesis tool, something for your club, an association, or a personal project.

• Problem: what concrete problem this project solves, in 2-3 sentences. Not the solution, the problem.
• Users: who’s going to use it. One type of user if possible for a first version; trying to satisfy everyone from day one is the surest way to satisfy no one.
• MVP features: the strict minimum needed for the tool to actually be useful. MVP stands for “minimum viable product”: the simplest version that genuinely works, not the one with every idea you had in the shower.
• Data: what information the app stores, and who can see it. Asking this now saves you a bad surprise later (the article on this blog about securing a vibe-coded app details what can go wrong if you skip this).
• Screens: the list of the 3 to 5 main screens, in the order the user sees them. No need for a mockup, a bullet list is enough.
• Acceptance criteria: how you’ll know each feature genuinely works. And, most importantly, what’s explicitly out of scope for this version — that last line prevents the most drift.

The template to copy

# Spec — [project name]

## Problem
[What concrete problem does this project solve? 2-3 sentences,
without describing the solution.]

## Users
[Who will use it? One type of user if possible for version 1.]

## MVP features
- [Must-have feature 1]
- [Must-have feature 2]
- [Must-have feature 3]
(Everything else waits for version 2: list it anyway, under a
"Later" section, so you don't forget it without mixing it into
the MVP.)

## Data
[What information does the app store? Who can see it?
Is any of it personal data?]

## Screens
[List the 3 to 5 main screens, in the order the user sees them.]

## Acceptance criteria
- [How do you know feature 1 genuinely works?]
- [How do you know feature 2 genuinely works?]
- [What's explicitly out of scope for this version.]

Fill it in within fifteen minutes, without hunting for the perfect wording. If some boxes still say “to be decided” or “maybe,” that’s the sign the question needs settling now, not while the AI is writing code.

How to use it with an AI coding tool

Once the page is filled in, paste it as-is into your conversation with whichever AI tool you’re using (Claude Code, Cursor, Lovable, it doesn’t matter), and explicitly ask for a plan before any code:

Here's my spec: [paste the document].
Before writing any code, propose a plan that breaks this
project into small steps. Also tell me if you see anything
vague or any question I haven't actually settled.

GitHub’s own documentation for Copilot recommends the same logic from the other direction: start with a general description of the goal, then list the precise requirements, and break a complex task into several simple ones rather than asking for everything at once. A spec does that breakdown work for you, once and for all, instead of redoing it in every message.

What if the project changes along the way?

A spec isn’t set in stone. It’s normal to update it once you start seeing your project take shape and new ideas show up. The good habit isn’t rewriting everything each time, but adding new ideas to a “Later” section instead of mixing them into the MVP features mid-stream: that’s exactly what derails a project, one feature at a time. If a change touches a decision you’d already settled (say, the type of user, or what data gets stored), update that section and explicitly flag it to the AI in your next message, rather than letting it guess that something changed.

What it actually prevents

Without this step, the same three problems keep coming back: the AI assumes a type of user you never had in mind, it builds an “extra” feature you never asked for that complicates everything, or it declares the project “done” while the one case you actually cared about doesn’t work. A one-page spec doesn’t guarantee a perfect project, but it turns a vague conversation into something you can point at and say “build exactly that.”

If the project is graded coursework, keep this page in your files: it shows that the thinking about the problem and the design choices came from you, even if the AI helped write the code afterward. Also check your institution’s own AI usage rules before using this for graded work.

Key takeaways

• Writing a page before coding costs fifteen minutes and saves hours of rework: decisions are cheaper to make in a document than in code that’s already been written.
• Six sections are enough: problem, users, MVP features, data, screens, acceptance criteria.
• The last section (what’s out of scope) is the one that prevents the most drift.
• Paste your spec into your conversation with the AI and ask for a plan before any code.
• Keep this page if the project is graded: it documents your own thinking, independent of the AI.

The full template, with filled-in examples, is available in the cahier-des-charges-vibe skill.