How to write a product spec a developer can build from

A good product spec gives a developer enough information to build the right thing without having to guess what you mean. You do not need a 50-page document. In most cases, one or two focused pages can be enough if they answer the questions that matter.

Last updated: 2026-09-27

Start with five questions:

• Who is the user, and what are they trying to do?
• What does "done" mean, and how will you test it?
• What should happen in unusual or unexpected situations?
• What are you deliberately not building?
• How will you check that the finished product works as intended?

Think of the spec as a blueprint. A builder can make decisions about how to construct a house, but they still need to know where the doors, rooms, and walls are supposed to go. A developer works in much the same way. They can decide how to implement something, but they need clear information about what they are building.

Every important question you leave unanswered becomes a decision the developer has to make for you. That decision might be correct, but it might also be wrong. If it is wrong, you pay for the misunderstanding through rework, delays, or a product that does not solve the original problem.

Key facts

In this article

• What does a developer actually need from a spec?
• What does the research say about requirements and rework?
• What goes in a one-page product spec?
• How do you write acceptance criteria a non-engineer can check?
• What should you leave out?
• How do you know the spec is ready?
• Where RocketDevs fits
• Conclusion
• Frequently asked questions

What does a developer actually need from a spec?

A developer needs five answers before writing code:

• who the user is;
• what done looks like;
• what happens when things go wrong;
• what is out of scope;
• and how the work will be checked.

The most common requirements problem in industry is not getting one of these answers wrong. It is not having the answer at all. In the NaPiRE survey of 228 companies across 10 countries, 48% of respondents named incomplete or hidden requirements as one of their most critical problems, more than any other problem reported.

Founders often write the opposite of this. A first brief tends to be a feature list: “Users can book appointments, get reminders, and pay online.” Each item is a noun that the developer has to turn into actual behaviour. Who can cancel? How late can they cancel? What happens to the reminder if the booking moves? What happens when payment fails?

The developer will have to answer these questions because the code cannot be written without answers. The question is whether you made those decisions or they guessed them.

Guessing is not a character flaw in the developer. It is what the job requires when the brief is silent. A good developer will ask questions, and a developer billed by the hour asks those questions on your clock.

The spec's job is to move those questions out of the middle of the build, when a change can mean rework, and into the planning stage, when a change might mean editing a sentence.

A clear spec also changes what the developer can tell you about the work. With only a feature list, an honest estimate may be so broad that it is difficult to use for planning. With the five answers, the developer can give you something more useful: “This should take about two weeks, except for the refund edge case, which depends on your payment provider.” That is the kind of answer you want before committing your budget.

What developers report about their work points in the same direction. JetBrains' State of Developer Ecosystem 2025, based on 24,534 developers across 194 countries, found that 62% rated non-technical factors as critical to their performance, compared with 51% for technical factors. Its summary highlights transparency, constructive feedback, and clarity of goals as things developers want. A good spec provides that clarity before the work begins.

The other side of the problem appears in Stack Overflow's 2024 Developer Survey. Technical debt was the most common workplace frustration among professional developers who responded, selected by 62.4% of 28,251 respondents. Rebuilding a feature because the requirements changed or were misunderstood is one way unnecessary technical debt can be created. A clear brief gives a founder a chance to prevent some of that rework before development starts.

If you are still deciding who to hire, our guide on how to evaluate a developer when you can't read the code covers the person. This article is about the other half of the equation: the work you hand them.

What does the research say about requirements and rework?

The research points to a consistent problem: incomplete requirements are one of the most frequently reported requirements problems, and poor requirements management is linked to project failure, time overruns, rework, and poor product quality.

Two surveys using different methods reach a similar conclusion. NaPiRE, a peer-reviewed study of 228 companies, found incomplete or hidden requirements to be the most frequently reported requirements problem. PMI's 2014 Pulse of the Profession, based on 2,066 practitioners, found inaccurate requirements management was identified as the primary cause of unsuccessful projects 47% of the time.

What the research does not support is the famous claim that a requirements mistake costs 100 times more to fix later. That number has been repeated for decades, but the strongest direct test of it did not find consistent evidence for such an effect.

What NaPiRE actually found

NaPiRE stands for Naming the Pain in Requirements Engineering. It is a family of surveys run by a consortium of universities led by Daniel Méndez Fernández and Stefan Wagner. The surveys have been repeated across countries, which helps reduce the risk that the results simply reflect one market.

