liveBook · Manning

Specification

As explained in Build High Value Software Systems

A specification is a documented statement of required software behavior, constraints, or qualities.

When generating code is easy, the costly mistake is often building more than the feature needs. A specification makes intent explicit before implementation: it states the required behavior, the boundaries around it, and what must not happen. It gives developers, reviewers, and AI tools a shared test for whether the result is necessary—not merely plausible. section 4.1 section 4.6

Write a spec when a change has several reasonable approaches, unclear requirements, or future reviewers and maintainers. Skip it for a trivial or mechanical fix; if the goal is still unknown, explore first. A useful spec answers what inputs are valid, what outputs and errors are required, which dependencies or existing patterns constrain the work, and what must never happen. section 4.4.1 section 4.5.2

Keep the boundary precise without prescribing every implementation detail:

  • Describe behavior and exclusions clearly enough that different implementers would deliver functionally identical results. section 4.4.1
  • State a technical choice when it is a real constraint; otherwise leave room to choose how to implement the behavior. section 4.5.2
  • Link to existing code patterns that must be followed, rather than allowing a new pattern to be invented by default. section 4.4.1 section 4.5.5

Order-history export

A bounded request is to let an authenticated user download their own orders as a UTF-8 CSV with four specified columns. It rules out other users’ data, browser-side CSV construction, and loading all orders into memory. Server-side streaming with bounded database reads addresses the memory risk without adding formats, queues, or delivery options that nobody requested. section 4.1.4

Listing 4.4 Spec file
Accept: GET /api/orders/export (authenticated user)
Return: CSV file with columns: order_id, date, total, status
Filter: Only orders belonging to the requesting user
Format: Standard CSV, UTF-8 encoding
Never: Include other users' data, build the CSV in the browser, load all orders into memory, allow unauthenticated access
Prefer: Stream CSV rows from the server using bounded database reads

The short spec file separates what to accept and return from what must never happen and the preferred way to handle large exports. section 4.1.4

Use the spec as a review boundary: missing required behavior and added behavior are reasons to stop a pull request. During implementation, delete fields, abstractions, dependencies, and options that do not serve the requirements. Then revise the spec when the work exposes a genuine edge case, ambiguity, or constraint. The first version need not be perfect; it must be clear enough to reveal where assumptions are being made. section 4.4.3 section 4.5.4

In an AI-assisted workflow, keep the spec as the stable definition of correct behavior. If a model change produces sprawling output, check that output against the spec and adjust prompts or project rules rather than changing the requirements to suit the tool. section 14.5

How Build High Value Software Systems covers it

How deep it goes
Gives criteria for when to write a spec, questions for its contents, and a refinement loop; leaves unconstrained architecture open.
Examples
Uses an order-history CSV export spec and a payment webhook handler spec to distinguish required behavior from unwanted additions.
What it assumes
Assumes familiarity with software changes, pull requests, and dependencies; teaches the decision to write a spec through explicit questions.
What you can do after
Practice/perform writing bounded requirements, checking implementations against them, and refining the spec when work reveals missing constraints.
How it connects
Connects specifications to AI-assisted development, code review, standard work, dependencies, and overproduction.

Also explained in

Compare how 12 books explain specification →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Build High Value Software Systems. The section links point to the parts of the book it draws on.