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











