What is spec driven development?

Spec driven development is a software methodology where teams write a structured specification — a precise description of what to build, why, and under what constraints — before any implementation begins. It predates AI, but AI is the reason it matters more than ever.

The core idea

The premise of spec driven development is simple: the quality of the software you ship is determined before the first line of code is written. Not in code review. Not in QA. Before.

A spec — short for specification — is a structured artifact that answers the questions every implementation needs answered. What is the goal? What does a successful outcome look like? What are the boundaries of the work? What constraints apply? What can be deferred?

In spec driven development, these questions are answered first, by the whole team, in writing, before anyone opens an editor. The implementation that follows is an execution against a contract — not an interpretation of a vague brief.

The quality of the software you ship is determined before the first line of code is written.

This sounds obvious. In practice, almost nobody does it. Most teams work from tickets — rough, loosely scoped coordination artifacts designed for humans filling in the gaps from memory and context. That worked when humans wrote all the code. It doesn't work when the code is written by an AI.

Why spec driven development matters now

For the first twenty years of Agile, the ticket was good enough. A human reading a ticket brings enormous amounts of implicit context: they were in the standup, they remember the conversation, they know what the customer actually meant, they can ask a follow-up question. The gap between what the ticket said and what the ticket meant was bridged by human judgment on every task.

AI agents don't have that context. An AI reading a vague acceptance criterion doesn't ask the PM what they meant — it makes a decision, silently, and keeps going. Every loose phrase becomes a guess. Every unstated assumption becomes a hidden implementation choice. Multiply this across a codebase built over months and you get software that moves fast but drifts — fast from the outside, fragile from within.

Spec driven development closes this gap. A well-written spec is a contract, not a prompt. It is precise enough that an AI agent can execute against it faithfully. It is structured enough that a human reviewer can verify the output against the intent. And it is durable — unlike a prompt, it outlives the conversation that created it.

A spec is a contract, not a prompt. Prompts disappear. Specs persist.

Spec driven development vs. ticket-driven development

To understand what spec driven development actually changes, it helps to compare it directly to how most teams work today.

Neither approach is wrong in every context. Ticket-driven development works well when the team is small, the work is well-understood, and implementation is done entirely by humans with shared context. Spec driven development pays off most when AI agents are doing implementation work, when the team is distributed, or when the codebase needs to be understood months or years after the code was written.

What a spec actually contains

A spec is not a PRD, and it's not a ticket with more words. It's a structured artifact with four specific components:

Definition

A precise, bounded statement of what the work is. Not “improve the onboarding flow” — that's an intent. A definition is: “Add an optional company name field to the signup form, persist it to the user profile, and display it in the workspace header when set.” Specific. Testable. Unambiguous.

Expected results

Observable outcomes that constitute success. Written as statements of what will be true when the work is complete — not steps to follow, but conditions to verify. An AI agent can use expected results as a checklist; a human reviewer can use them to assess the PR.

Conditions

Constraints that apply to the implementation. Performance requirements, accessibility standards, design system compliance, API compatibility — anything the implementation must satisfy that isn't captured in the definition. Conditions are what turn “build a thing that works” into “build a thing that works like this.”

Boundaries

Explicit statements of what is out of scope. Not everything that could be done, but everything that won't be done in this iteration. Boundaries prevent scope creep in human teams and runaway implementation in AI agents. An AI without boundaries will keep going — because completing adjacent tasks looks like being helpful.

An AI without boundaries will keep going — because completing adjacent tasks looks like being helpful.

Spec driven development and AI agents

The relationship between spec driven development and AI is not incidental. The methodology becomes significantly more powerful — and significantly more necessary — the moment AI starts executing implementation work.

When a human reads a vague spec, they apply judgment: they ask questions, make reasonable assumptions, flag things that feel off. Their output is imperfect but legible — there are traces of human reasoning the team can interrogate after the fact.