In the round published in Empirical Software Engineering, 228 organisations across 10 countries were given 21 known requirements problems drawn from previous research. They were asked which problems they had experienced, which five were most critical, and which had contributed to project failure. They were then asked about causes and effects in their own words, which the researchers coded into cause-and-effect diagrams.

The results were clear:

• Incomplete or hidden requirements: 48%, reported by 109 of 228 respondents.
• Communication problems between the team and customer: 41%.
• Moving targets, meaning changing goals or requirements: 33%.
• Requirements that are too abstract and allow different interpretations: 33%.

The first three problems were also among the most frequently identified as causes of project failure.

Put those findings together and they describe a familiar situation: the person who knows what the product should do has not fully communicated it, the team and customer are not aligned, or the requirements change while development is already underway.

The cause-and-effect analysis makes the problem more concrete. Weak qualification and lack of experience in the person writing the requirements were each responsible for roughly 9% of reported causes of incomplete requirements. Other causes included time pressure, stakeholders without a clear business vision, poor requirements elicitation, overly abstract specifications, and missing completeness checks.

The reported effects included time overruns at about 10% of cited effects, post-implementation rework at about 9%, and poor product quality at about 9%.

For a founder writing their first product brief, that matters. You do not need to be an experienced requirements engineer. But you do need to recognise that a vague brief leaves decisions for the developer to make, and those decisions can come back as rework later.

What PMI found

PMI approached the question differently. Instead of asking which requirements problems teams experienced, it asked what caused projects to miss their goals.

Its 2014 report found that inaccurate requirements management was identified as the primary cause of unsuccessful project outcomes 47% of the time. It also reported that 5.1% of project and programme spending was wasted because of poor requirements management.

The report separately found inaccurate requirements gathering was identified as a primary cause of project failure by 37% of respondents in its 2014 annual survey.

There are important limitations. PMI sells requirements and business-analysis training, so its commercial context is worth knowing. The data is also from 2014. Both PMI and NaPiRE rely on practitioners reporting what they believe went wrong. They are not instrumented measurements of exactly how many hours were spent rewriting a feature because of a missing sentence in a specification.

There is also no public dataset that measures the rework caused by specification gaps specifically on small contracted software builds.

So the evidence supports a narrower claim than “bad specs always cost X times more.” It supports the much more useful observation that requirements problems are common and that they are associated with rework, delays, and unsuccessful outcomes.

Why we are not using the Standish CHAOS figure

You may have seen the Standish Group's CHAOS report quoted as evidence that software projects routinely fail. Its 1994 report famously put project success at 16%.

We are not using that figure here because its methodology has been heavily criticised. Eveleens and Verhoef applied Standish's definitions to 5,457 forecasts from 1,211 real projects and identified four major problems with them. They concluded, in IEEE Software, that the Standish figures did not reflect the reality of the case studies they examined.

That is why this article does not use a dramatic overall project-failure percentage to make its case. The evidence about requirements is enough on its own.

What about the 100x cost-of-change rule?

The folklore says that a requirements mistake found after release costs 100 times more to fix than one caught while writing the specification. This number is often used to justify extensive upfront requirements documents.

The strongest direct test does not support treating that multiplier as a rule.

Menzies, Nichols, Shull and Layman studied 171 software projects run between 2006 and 2014 and found no evidence for a consistent delayed-issue effect. In their sample, resolving issues later was not consistently or substantially more expensive in effort than resolving them earlier.

Their literature review also examined some of the older evidence behind the large ratios. The frequently quoted 1:137 and 1:117 figures from Toshiba and IBM were reported without the underlying raw data, meaning they could not be independently confirmed. NASA data, meanwhile, showed some defect categories costing 1.2 hours when fixed early and 1.5 hours when fixed later.

Laurent Bossavit's The Leprechauns of Software Engineering also examines how some of the widely repeated cost-of-change claims became accepted despite limited evidence behind the original numbers.

There is a fair qualification to make here. The steep cost curves came from large, long-running, plan-driven systems, while the Menzies study was dominated by smaller, iterative projects. If you are building safety-critical avionics, that distinction matters.

If you are a founder briefing a developer on a feature, however, you do not need a 100x multiplier to justify writing a good specification. The evidence already gives you a simpler reason: missing requirements are common, and they can turn into rework and delay.

