Write a project spec an AI can build from
A spec is the most valuable thing you write in AI-assisted development. Learn a simple template, write a full spec for the Brew & Bean website, let AI interview and review it, and turn it into a plan.
In this tutorial you will write a one-page spec for the Brew & Bean coffee shop website that you build in the next module. You will use a template, ask AI to find the gaps in your spec, and then turn the spec into a plan of small tasks.
Prerequisites: you have read *The AI coding workflow: spec, plan, build, review*, and you have a free chat assistant (see *Set up your machine*). No coding is needed here. This lesson is writing.
What a spec is, and what it is not
A spec (specification) is a short written description of what you are building. It is not a long document or a formal contract. For a small project it is one page. Its job is to put your decisions in writing so the AI does not make them for you, and so you can later check the result against something.
Spec versus prompt versus plan
| Item | What it is | When you use it |
|---|---|---|
| Spec | What and why: goal, features, limits, data | Once at the start, updated as you learn |
| Plan | In what order: a list of small tasks | After the spec, before coding |
| Prompt | One request to the AI for one task | Many times, each one quoting the relevant part of the spec |
The spec template
Use these headings. Every one earns its place.
Parts of a spec
| Section | Question it answers | Typical mistake |
|---|---|---|
| Goal | What is this for, in one or two sentences? | Too vague ("a nice website") |
| Users | Who uses it and on what device? | Forgetting phones |
| Features | What must it do? Numbered and specific | Listing ideas instead of must-haves |
| Out of scope | What are we not building now? | Leaving it out, so the AI adds extras |
| Data | What things exist and what fields do they have? | Skipping it, so each page invents its own |
| Tech | Languages, frameworks, libraries | Not saying, so the AI chooses |
| Rules and edge cases | Limits, validation, what happens when things go wrong | Only describing the happy path |
| Done means | How will I know it works? | No test, so "done" is a feeling |
A complete example
Here is a finished spec for the website. Read it slowly. Notice that every line is something you could check.
Project: Brew & Bean website (version 1)
Goal
A website where customers of Brew & Bean, a small coffee shop in Indiranagar, Bengaluru, can see the menu and place a pickup order.
Users
- Customers on phones (most traffic) and laptops.
- No logins in version 1.
Features (must have)
1. Home page: shop name, short intro, opening hours (8 am to 10 pm daily), address.
2. Menu page: items grouped by category (coffee, tea, bakery, food). Each item shows name and price in rupees.
3. Cart: add an item, change quantity, remove an item, see the total.
4. Order form: name and phone number, then Place order. After placing, show an order confirmation.
Out of scope for version 1
Online payment, user accounts, delivery, an admin page, multiple branches.
Data
Menu item: id, name, category, price (whole rupees).
Order: customer name, phone, items [{item id, quantity}], total.
Menu: espresso 120, cappuccino 180, cold brew 220, filter coffee 80, masala chai 90, butter croissant 150, banana bread 130, veg grilled sandwich 160.
Tech
React with Vite, plain JavaScript (JSX), plain CSS. No UI library. Menu data kept in one file for now.
Rules and edge cases
- Quantity is a whole number from 1 to 20.
- Phone must be 10 digits. Name must not be empty.
- The cart total is always recomputed from prices, never typed by the user.
- An empty cart cannot be ordered.
Done means
- I can open the site on a phone-sized screen and place an order end to end.
- Every feature above works without console errors.
Save your own spec in a file like this in your project folder. You will paste parts of it into prompts.
Use real details, not placeholders
"Menu with prices" invites the AI to invent prices. Listing the eight items and their prices removes that guesswork and keeps every page consistent. The same goes for validation rules and the phone format.
Step 1: Write your first draft
Now do it for your own idea, or use Brew & Bean. Start by writing the goal, features and out of scope sections, even if they are rough. Do not start with the AI. Your own thinking is what the spec captures.
Draft the spec
- 1Write the goal in one or two sentences.
- 2List 3 to 6 features as numbered, specific sentences (what the user can do).
- 3List at least 3 things that are out of scope.
- 4Write the data: each thing (menu item, order) and its fields.
- 5Choose the tech. If you are not sure, write "React with Vite, plain JavaScript" for the website.
- 6Write at least 3 rules or edge cases (for example: empty cart, wrong phone number).
- 7Write 2 or 3 "done means" sentences you could check yourself.
Step 2: Let AI interview you
The AI is excellent at asking the questions you forgot. Ask it to interview you instead of building anything.
You are a senior developer reviewing a project spec before any code is written. Here is my spec:
[paste your spec]
Do not write any code. Instead:
1. List up to 8 questions about anything that is unclear, missing or contradictory, most important first.
2. List 3 edge cases or error situations I have not described.
3. Point out anything in my spec that is too big for a first version.
I will answer, then you can help me improve the spec.What to expect: Good questions are specific, for example 'What should happen if the user orders when the shop is closed?' Ignore generic questions that do not apply, and add answers to your spec yourself.
Answer the questions in your own words, edit the spec and keep it short. If an answer is "I do not know", pick the simplest option and write it down. You can change it later, but now it is a decision instead of a guess.
Step 3: Turn the spec into a plan
Once the spec feels complete, ask for a plan. Insist on small tasks that can each be checked.
Here is my project spec:
[paste your spec]
Do not write code. Create a numbered build plan of 8 to 12 small tasks. For each task give:
- Goal (one sentence)
- Files to create or change
- How I can check it works
Rules: the app must run after every task. Do not add features that are in my 'Out of scope' list. Put risky or unclear parts early.What to expect: For Brew & Bean you would expect something like: project setup, header and home page, menu data file, menu page, cart state, cart UI, order form with validation, confirmation screen, styling for phones. Edit the plan before using it.
Step 4: Use the spec while building
The spec is only useful if you keep using it. When you prompt for task 3, paste the relevant part of the spec and the task, not the whole project description every time. For example:
Project: Brew & Bean website (React + Vite, plain JavaScript, plain CSS, no other libraries).
Relevant spec: [paste the Menu and Data sections]
Task: [paste one task from the plan, e.g. 'Create src/menu.js with the 8 menu items and src/MenuPage.jsx that shows them grouped by category']
Only do this task. List the files you change. Do not add features that are not in the spec. Tell me how to check that it works.What to expect: Check that the answer touches only the files you expected and uses the exact menu items and prices from your spec.
When something changes, update the spec first, then the code. If the spec and the code disagree, you will not know which one is right.
Common mistakes
Is my spec good enough?
- Every feature can be checked by someone else ("user can remove an item", not "good cart").
- I listed what is out of scope.
- I wrote real data (names, prices, field names), not "some items".
- I wrote the tech stack so the AI does not choose.
- I described at least three error or edge cases.
- The spec fits on one page for a small project.
- I did not leave out the users' device (phones matter in India).
Do not let AI write the whole spec for you
If you ask the AI to invent the spec from a one-line idea, you get a plausible spec full of its choices, and you have not thought about your project. Write the first draft yourself; use AI to question and tidy it.
Try it: Write a spec for your own mini-project
Choose one: a study timetable planner, an expense tracker for a hostel mess, or a small portfolio site. Fill in all eight sections, then run the 'Find the gaps' prompt and improve the spec using the answers. Finally run 'Spec to plan' and mark each task with how you would check it.
Key takeaways
- A spec is one page that records your decisions: goal, users, features, out of scope, data, tech, rules and what done means.
- Write the first draft yourself, then let AI interview you to find gaps and edge cases.
- Real data and explicit rules stop the AI from inventing details.
- Turn the spec into a plan of small, checkable tasks, and prompt for one task at a time with the relevant spec section.
- If requirements change, update the spec first, then the code.
Check yourself
Finishing the quiz marks the lesson as done.
1. Why include an 'Out of scope' section?
2. Which feature line is best for a spec?
3. You do not know what should happen when a customer orders an empty cart. What is the best move?
4. What is the best use of AI at the spec stage?
5. The requirements change midway. What should you update first?
Saved on this device. Create a free account to keep it on every device.
Practise this with Sam
A real mock interview, out loud, with an honest scorecard. Free to start.