How to Write a Product Spec That Engineers (or AI) Can Actually Work From

A product spec that engineers can actually work from contains four things: a clear problem statement, a set of user flows written in plain language, explicit acceptance criteria for each feature, and a list of what you are deliberately not building. Everything else, the diagrams, the Notion pages, the colour-coded priority columns, is optional. Get those four right and a developer, an agency, or an AI coding tool can execute your idea faithfully. Miss any one of them and you will spend weeks in clarification loops.

Why most founder specs fail before a line of code is written

The most common failure mode is not that founders write too little. It is that they write at the wrong level of abstraction. A spec that says "users should be able to manage their account" tells an engineer almost nothing. A spec that says "a logged-in user can change their email address, and receives a confirmation link to the old address before the change takes effect" gives them something to build and test against.

This matters more now than it did a few years ago. AI coding tools, whether you are using them yourself or working with a developer who leans on them, are highly literal. They will implement exactly what you specify. Vague input produces technically-working software that does not do what you imagined. The spec is load-bearing in a way it was not when a developer could walk over and ask a question.

The structure that actually works

You do not need a formal product requirements document with dozens of sections. For most early-stage products, a single structured document covering the sections below is enough. Keep it in one place, version it, and treat it as a living document rather than a one-time deliverable.

1. Problem statement. One or two sentences. What is broken or missing for which kind of person, and what does that cost them? Write it as a factual observation, not a vision statement. Example: "Freelance bookkeepers in the UK track client payment deadlines in spreadsheets and miss them when they are managing more than eight clients. Late payments hurt their cash flow and damage client relationships."
2. Who it is for. Describe the primary user in concrete terms: their technical confidence, their workflow context, what device they are likely on. Not a persona card with a name and a stock photo. Just the relevant facts that change how you build.
3. User flows, not feature lists. Walk through what a user actually does, step by step, from landing on the product to completing the action that matters. Write each flow as a numbered sequence. Flows expose gaps that feature lists hide, because you have to account for what happens when something goes wrong.
4. Acceptance criteria per feature. For each feature, write a short checklist of conditions that must be true for it to be considered done. These are not design specs. They are behavioural contracts: "Given X, when the user does Y, the system does Z." If you can write an acceptance criterion, you can test it. If you cannot write one, the feature is not well-defined enough to build.
5. Out of scope, explicitly stated. List the things you considered and decided not to build in this version, and briefly note why. This saves enormous time. Without it, developers make reasonable assumptions about what to include, and founders end up disappointed by features that were quietly built in.
6. Open questions. A short section noting decisions you have not made yet. A good engineer or AI tool will surface these anyway; having them written down shows you know where the gaps are and prevents them from becoming hidden blockers.

How to write user flows that are actually useful

Most founder specs describe features from the product's perspective. User flows describe behaviour from the user's perspective. The difference sounds subtle but it changes what you build.

Take a simple example: a user who has forgotten their password. A feature-list spec says "password reset functionality". A user flow spec says this:

1. User arrives at the login screen and clicks "Forgot password".
2. User enters their email address and submits the form.
3. System sends a reset link to that email address if an account exists; shows the same confirmation message either way (do not confirm whether the account exists, for security).
4. User clicks the link. Link expires after 60 minutes.
5. User sets a new password. Password must be at least 10 characters.
6. User is redirected to the dashboard, now logged in.

That flow specifies the security behaviour, the link expiry, the password rule, and the post-reset redirect. A feature list would have left every one of those as an implicit decision for the developer. Write every flow at this level of specificity.

Writing specs for AI coding tools specifically

If you are working with an AI coding tool directly, or handing a spec to a developer who will use one heavily, a few additional practices make a material difference.

• Specify the tech stack if you have constraints. AI tools will make sensible default choices, but if you are building on an existing codebase or have a hosting constraint (for example, a UK data-residency requirement), state it explicitly.
• Break features into small, independently completable units. AI coding tools work best on contained tasks. A spec that says "build the authentication system" is harder to execute faithfully than one that breaks it into: registration, login, password reset, and session management, each with its own acceptance criteria.
• State what "done" looks like for the overall product. What is the minimum that needs to work for you to consider the first version shippable? This gives the tool a stopping condition, which matters more than most founders realise.
• Include error states. What should happen when a form submission fails? When an API call times out? When a user tries to access something they do not have permission for? These are boring to specify and expensive to leave vague.

What to do when you do not know what you want yet

Sometimes the honest answer is that you are not ready to write a spec because the product thinking is not done. That is a legitimate position. Writing a vague spec to fill the gap does not move things forward, it just shifts the ambiguity downstream where it is more expensive to resolve.

In that situation, the better move is to write a discovery brief rather than a product spec. A discovery brief says: here is the problem, here are the users, here is what I do and do not know, and here is what I need to figure out before I can spec this properly. That document is honest about its own incompleteness and gives a developer or consultant something real to work with.

If you are working with a development partner, that discovery phase often becomes a scoping workshop. The output is the spec. You are not expected to arrive with everything figured out. You are expected to arrive having thought clearly about the problem.

Common mistakes worth avoiding

A practical starting point

If you are staring at a blank document, start with this structure and fill it in order. Do not move to the next section until the current one feels specific enough that someone unfamiliar with your idea could not misread it.

1. Problem (2–3 sentences, grounded in a specific user and situation)
2. Primary user (who they are, their context, their technical confidence)
3. User flows (numbered steps, at least one happy path and one error path per core feature)
4. Acceptance criteria (3–5 bullet points per feature, written as testable conditions)
5. Out of scope (anything you considered and decided against)
6. Open questions (things you know you have not decided yet)

That structure keeps the document honest about what it knows and does not know. It gives an engineer something to build from. And it gives you a basis for a real conversation rather than a briefing that turns into a guessing game.