Does this matter more with AI coding tools?

There is early evidence that it may.

A September 2026 preprint by Jiang and colleagues analysed 3,553 coding-agent sessions and found that when a requirement arrived after an agent had already written code, the subsequent changes were followed by roughly twice as much code invalidation as comparable edits. The researchers explicitly note that the result has not been demonstrated as causal, and the study has not yet been peer reviewed.

GitHub is also pushing the idea of spec-driven development through its open-source Spec Kit. Its announcement describes situations where generated code can look correct without actually meeting the intended behaviour, and describes the specification as a contract for how the code should behave.

GitHub has a commercial interest in its own tooling, so its framing should be treated accordingly. But the underlying principle is straightforward: whether a human or an AI agent writes the code, someone still has to define what the code is supposed to do.

That makes the specification more important, not less.

What does this mean for how you pay for development?

Requirements also affect the commercial side of a project.

A Management Science study of 93 offshore software projects found that requirement uncertainty significantly influenced the choice of contract, and that contract choice significantly affected project profit.

That matters because a vague specification does not only create a technical problem. It creates uncertainty about what is actually being purchased.

If you have not decided what the product should do, what counts as finished, or what happens in unusual situations, it becomes harder to agree on a fixed scope and harder to tell whether a developer has delivered what you asked for.

A good spec does not guarantee that a project will stay on schedule. It does something more practical: it removes decisions from the build that should have been made before the build began.

That is the real case for writing one. Not a mythical 100x penalty. Not a 50-page document. Just fewer unanswered questions when the developer starts turning your idea into software.

What goes in a one-page product spec?

A one-page product spec can have nine short sections:

• the problem and user;
• the outcome;
• the scope;
• the acceptance criteria;
• the edge cases;
• what is out of scope;
• the real constraints;
• how you will check it;
• and open questions.

There is a formal alternative. ISO/IEC/IEEE 29148:2018 is the international standard for requirements engineering. It runs to 92 pages and defines requirements-engineering processes and information items for complete systems. It is an appropriate reference for something like an aerospace contract. It is not where a founder needs to start when writing their first feature brief.

The template below uses one running example: a SaaS invoicing tool wants customers' clients to pay an overdue invoice directly from the reminder email without logging in. Replace the example with your own feature and keep the structure.

Problem and user

This is not “users need a payment feature”. It identifies a person in a specific situation and explains what they are trying to accomplish.

The test is simple: could a developer who has never met you explain, in their own words, why this user would click the button? If they cannot, the problem statement needs more detail.

Outcome

The outcome is what should change when the feature ships and the number you will watch afterwards.

For example, instead of simply saying “make it easier to pay overdue invoices”, you might track the share of overdue invoices paid within seven days of the first reminder.

This gives the feature a clear purpose. It also helps control scope because new ideas have to justify themselves against the same outcome. If a trade-off appears during development, the outcome tells the developer what the feature is supposed to protect.

Scope

Scope describes what the user can actually do. Keep it as a short list of actions rather than a technical description.

In the example, the user can open the email, click Pay now, view the invoice, pay by card, and receive a receipt.

This tells the developer what the feature needs to support without telling them how to build it.

Acceptance criteria

Acceptance criteria define what must be true for the feature to count as finished.

A useful format is three to seven Given/When/Then statements. Each one should be specific enough that someone can test it and get a clear pass or fail result.

This is different from scope. Scope describes what the user can do. Acceptance criteria describe how you will know the implementation actually works.

Edges

Edges describe what happens when the normal path breaks.

The main path of most features is usually straightforward to describe and build. The cases that consume unexpected time are often the unusual ones: the invoice was paid by bank transfer an hour before the reminder arrived, someone forwarded the payment link, the link expired, the card was declined, or the invoice amount changed after the email was sent.

You may already know about these situations because they appear in your support inbox. The developer does not.

That makes edge cases one of the most valuable parts of the spec. You are giving the developer information they cannot reasonably infer from the happy path.

Out of scope

This section says what you are deliberately not building.

For the invoicing example, that might mean no partial payments, no bank transfers, and no changes to the existing login flow.

This protects the feature from quietly expanding while it is being built. If someone suggests adding bank transfers halfway through development, you already have a written answer about whether that belongs in this release.

Constraints

Only include constraints that are actually real.

