Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Requirement

Pattern

A reusable solution you can apply to your work.

“The hardest part of building a software system is deciding precisely what to build.” — Fred Brooks

Understand This First

  • Application – requirements describe what the application must do.

Context

This is a strategic pattern. Once you’ve defined the Application — the thing you’re building — you need to describe what it must do and what properties it must have. Those descriptions are requirements.

Requirements matter in every software project, but they take on particular urgency in agentic coding. An AI agent will build exactly what you ask for, quickly and without pushback. If your requirements are vague, the agent fills in the gaps with plausible-sounding defaults that may have nothing to do with what you actually need.

Problem

How do you communicate what a system must do in a way that is specific enough to guide design and concrete enough to verify?

Natural language is ambiguous. People often describe what they want in terms of solutions (“add a database”) rather than needs (“the system must persist user data between sessions”). And incomplete requirements don’t announce themselves. You discover the gaps when something breaks or when a user complains.

Forces

  • You want requirements to be precise, but over-specifying constrains design options unnecessarily.
  • Requirements should be stable enough to build against, but real needs evolve as you learn.
  • There are always more requirements than you can satisfy at once, so you must prioritize.
  • In agentic workflows, the agent treats your stated requirements as the ground truth. Unstated requirements simply don’t exist from its perspective.

Solution

Write requirements as statements about capabilities or properties the system must have, not as implementation instructions. A good requirement answers the question “what must be true?” rather than “how should this be built?”

There are two broad kinds. Functional requirements describe behavior: “The system must allow a user to search tasks by keyword.” Non-functional requirements describe qualities: “Search results must appear within 200 milliseconds.” Both are necessary. Functional requirements without quality attributes produce software that technically works but frustrates users. Quality attributes without functional grounding produce elegant architecture with nothing to run.

Each requirement should be specific enough that you can write acceptance criteria for it. If you can’t describe how to tell whether the requirement is met, it’s not yet a requirement. It’s a wish.

Tip

When directing an AI agent, state your requirements explicitly in the prompt or project instructions. Don’t assume the agent will infer unstated needs. If performance matters, say so. If accessibility matters, say so. The agent optimizes for what you make visible.

How It Plays Out

A team asks an agent to build a file upload feature. They say: “Users should be able to upload files.” The agent builds a working uploader with no file size limit, no type validation, and no progress indicator. Every unstated requirement (security, usability, performance) was silently ignored.

A more experienced team writes: “Users must be able to upload PDF files up to 10 MB. The system must show upload progress. Uploads must complete within 5 seconds on a typical broadband connection. The system must reject non-PDF files with a clear error message.” Now the agent has something concrete to build against, and the team has something concrete to verify.

Example Prompt

“Build a file upload feature. Requirements: PDF files only, max 10 MB, show upload progress, complete within 5 seconds on broadband, reject non-PDF files with a clear error message.”

Consequences

Good requirements reduce rework by catching misunderstandings early. They give you a basis for acceptance criteria and testing. They help you negotiate tradeoffs because you can see which requirements conflict and decide which to prioritize.

The cost is time spent thinking and writing before building. Requirements also create a temptation to over-specify, locking down every detail before learning from a working prototype. The remedy is to write requirements iteratively: enough to start, then refine as you learn.

  • Depends on: Application — requirements describe what the application must do.
  • Uses: Constraint — some requirements arise directly from constraints.
  • Enables: Acceptance Criteria — criteria make requirements verifiable.
  • Enables: Tradeoff — conflicting requirements create tradeoff decisions.
  • Informs: Domain Model — requirements reveal which domain concepts the software must represent.
  • Improved by: Ubiquitous Language — requirements written in the ubiquitous language are less ambiguous.
  • Enables: Invariant — invariants are often derived from requirements.