When an AI reads a vague spec, it applies pattern matching: it produces the most statistically likely interpretation of the brief, with no signal about which assumptions it made or where it was uncertain. The output is often technically competent — well-formatted, syntactically correct — but it may be solving a subtly different problem than the one you had in mind. The problem won't surface in linting. It won't surface in tests, unless your tests were written against the same vague spec. It surfaces in production, six weeks later, when a user does the thing you forgot to spec.

Spec driven development is the discipline that prevents this. A well-written spec gives an AI agent a contract it can execute faithfully, observable milestones it can report against, and explicit boundaries it won't cross without flagging. The result is AI output that is not just fast but correct — aligned with the thing the team actually wanted to build.

Spec driven development is a team practice

One of the most common misunderstandings about spec driven development is treating it as a solo engineering activity — something one person does before they start coding, between themselves and their AI.

That works for a personal project. It does not work for a team.

The value of a spec is proportional to the quality of the thinking that went into it. And the quality of the thinking is proportional to the number of perspectives that shaped it. Designers know which expected results are measurable in the interface. PMs know which conditions come from customer commitments. Tech leads know which boundaries are load-bearing for the rest of the codebase. Engineers know what's actually feasible in the timeframe.

When the spec is written by one person — usually the engineer who's about to build the thing — all of this collective intelligence stays locked in heads that aren't in the room. The AI executes against a spec that represents one perspective. The PR lands and nobody else understands what was decided, or why.

The value of a spec is proportional to the quality of the thinking that went into it.

In spec driven development done well, writing the spec is a team activity. The artifact that emerges is a distillation of the whole team's understanding of the work, before any implementation begins. This is the thing that makes AI output reliable: not better prompting, but better shared thinking upstream of the prompts.

Common objections

“This sounds slower than just building it.”

Writing a good spec takes time. Not a lot — for most features, an hour of structured thinking before building is fast compared to the debugging, rework, and misalignment you're avoiding after. The teams who feel slowest using spec driven development are usually the ones who weren't measuring the time they were spending fixing things that were built wrong the first time.

“We move too fast for this.”

Speed is a product of clarity, not a substitute for it. The teams that ship fastest over sustained periods are the ones where everyone knows what they're building and why. Spec driven development doesn't slow that down — it creates the conditions for it. What spec driven development does slow down is the illusion of speed: the kind where PRs land fast but the codebase drifts, and nobody can explain what it does anymore.

“We already write tickets. This is just tickets with more ceremony.”

A ticket is a coordination artifact. A spec is a contract. The difference is not ceremony — it's precision and durability. A ticket is designed to be read once by a human who has context. A spec is designed to be executed against by an agent that doesn't.

How Penling implements spec driven development

Penling is built around spec driven development as its core operating model. The workflow has five stages:

A Goal defines the milestone the team is moving toward. A Focus area is the spec itself — definition, expected results, conditions, and boundaries — written collaboratively by the whole team before any implementation begins. A Plan is generated by an LLM and reviewed by humans before the first commit. A Build is carried out by an AI agent via MCP, with every decision and event reported back to the team in real time. And a PR lands with the full chain of reasoning attached — from the original spec through every decision made along the way.

The result is software that is fast to ship, traceable to its intent, and understandable six months later. The spec lives in the repository alongside the code. The reasoning survives.

You can read more about the philosophy behind the methodology in our manifesto, or see the full workflow in how it works.

Is spec driven development right for your team?

Spec driven development is the right choice if:

• Your team uses AI agents (Claude Code, Cursor, Copilot) for implementation work.
• You've noticed that PRs are getting harder to review because it's unclear what was asked for.
• You or your team has felt that collective grip on the codebase is loosening — fast PRs, but nobody quite knows why the code is the way it is.
• You have more than one person contributing to a codebase and need shared context on what was decided and why.
• You want your AI output to be predictable and aligned with intent, not just syntactically correct.

If any of those sound familiar, spec driven development is worth trying. Not because it's a silver bullet, but because the alternative — continuing to treat vague briefs as contracts and hoping the AI figures it out — compounds quietly until it doesn't.

Spec-driven development isn't slower. It's deliberate. And deliberate is fast.