These might be an existing payment provider that must be used, a legal requirement, a fixed launch date, or a genuine budget limit. Do not fill this section with technical preferences unless they matter to the outcome.

A constraint should limit the developer's choices for a reason. Otherwise, you may be solving a technical problem you do not actually have.

How you will check it

Say who will test the feature, what they will use, and what has to happen before you call it finished.

In the example, the founder tests every acceptance criterion on their phone using a test card, followed by one real client completing a payment.

This is important because “the developer says it works” and “the feature has been checked against the agreed criteria” are not necessarily the same thing.

Open questions

Open questions are what make the spec honest.

A specification with no open questions for a new feature is often not evidence that everything has been decided. It may simply mean the author has not discovered the unknowns yet.

List anything that still needs an answer and, where possible, say who should provide it. The developer can answer technical questions they have the information to resolve. Questions about business rules, pricing, customer behaviour, or product decisions may need an answer from you before development starts.

For example: Does each reminder email already contain a unique invoice ID?

That is a much better question to discover before development than halfway through it.

What if you are building a whole product?

If your first build is an entire product rather than a single feature, use the same template for each important feature. Add one extra page for the shared parts of the product, such as authentication, payments, accounts, or common technical constraints.

The goal is not to produce a giant requirements document. It is to make sure each feature gives the developer enough information to make implementation decisions without having to invent the product for you.

Our guides on MVP development for startups and building an MVP cover how to reduce a product to the features worth specifying first. Our guide on how much it costs to build an app covers the budget side.

The format is not particularly niche, either. The English Wikipedia article on product requirements documents received 44,409 views in the year to August 2026, according to Wikimedia's pageview data.

The important part is not the page count. A one-page spec is useful when every section answers a question the developer would otherwise have to ask or guess.

How do you write acceptance criteria a non-engineer can check?

Write each criterion as Given, When, Then: the situation before, the action, and the result you expect to see.

The Cucumber Gherkin reference defines Given as the initial context of the system, When as the event or action, and Then as the expected outcome or result. It describes each example as a concrete example that illustrates a business rule.

The important part for a founder is the Then. It describes something observable. You should be able to perform the When yourself and look at the result without needing to read code.

The format is also older and broader than any one testing tool. Wikipedia describes Given-When-Then as a semi-structured way to write test cases that can be tested manually or automated. Dan North proposed the approach in 2006 as part of behaviour-driven development. The Agile Alliance describes it as a template for writing acceptance tests for a user story.

The manual part is what matters most when you are writing a spec. You do not need to automate anything for Given-When-Then to be useful. The automated part matters to your developer because the same criteria can later become automated tests.

The invoice example

Here is the invoice example from the previous section, rewritten as criteria you could check yourself on your phone:

What makes a good Then?

Notice what these criteria avoid.

None says “the page loads fast” or “the flow is intuitive”. Those statements sound useful but are difficult to check consistently. Different people can have different ideas about what “fast” or “intuitive” means.

If speed matters, give it a measurable condition:

On a mid-range phone using 4G, the invoice appears within 2 seconds.

If clarity matters, describe an observable outcome:

A client who has never used the product completes the payment without asking support for help.

The rule is simple: every Then should describe something two people could agree either happened or did not happen.

Turn your edge cases into tests

Notice that the unusual situations from the previous section have now become acceptance criteria.

That is the point of writing them down. An edge case you identify in the spec is something you can check before launch. An edge case you never identify may become something you discover through a customer complaint.

The invoice that was already paid. The expired link. The declined card. The changed amount. These are not separate from the feature. They are part of defining what the feature actually does.

Why developers like this format

For your developer, these criteria are close to executable tests. The Gherkin reference explains that a Then step's implementation should use an assertion to compare the actual outcome with the expected outcome.

There is also substantial tooling around the format. The npm registry recorded 7,511,101 downloads of @cucumber/cucumber in the 30 days to 25 September 2026. PyPI Stats recorded 3,893,130 monthly downloads of behave, a Python equivalent. The cucumber/gherkin parser supports implementations across eleven languages, and the Stack Exchange API lists 10,994 Stack Overflow questions tagged cucumber.

You do not need to know what any of those tools do to write good acceptance criteria.

You just need to describe what should be true before the action, what someone does, and what they should see afterwards.

That gives your developer something they can build against and gives you something you can check yourself.

What should you leave out?

