Why does an AI coding tool need a spec?
AI coding tools are quick to produce something that looks finished. That speed is also the problem: given a vague request, the tool fills every gap with its own guesses, and each new prompt can quietly undo an earlier decision. A spec gives the tool, and you, a fixed reference. When the result drifts, you compare it with the document instead of with your memory of an earlier chat.
The spec does not need technical language, but it does need to be specific. “A booking app” is a wish; “a visitor picks a service, a date and a free time slot, leaves a name and phone number and sees a confirmation” is something a tool can build and you can check. If you are learning this way of working, our vibe coding course practises exactly this step: turning an idea into instructions a tool can follow.
Keep the spec in a file inside the project, not only in the chat. Most tools can read project files, and a document that travels with the code survives a new session, a new tool or a new person joining the work.
What should a vibe coding spec describe?
Users and their main task. Name each type of user and the one thing they come to do. A prototype with one user and one task is far easier to get right than one with several roles and an admin panel.
Screens and steps. List the screens in the order the user meets them and what can be done on each. A rough sketch or a simple list is enough. Say what is deliberately not included, such as accounts, payments or notifications, so the tool does not add them on its own initiative.
Data. Describe what is stored, which fields are required and what is never stored. If the prototype handles personal details, say so plainly and decide where the data lives. Do not paste real customer data or secret keys into prompts or into the code.
Error cases. What happens if a field is empty, a slot is already taken, the connection drops or the user presses the button twice? AI tools tend to build only the happy path unless they are told otherwise, and these cases are exactly where a prototype breaks in front of real people.
What counts as done. For each step, write an acceptance example in plain words: “a visitor books a free slot and sees it in the confirmation; the same slot is no longer offered to the next visitor.” This is what you will check after every change.
How do you build in checkable steps?
Do not ask for the whole application at once. Split the spec into small steps, each of which produces something you can open and try: the first screen with fixed data, then saving, then the error messages, then the second screen. After each step, check the acceptance examples for everything built so far, not only the newest part, because a fix in one place often breaks another.
Use version control from the first step and save a working state before each new request. When a change breaks something, you can go back in one move instead of asking the tool to repair its own repair. Keep a short log in the spec as well: what was asked, what changed and what was checked.
When the prototype starts to matter, for example when real users or real data are involved, step back and review it properly. Our guide on how to review a vibe-coded app covers permissions, data handling and the error cases that need a second look. And if the prototype has proved the idea and needs to become a product, MVP development services usually start from the same spec, which saves time on both sides.
How do you write prompts from the spec?
Each prompt should point to one part of the spec and one step. Name the screen or rule you are working on, paste or reference the acceptance examples for it and say what must not change. “Add the error message for a taken slot; do not change the booking form or the stored fields” gives the tool far less room to wander than “fix booking”.
When the tool proposes something the spec does not mention, decide deliberately. Either add it to the spec, with its own acceptance example, or reject it. Letting extras slip in unrecorded is how a small prototype turns into code nobody fully understands.
Common mistakes
- One giant prompt. Asking for the whole application at once gives the tool too many decisions to make on its own and makes errors hard to trace.
- Only the happy path. A spec without error cases produces a prototype that works in a demo and fails with the first real user.
- Spec only in the chat. Instructions scattered across a long conversation are lost with the next session. Keep the spec as a file in the project.
- No working state saved. Without version control, a bad change can only be fixed by more prompts, and each one risks breaking something else.
Vibe coding spec template
A template to adapt to your own project.
| Section | What to write |
|---|---|
| Goal | The one task the prototype must let a user complete. |
| Users | Each type of user and what they come to do. |
| Screens | The screens in order, the actions on each and what is not included. |
| Data | What is stored, which fields are required and what is never stored. |
| Error cases | Empty fields, conflicts, a lost connection, repeated clicks. |
| Done | Acceptance examples in plain words for every step. |
| Log | Each request, what changed and what was checked. |
Checklist: vibe coding spec
- Write the goal and the main user task in one sentence.
- List the screens in order and what is deliberately left out.
- Describe the data, including what must never be stored.
- Add error cases before the first prompt, not after the first failure.
- Write acceptance examples and check all of them after each step.
- Keep the spec in the project and save a working state before every change.
Example: a booking prototype in small steps
A salon owner wants to test online booking. The first attempt is a single prompt, “make a booking app”, and the result has accounts, a dashboard and a payment page nobody asked for, while two visitors can still book the same slot.
The second attempt starts from a one-page spec: one user, three screens, the data fields, the error cases and acceptance examples. The tool builds it in several small steps, each checked against the examples. The double-booking problem is caught at the step where saving is added, while it is still easy to fix.
