Writing a Spec in Plain Language

Three Questions That Are Your Whole Spec

A spec is simply a written description of what you want built. You do not need a technical document. You need answers to three questions, written down in ordinary sentences. Who is this for? Not "everyone", but the specific person: what they already know, what device they are on, how much patience they have. What must it do? The actions someone can take, listed plainly, in the order they would happen. What must it never do? The boundaries, which is the section people skip and then regret. That third one is the most valuable, because an AI will not invent your constraints. If you never say that visitors must not see each other's entries, nothing in the request implies it. You will get exactly what you asked for, rather than what you assumed.

• Who it is for, as one concrete person rather than a market segment
• What it must do, as actions in the order they happen
• What it must never do — the section that prevents the worst surprises
• Unstated assumptions are not implied; they are simply absent

Be Specific Where It Matters

Vagueness gets filled in with a guess, and the guess is usually a generic default. "Users can upload a file" leaves open which formats, how big, what happens to a wrong one, and whether anyone else can see it. Compare that with a fuller version. "Users can upload a photo, up to about five megabytes, JPEG or PNG only, and see a clear message if it is the wrong type." That leaves almost nothing open. You do not need to be specific about everything. Be specific about anything where a wrong guess would annoy you. A useful habit is to say what happens when things go wrong, as well as when they go right. The unhappy paths are where generated software is thinnest, and where real users spend a surprising amount of their time.

• State limits explicitly: sizes, formats, counts, lengths, allowed values
• Describe what happens when something is wrong, not only when it is right
• Anywhere you would be annoyed by a wrong guess, remove the guess
• Unhappy paths are where generated code is weakest and users live most

Say What Success Looks Like

End your spec with a short list of statements that must be true when it is finished. "A visitor can submit the form and I receive an email within a minute." "Nobody can see another person's submission." "It is readable on a phone." These are not decoration. They are how you tell whether you are done. In module four they become the checklist you run every time you change anything. Write them before you build, while you still have clear eyes. Written afterwards, they mysteriously describe whatever the software happens to do, which tests nothing at all. Five to ten statements is plenty for a first version. Each one should be something you could check in under a minute.

• Finish the spec with five to ten checkable statements about the finished thing
• Write them before building, or they will just describe what you got
• Each should be checkable by hand in under a minute
• These become your regression checklist for every future change

Give the AI the Spec, Not a Wish

Once you have those pieces, paste the whole thing in as context. Then ask for a small first piece of it. That combination matters. Without the spec, the AI is guessing at your intent, and it will fill the gaps with generic choices. Without the "small first piece", it will attempt the entire document at once. What comes back is broad, shallow and very hard to correct. Keep the spec somewhere you can paste it again, because conversations lose earlier context and tools get restarted. Re-supplying the same clear description is not wasted effort. It is the cheapest way to keep everything you build pointing at the same idea, rather than drifting a little further with each session.

• Supply the full spec as context, then ask for one small piece of it
• Keep the spec in a file you can paste again — conversations lose context
• Re-stating constraints in later sessions prevents slow drift
• A spec plus a narrow request beats a wish plus a wide one every time

Try It Yourself

You sized your idea down to a weekend at the end of module one. Now write the spec for that version — the document you will paste into every building session from here on.

What it is: [one or two plain sentences]

Who uses it: [one specific person — what they know, what device they are on]

The screens: [each screen top to bottom, every control, and what pressing it does]

What happens when things go wrong: [empty fields, wrong values, pressing a button twice]

What it must never do: [the boundaries — who must not see what, what must never happen without you]