Write a one-page spec that an AI coding assistant can build from.
Before you ask your coding assistant for any code, open a blank document and write one or two sentences about who will use your app. That is the first part of a spec. The rest of the page sets out the decisions the assistant would otherwise make for you.
The second time Priya started her app, she typed one line to her coding assistant: build a web app that summarises customer feedback using AI. It produced an app in two minutes. The app had a chat interface she didn't want, and it called the model directly from the browser with a placeholder where the key should go. It also returned paragraphs of prose instead of her table.
The assistant didn't cause this. The request was underspecified. A one-line request leaves every decision to the assistant, and it fills the gaps with the most common answers it knows.
A spec (short for specification) is where you make those decisions yourself, before any code exists. It is a short document describing what the app does, precise enough that someone else could build it without asking you questions. For a small app, one page is enough. Write it in plain words, because it describes behaviour. The code comes later.
Every spec covers the same five things:
The user: who uses the app, in one or two sentences. You wrote this in lesson 6.1, Pick a project small enough to finish. The job: the single task the app does for that user. The screens: each screen and what is on it. The data: what the app stores, if anything, and where. The actions: what happens when the user does each thing.
Priya's version one has one screen. It holds a text box for pasting feedback, a submit button, a results table with three columns (sentiment, issues, summary) and an area for error messages.
Her version one stores nothing, and the spec says so explicitly. If you leave the data section out, the assistant may add a database "to be helpful". Writing that the app stores nothing prevents this.
Her actions section describes what happens on submit. The browser sends the text to the server. The server splits it into items, one per line, and rejects the request if there are more than 50 items. It calls the model for each item using the system prompt and schema from module 2, validates each reply, and returns the results for the page to show as a table.
Next, add examples: sample inputs, each with the exact output it should produce. Lesson 2.1 of Working with AI assistants, One good example beats a paragraph of description, made this point about prompts, and it applies to specs as well. Priya included three feedback lines, each with the exact row it should produce.
Then write down what happens when things go wrong. A spec that only describes the happy path, the case where nothing goes wrong, produces an app that only works on the happy path. Priya took her rules from lesson 2.3, Handle a bad response without crashing. If the box is empty, the app shows "Paste at least one piece of feedback" and does not call the model. If there are more than 50 items, it shows "Please paste 50 items or fewer" and does not call the model. If one item fails validation twice, that row shows "Could not summarise" and the app continues with the rest. If the model call times out, it shows "This is taking longer than usual, please try again" and keeps the pasted text in the box.
Last, include one line about the API key in every spec. Assistants sometimes default to calling the model from the browser, especially for quick prototypes, which is what happened in Priya's first attempt. Her line reads: the model API key is read from an environment variable on the server, never sent to the browser, never written in any file in the repository. With that rule in the spec, the assistant builds the right structure from the start. You also have a fixed rule to check every change against, which you will do in lesson 6.3, Work in small steps and read every change.
Once the spec is written, don't ask for code yet. Give the spec to the assistant and ask for two things. First, ask it to restate the plan in its own words, including the files it would create and how the browser and server talk to each other. Second, ask it to list every question or ambiguity it sees.
The restatement shows whether the assistant understood your spec. Watch for a database you never mentioned, or for the browser calling the model directly. If you catch a misunderstanding at this stage, you fix one line in the spec. If you catch it later, you may be fixing a hundred lines of code.
The questions show what you left out. Priya's assistant asked three. It asked how to split items if one contains a line break, what to do with non-English feedback, and whether results should be downloadable. She answered the first two in the spec. Downloadable results were outside version one, so she added that idea to her later list.
Revise the spec with your answers, then ask again. Stop when the only questions coming back are about small details.
This is the same plan-before-the-work habit from lesson 3.2 of Working with AI assistants, Ask for the plan before the work. Here, though, the plan becomes a file in your repository that you and the assistant keep referring to.
The activity below asks you to write your spec, put it through this question round with your assistant, and revise it.
Write a one-page spec for your app. Ask an AI coding assistant to restate it and list its questions, then revise the spec.
Junxiong-WFG Organisation is an authorised representative of AIA Financial Advisers Private Limited (Reg. No. 201715016G).