Specifications: What The Machine Actually Needs

A specification takes the requirements from 2.1 and adds the structure, detail, and edge cases an engineer (human or AI) needs to actually build the thing.

For each requirement, a spec answers:

INPUTS. What does this feature receive? From where? In what format? OUTPUTS. What does this feature produce? Sent where? In what format? RULES. What logic transforms the inputs into the outputs? EDGE CASES. What happens when the input is empty? Malformed? Too big? Arrives twice? Arrives out of order? ERROR HANDLING. What does the user see when something goes wrong? What gets logged? Does anyone get notified? DATA. What gets read from a database, and from which tables? What gets written, and to which tables? PERMISSIONS. Who can do this? Who cannot?

Take this requirement: "Customers can log in with their email and a password."

Spec it out:

Inputs: email address (string), password (string) Outputs: on success, a session token (returned in a cookie); on failure, an error message displayed in the UI Rules: - Email must match a row in the customers table. - Password is hashed (bcrypt) and compared to the stored hash. - On 5 failed attempts within 10 minutes (tracked in the login_attempts table), lock the account for 15 minutes. - Successful login creates a row in the sessions table with a 90-day expiration. Edge cases: - Empty email or password: return validation error immediately, no database lookup. - Email exists but password is wrong: increment login_attempts, return generic "invalid email or password" message (do NOT reveal whether the email existed). - Account is locked: return "account temporarily locked, try again in X minutes" with the actual minutes remaining. - Session table write fails: log the error, return 500 to the user with a generic "please try again" message. Permissions: anyone can attempt login.

This is one requirement, expanded to a spec. A typical small project will have 20-50 requirements that each get this treatment. That sounds like a lot. It is. That's why most projects fail.

The good news: a coding agent will help you write the spec. You give it your one-sentence requirement, ask "what edge cases am I missing?", and iterate. The agent is much better at spotting omissions than at writing software with omissions present.

We'll see this exact pattern in the templates in section 8.1 (PRD) and 8.2 (feature spec).