AI coding tools are good at writing code and bad at guessing what you meant. Ask Cursor, Claude Code or Lovable to "build a habit tracker" and it has to decide hundreds of things for you: how a streak is counted, what happens at midnight, what the empty screen says, whether data is stored on a server. It will decide them, quickly and quietly, and many of those decisions will not be the ones you would have made.
A spec moves those decisions to the start, where they are cheap to make. Here is what a spec needs for an AI tool to build from it without stopping to ask questions.
1. Start with a summary and your assumptions
Open with two or three sentences: what the app is, who it is for, and the one thing it must do well. Then list your assumptions as plain statements, such as:
- Data is stored only on the user's device, with no accounts.
- A day runs from midnight to midnight in the user's local time zone.
- A user can have at most 12 habits.
Assumptions are the most useful part of a spec. Each one is a decision the AI would otherwise make for you without saying so. Writing them down makes them visible, and a wrong one is easy to correct.
2. Name the tech stack
Say what to build with: framework, language, storage, sign-in, styling and hosting. One line each is enough, with a short reason. "React with Vite, IndexedDB for storage, no server" stops the tool from adding a database and a sign-in system you never asked for.
3. List every screen
For each screen, write down:
- how the user gets there
- what it shows
- what it shows when it is empty, loading, or when something fails
- where Back or Close goes
The empty, loading and error states are where AI-built apps most often feel unfinished. If the spec doesn't say what an empty list shows, the tool will usually show nothing.
4. Define the data and the rules
List each kind of record the app stores (a habit, a completion, an invoice) with its fields, types and limits. Then write every rule as something you can check:
The current streak counts back from today if today is done, otherwise from yesterday. A day not yet done today does not break the streak until midnight passes.
Vague rules such as "track streaks" are where bugs come from. A precise rule, ideally with a worked example ("done Monday, Tuesday and Thursday, so on Friday the streak is 1"), gives the tool something it can test against.
5. Spell out each feature
For each core feature, describe exactly what the user does and what happens next, including the exact words on buttons and messages. "Show an error" leads to a generic message. Name must be 1–40 characters leads to exactly that message.
Include what happens on failure: no network, a duplicate name, a payment that doesn't go through.
6. Say what is out of scope
A short "not in version 1" list (no reminders, no sharing, no dark mode) keeps the tool from adding features on its own and keeps the first build small enough to finish.
7. End with success criteria you can test
Finish with checks a person or a test can confirm, such as:
- Marking a habit done twice in one day counts once.
- After midnight, a habit not done yesterday shows a streak of 0.
- The app opens and works offline after the first visit.
These double as the acceptance tests for the build. You can ask the tool to check each one before it says it is done.
How to use the spec
- Save it in your project as
SPEC.md. - Ask the tool to read the whole spec first, then build one section at a time, starting with the data model.
- After each step, have it check the success criteria that apply.
- When something comes out wrong, fix the spec first, then the code. The spec stays the source of truth.
The short version
A good spec answers every question the AI would otherwise guess at: what is stored, what each screen shows in every state, the exact rules with examples, the exact words, what is left out, and how you will know it works.
Writing all of that by hand takes an afternoon. SpecWise writes it from a single sentence in about a minute, and you can see five full examples before you try it.