Leave out how the product should be built unless a particular technical decision is a genuine constraint. That means leaving the tech stack, database, architecture, and screen layout to the developer unless you have a specific reason they must be a certain way.

The distinction matters because separating what a product needs from how it should be built is surprisingly difficult. In the NaPiRE survey, 25% of respondents ranked difficulties separating requirements from known solution designs among their most critical requirements problems.

The principle is well established. Joel Spolsky's 2000 essay on functional specifications argues that a specification should describe how a product works from the user's perspective rather than how it is implemented. Wikipedia's definition of a product requirements document makes a similar point: requirements should generally avoid defining how the product will achieve the result, leaving interface designers and engineers room to use their expertise.

That is part of what you are hiring the developer for.

Do not choose a tech stack just because you have heard of it

A common founder mistake is choosing a technology because it is popular, new, or something they recently read about.

“Build it in the framework I read about” sounds specific, but it is a decision you will have to maintain long after the first version is finished.

If you have a genuine reason to use a particular stack, put it under Constraints and explain why. You might already have an existing codebase, a team that knows the technology, or a customer contract that requires it.

If none of those apply, ask the developer to recommend the technology and explain the trade-offs.

How they answer is useful information about the developer, too. You want someone who can explain why a particular choice suits your product, not someone who simply reaches for their favourite technology.

Do not turn a screen design into a requirement

A mock-up can be extremely useful. It shows the developer what you have in mind and can make a product easier to discuss.

But a mock-up is not automatically a requirement.

If you specify the exact position, size, colour, and behaviour of every element before anyone has tested the design, you may be freezing decisions that have not been validated.

Label mock-ups as illustrative unless the exact design really matters. If it does matter, explain why.

For example, a legal requirement might dictate exactly what information must appear on a payment screen. That is a genuine constraint. “I saw another app do it this way” is not.

Do not put every future idea into version one

Your first product will probably contain features you would like to add eventually. They do not all belong in the first build.

Joel Spolsky recommended including a “nongoals” section in a functional specification: things the team has explicitly decided not to build. The reason is simple. Every team has extra features that sound reasonable individually but can cause the project to grow until it takes too long and costs too much.

That is what the Out of scope section in your one-page template is for. Write at least three things you are deliberately not building. It is one of the cheapest forms of scope control you can use.

What you should include instead

There is one important exception to the rule of leaving out the “how”: include anything the developer cannot reasonably know but you do.

Your payment provider account is a constraint. Your data-retention obligations are a constraint. An integration required by an important customer is a constraint.

These are different from telling the developer which database to use or how to structure the application.

A useful test is:

Does this requirement describe something the product must do, or am I telling the developer how to make it happen?

If it describes the result the user or business needs, it belongs in the spec.

If it dictates the implementation without a genuine business or technical reason, leave it to the developer.

If it is a limitation the developer needs to know about before choosing an implementation, put it under Constraints and explain the reason.

The goal is not to give the developer less information. It is to give them the right information: enough to understand what you need, without solving technical problems that you hired them to solve.

How do you know the spec is ready?

A spec is ready when a developer can read it, ask their remaining questions, and give you an estimate without saying “it depends” about something you could have decided yourself.

That matters because the effects associated with incomplete requirements in the NaPiRE research are the ones founders are most likely to feel: time overruns, post-implementation rework, and poor product quality.

You do not need to eliminate every question before development starts. The goal is to catch the questions that should have been answered before anyone started building.

The readiness test

1. Someone outside your head has read it

Give the spec to someone who was not involved in creating the idea.

Every question they ask reveals something that made sense to you but was not actually written down. Answer those questions in the spec rather than leaving the answers buried in a chat thread.

If a developer is the first person to read it, their questions are especially useful. They are showing you where the specification still leaves room for interpretation.

2. Every criterion has a Given, a When and a Then

Each acceptance criterion should describe the starting situation, the action, and the expected result.

If you cannot write the Then, you probably do not yet know what “done” means.

This reflects a long-established idea in agile development. Bill Wake, who developed the INVEST checklist for user stories, described a good story as something you understand well enough that you could write a test for it.

That does not mean every requirement needs to become an automated test. It means you should be able to describe what successful behaviour looks like.

3. You can check every Then yourself

You should be able to test the acceptance criteria without needing to read code.

Avoid words such as “fast”, “intuitive”, “robust”, or “easy” unless you define what they mean in something observable.

