Specification

A specification is a written description of what a system should do, precise enough to build from and concrete enough to verify.

“A complex system that works is invariably found to have evolved from a simple system that worked. A complex system designed from scratch never works and cannot be patched up to make it work.” — John Gall

Understand This First

• Requirement – specifications give requirements enough detail to build from.
• Constraint – constraints shape what the specification must respect.

Context

This is a strategic pattern. You have an Application with requirements and constraints. You know what to build and roughly what it must do. Now you need to write that understanding down in enough detail that someone (or something) can build it correctly.

Specifications have been central to software construction since before the first compiler. What has changed is who reads them. A human developer fills gaps with experience, asks clarifying questions, and makes judgment calls about ambiguities. An AI agent does none of that. It treats every stated detail as a hard requirement and every unstated detail as a free variable. The quality of your spec determines the quality of the agent’s first pass.

Problem

How do you capture what a system should do in a form that survives the journey from intent to implementation without losing essential details or accumulating false ones?

Verbal understanding evaporates. Requirements describe what the system must do, but they don’t describe how the pieces fit together, what the interfaces look like, or how the system should behave in the dozens of edge cases that only surface when you sit down and think through the details. Without a written spec, these decisions get made implicitly by whoever is coding, and the results may not match what anyone actually wanted.

Forces

• You want enough detail to prevent misinterpretation, but too much detail makes the spec brittle and expensive to maintain.
• A spec should be written before building, but you can’t know everything about a system before you’ve tried building parts of it.
• Specs need to be readable by both humans (for review and approval) and machines (for implementation by agents).
• The act of writing a spec forces you to think through problems you’d otherwise discover mid-build, but that thinking takes time that feels unproductive to people eager to start coding.

Solution

Write a document that describes the system’s behavior, structure, and constraints at a level of detail sufficient for a competent builder to implement without guessing about intent. A good spec sits between requirements (which say what the system must do) and code (which says how it does it). It describes the system’s shape, its interfaces, its major decisions, and its expected behavior well enough that the builder doesn’t need to keep asking “what did you mean by that?”

The right length depends on the complexity of the system and the shared context between author and builder. For a small feature, a page might suffice. For a complex system, ten pages. When the builder is an AI agent with no institutional memory, you need more detail than you’d give a senior colleague who has worked on the codebase for three years.

Specs typically cover:

• Behavior: What the system does in response to inputs, including edge cases and error conditions.
• Structure: The major components and how they relate to each other.
• Interfaces: What the system exposes to the outside world, and what it expects from external systems.
• Constraints: Performance targets, security requirements, compatibility needs, and any other qualities the implementation must respect.
• Decisions: Why you chose this approach over the alternatives. These are the choices a builder might otherwise revisit or reverse.

Spec-driven development gained renewed attention as agentic coding tools matured. AWS launched Kiro, an IDE built around spec-driven workflows. The Thoughtworks Technology Radar placed it in its “Assess” ring, noting both its promise and the risk of falling back into heavy upfront specification. In practice, teams adopt specs at different levels of commitment: some write specs before building and then move on (spec-first), some keep the spec as a living reference throughout the project (spec-anchored), and some treat the spec itself as the primary artifact that humans maintain while agents generate code from it (spec-as-source). Where your team lands depends on how much of the system’s intent lives in your head versus on the page.

How It Plays Out

A founder wants to add a payment system to their SaaS product. Without a spec, they tell their agent: “Add Stripe payments for monthly subscriptions.” The agent builds something that processes payments but has no trial period, no proration for mid-month upgrades, no webhook handling for failed charges, and no way to cancel. Each missing piece requires another round of prompting, and each round risks breaking what came before.

With a spec, the founder writes two pages covering subscription tiers and prices, trial period behavior, upgrade and downgrade rules, cancellation flow, failed payment retry logic, and the webhook events the system must handle. The agent builds from this document and covers the stated cases on the first pass. Six months later, when someone asks “how does proration work?”, the answer is written down.

Consequences

A written spec reduces rework by forcing decisions before building starts. Reviewers can evaluate intent before any code exists. The agent gets a stable reference that persists across conversation turns and compaction boundaries. And the spec becomes an artifact that explains the system’s intended behavior to anyone who needs to understand or modify it later.

The cost is real. Writing a good spec takes time and thought. It also creates a maintenance burden: as the system evolves, the spec must either evolve with it or be clearly marked as a point-in-time snapshot. A stale spec that contradicts the code is worse than no spec, because it misleads anyone who trusts it.

Specs can also create false confidence. A detailed document feels authoritative, but it’s still a prediction about how the system should work. Some predictions will be wrong, and you’ll need the flexibility to revise them. The remedy is to treat the spec as a living document during active development and freeze it only when the feature stabilizes.

Related Patterns

• Depends on: Requirement — specifications give requirements enough detail to build from.
• Depends on: Constraint — constraints shape what the specification must respect.
• Enables: Acceptance Criteria — a spec makes it straightforward to derive testable criteria.
• Enables: Tradeoff — the decisions section of a spec records which tradeoffs were resolved and how.
• Contrasts with: Judgment — a spec captures decisions that have been made; judgment handles the ones that haven’t.
• Uses: Application — every spec describes a specific application or feature of one.

Sources

• John Gall articulated the principle that complex working systems evolve from simple working systems in Systemantics: How Systems Work and Especially How They Fail (1975). The epigraph quote comes from this work, now commonly known as Gall’s Law.
• The IEEE formalized the content and structure of software specifications in IEEE 830-1984, the first widely adopted standard for software requirements specifications. It established the practice of writing detailed specs as a distinct engineering discipline.
• Spec-driven development as a named methodology was formalized in 2004 as a synthesis of test-driven development and design by contract. The 2024-2025 resurgence — driven by agentic coding tools that need explicit written intent — gave the practice mainstream visibility.
• Thoughtworks placed spec-driven development on their Technology Radar, noting its promise for agentic workflows while cautioning against reverting to heavy upfront specification.
• GitHub released Spec Kit, an open-source toolkit for spec-first agentic development, providing a structured process for turning specifications into agent-executable plans.