Instead of “the page loads quickly”, give it a measurable condition.

Instead of “the payment process is intuitive”, describe what the user must be able to do.

The test is simple: could two people perform the check and agree on whether it passed?

4. The edges are listed

Do not test only the happy path.

Think about the empty result, the duplicate request, the expired link, the failed payment, and the unusual case your support inbox already knows about.

These are often the situations that turn a seemingly simple feature into a much larger build.

If you have already identified an edge case in the spec, you can decide how it should behave before a customer discovers it for you.

5. Out of scope has at least three items

Write down at least three things you are deliberately not building.

This gives everyone something concrete to refer back to when a new idea appears halfway through development.

It also helps prevent a feature from becoming larger simply because each additional request sounds small on its own.

Write it down now so nobody has to argue about it in week four.

6. A developer has asked their questions

The developer should have a chance to read the spec before you treat the estimate as final.

Their questions are not evidence that the specification failed. They are part of the process.

The INVEST approach, as Wikipedia summarises it, describes a user story as an invitation to a conversation rather than a contract. Research by Lucassen and colleagues supports the need for that conversation: after analysing 1,023 user stories from 18 companies, they found that user stories were often poorly written and developed a 13-criterion framework for assessing their quality.

The important thing is what happens next. Answer the developer's questions, put the decisions back into the spec, and then estimate the work.

You can make some of this automatic

If your team works in GitHub, issue forms let you create structured templates with required fields. You could require an Acceptance criteria field and an Out of scope field before someone can open a feature request.

Teams using Scrum have a related concept in the Definition of Done: a formal description of the state an increment must reach before it meets the required quality measures, in the words of the Scrum Guide.

Your “How you will check it” section is a smaller, feature-level version of the same idea.

You are not creating a bureaucracy. You are making the finish line visible before anyone starts running.

The spec should survive the build

A spec does not stop being useful when development begins.

If a new question comes up during the build, answer it in the spec and tell the developer where the decision is recorded. If a requirement changes, update the document rather than leaving the new decision only in Slack, email, or a meeting.

By the end of the build, the spec should describe what was actually agreed and what was actually built.

That gives you something much more useful than the original brief. It becomes the record of why the feature works the way it does, and the starting point for the next person who has to change it.

Where RocketDevs fits

The mechanism on our side is simple: we read the brief before we match.

When a client sends us a PRD, it is reviewed and questioned as part of the matching process. That means the gaps discussed in this article (missing edge cases, unwritten acceptance criteria, or a prescribed tech stack without a clear reason) can surface in a conversation before development begins rather than appearing later as questions on a developer's first invoice.

The developer we match has already completed 6-8 hours of assessment and comes from the top 2% of applicants. They are not starting from a brief that has never been challenged. They are starting with a specification that has already been examined for gaps and discussed with the client.

Rates start at $9.99/hr for Associate engineers, $21.99/hr for Mid-senior engineers, and $30.99/hr for Senior engineers.

Every engagement also starts with a 14-day risk-free trial. If the engagement does not work out, the money-back guarantee is honoured 100% of the time.

If you already have a brief and want a second read before anyone writes code, build a vetted team with RocketDevs.

Conclusion

A product spec does not need to be long to be useful. It needs to remove the decisions that should not be left for the developer to make during the build.

Before anyone writes code, the developer should know who the user is, what the feature needs to achieve, what “done” looks like, what happens when things go wrong, and what is deliberately outside the scope. Acceptance criteria turn those decisions into something that can actually be checked. Out-of-scope items stop the brief from quietly expanding. Open questions make the remaining uncertainty visible.

The goal is not to predict every technical decision. That is part of what you are hiring a developer to do. The goal is to give them a clear enough target that they can make those technical decisions without having to guess what you meant.

A good test is simple: could someone who was not in the original conversation read the spec and understand what needs to be built, what does not need to be built, and how you will know it works? If the answer is yes, you have given the developer something they can build from.

The few minutes you spend clarifying a requirement before development can save much more time later. A sentence changed in a spec is cheaper than changing finished code, explaining a misunderstanding to a customer, or discovering at launch that the feature solves the wrong problem.

Your product spec is not paperwork before the real work begins. It is the first part of the build.

Frequently asked questions

What is the difference between a PRD and a spec?

For a founder briefing one developer or a small team, you can treat them as the same document and write one clear brief. In larger organisations, a product requirements document (PRD) usually explains what the product should do and why, while a functional or technical specification may describe the detailed behaviour or implementation.

For a small build, the important thing is not the document name. Your brief should explain the problem, desired outcome, scope, acceptance criteria, edge cases and constraints while leaving technical implementation decisions to the developer.

How long should a product spec be?

One page per feature, or two pages for a small product, is usually enough if every important section is covered. The formal requirements-engineering standard ISO/IEC/IEEE 29148:2018 runs to 92 pages because it covers much larger systems and formal requirements processes.

If your spec is growing well beyond two pages, check whether you are actually describing several features. If you are, split them into separate specs rather than making one document harder to use.

Who writes the acceptance criteria?

You do, because you know what “done” needs to mean for the business. Write the criteria in plain Given/When/Then language so each one describes a situation, an action and an observable result.

The developer should review them and add edge cases they identify. They can also turn the criteria into automated tests where appropriate. The business defines what must be true; the developer helps determine how to test and implement it.

Should I tell the developer which tech stack to use?

Only if it is a genuine constraint. For example, you may already have a codebase that uses a particular stack, have a team that needs to maintain the new feature, or have a client contract that requires specific technology. In those cases, explain the reason in the Constraints section.

Otherwise, describe what the product needs to do and let the developer recommend an appropriate stack. Separating requirements from solution designs is a problem that a quarter of companies in the NaPiRE survey ranked among their most critical requirements difficulties, so avoid specifying implementation details unless there is a clear reason to do so.

How do I know when my product spec is ready?

Ask whether a developer could read the document and understand what needs to be built, what is outside the scope, and how you will decide whether it works. Every acceptance criterion should have an observable result. The important edge cases should be identified. At least a few things you deliberately are not building should be written down.

The developer should still have questions. That is normal. The important thing is that questions about the business rules, desired outcome or scope are answered before development starts. Once those decisions are clear, the developer has enough information to estimate the work and make the technical decisions they were hired to make.

James Hitch, COO at RocketDevs.LinkedIn

Sources

• Méndez Fernández, Wagner et al., Naming the pain in requirements engineering: contemporary problems, causes, and effects in practice, Empirical Software Engineering, 2017 (arXiv 1611.10288)
• PMI, Pulse of the Profession In-Depth Report: Requirements Management, A Core Competency for Project and Program Success, August 2014
• Menzies, Nichols, Shull and Layman, Are delayed issues harder to resolve? Revisiting cost-to-fix of defects throughout the lifecycle, Empirical Software Engineering, 2017
• Menzies et al., same paper, full text (arXiv 1609.04886)
• Laurent Bossavit, The Leprechauns of Software Engineering
• Eveleens and Verhoef, The rise and fall of the Chaos report figures, IEEE Software, 2010
• Jiang et al., Requirements After the First Edit: Mining Late Requirement Emergence and Rework in Real-World Coding-Agent Sessions, arXiv 2609.03028, 2026
• Gopal, Sivaramakrishnan, Krishnan and Mukhopadhyay, Contracts in Offshore Software Development: An Empirical Analysis, Management Science, 2003
• Lucassen, Dalpiaz, van der Werf and Brinkkemper, Improving agile requirements: the Quality User Story framework and tool, Requirements Engineering, 2016
• JetBrains, The State of Developer Ecosystem 2025
• ISO, ISO/IEC/IEEE 29148:2018, Systems and software engineering, Life cycle processes, Requirements engineering
• Cucumber, Gherkin Reference
• Wikipedia, Given-When-Then
• Agile Alliance, Agile Glossary, Given-When-Then
• Bill Wake, INVEST in Good Stories, and SMART Tasks, 2003
• Wikipedia, INVEST (mnemonic)
• Wikipedia, Product requirements document
• Joel Spolsky, Painless Functional Specifications, part 2: What's a spec?, 2000
• Schwaber and Sutherland, The Scrum Guide
• GitHub Docs, Syntax for issue forms
• GitHub Blog, Spec-driven development with AI: Get started with a new open source toolkit, 2025
• GitHub API, github/spec-kit
• GitHub, cucumber/gherkin
• npm registry downloads API, @cucumber/cucumber
• PyPI Stats, behave
• Stack Exchange API, cucumber tag
• Wikimedia pageviews API, Product requirements document