Spec-driven development in Jira
Spec-driven development means writing a structured spec before an agent builds, so it builds the right thing instead of a plausible guess. In Jira, that spec lives in the work item you already run on, once it carries real intent: outcomes, scope, constraints, and acceptance criteria. A work item can hold the full spec for one task, or one slice of a larger feature spec split across several work items.
This guide covers what makes a spec agent-ready, why the work item is the right home for it, and how to write your first one. In short, spec-driven development in Jira gives you three things:
A single source of truth the agent builds from and the reviewer checks against
Acceptance criteria that define done for both the agent and the person
Less rework, because intent is settled before the agent writes a line of code
What is spec-driven development?
Spec-driven development is a practice in which you write a structured spec that defines what to build and how success is measured, and the agent implements it, rather than guessing from a one-line prompt.
The spec becomes the source of truth. It drives the plan, the build, and the check, and in Jira all three happen on the same work item. The idea predates AI, as it grew out of API design and formal-methods practice, where you define behavior before you build it.
The definition keeps shifting as the tools mature, so treat it as a practice, not a fixed spec format. What stays constant is the core move: define the work before the agent builds it.
The difference comes down to when you resolve ambiguity. Vibe coding resolves it after the code is written; spec-driven development resolves it before.
Vibe coding: you steer the agent with prompts and accept what it gives back, so the scope, constraints, and edge cases it assumes surface after the code exists.
Spec-driven: you settle intent, constraints, and acceptance criteria first, so the agent builds to a definition instead of a hunch, and review checks against that same definition on the work item where it lives.
For code that has to survive in a real codebase, an agent without settled context can solve the ticket too literally and miss the constraint that mattered. That is where rework starts.
Two things prompts tend to blur: the spec is what you're building, the plan is how it gets built. Spec-driven development settles the what first, then builds the how from it. That's the step the plan mode in AI coding tools often skips: it drafts the how straight from a prompt, with usually no agreed spec behind it.
Plan mode can stand in as a lightweight spec, but it drafts the “how” from a prompt in the moment, not from an agreed spec that persists on the work.
Why specs matter for AI coding
When code generation gets cheap, the hard part is no longer writing code. It is defining the right thing to build. That makes the spec, not the prompt, the highest-leverage artifact you produce.
A one-shot prompt leaves the gaps to the agent, which fills them with assumptions and produces code that looks right but solves the wrong problem. A spec closes those gaps first, so the agent builds toward a definition rather than a guess. In Jira, that spec is the work item your team already plans, assigns, and reviews on.
What goes into a spec an agent can build against?
An agent-ready spec answers the questions a good engineer would ask before starting. In Jira, these live in the work item's summary, description, linked requirements, and acceptance criteria. Six elements matter:
Outcomes: what the change should achieve, in terms a reviewer can check.
Scope: what is in, and just as important, what is out.
Constraints: the architecture, security, and performance limits to respect.
Prior decisions: context already settled, so the agent does not relitigate it.
Task breakdown: the work split into steps small enough to verify.
Acceptance criteria: the testable definition of done the agent builds toward and is reviewed against. In Jira they live on the work item, and an AI code review can check the change against them before it reaches a person.
How the work item becomes the spec in Jira
A well-formed work item can serve as the spec the agent builds from and reviews against. The spec can also live in a linked document, which is how many SDD tools work; Jira just lets it live where the work already runs. It is spec-grade when it carries the six elements above. A one-line "fix the login bug" work item is not.
Keeping the spec on the work item has one structural advantage: it sits where the work already lives, so it is harder to abandon than a markdown file in a repo nobody reopens. That does not make it self-maintaining. It just means the spec and the work never drift apart.
Everything travels together: summary, description, linked Confluence requirements, and acceptance criteria, in one place the agent and the reviewer both read.
A repo file, by contrast, sits apart from where work is tracked, reviewed, and closed, so it goes stale the moment the plan changes.
The same work item becomes the review surface once the agent is done, the place your team aligns on requirements and open questions.
Jira defines plans with clear requirements, tasks, and estimates built in.
How Jira Planner generates a structured spec
The previous section covered the baseline: turning one work item into a spec yourself. Jira Planner is for complex initiatives spanning several teams, where writing every spec by hand does not scale. It starts from the initiative and breaks it into structured work items, each with its own spec.
Jira Planner is the accelerator, not the baseline. The baseline SDD method is a well-formed work item plus acceptance criteria, and every team can do that today. Jira Planner speeds up the hardest part of that work: turning a complex, ambiguous request into a structured spec.
For complex projects, Jira Planner draws on the Teamwork Graph, including your codebase, Jira and Confluence history, and team context, to define requirements and generate a structured technical spec in Confluence, ready for a developer or coding agent to build on. One plan, many audiences: readable by a human, useful to an agent.
What it does:
Provides a shared surface for you and your team to collaborate on, aligning upfront before an agent executes.
Pulls context from across your work, so the spec starts from what your team already knows instead of a blank prompt.
Produces a spec that reads clearly for a person and parses cleanly for an agent, so the same artifact serves review and execution.
Keeps the spec in Confluence, linked to the work, so intent and decisions stay on the record.
Jira Planner turns rough ideas into structured, agent-ready specs
Jira Planner is in early access — sign up for the waitlist
How to write your first agent-ready spec in Jira
Take one work item and turn it into an agent-ready spec by hand, with the six elements as your checklist.
Start from a work item. Capture the outcome, scope boundaries, and constraints in the description, not just a title.
Turn intent into a structured spec. This is the real SDD work. Shape prior context into outcomes, scope, and constraints on the work item, so the agent inherits a definition.
Write testable acceptance criteria. These are the contracts the agent builds toward and the reviewer checks against. Most criteria often need a few passes before they are testable.
Assign it to a coding agent. A spec-grade work item gives the agent enough to implement and open a pull request tied back to the item.
Review the PR against the criteria, then refine. Tighten the spec where the agent guessed, and reuse the pattern on the next work item.
Frequently asked questions about spec-driven development
Do I need Jira Planner to do spec-driven development?
No. The baseline is a well-formed work item with acceptance criteria, which any team can write today. For complex work, Jira Planner accelerates it by starting from a top-level plan, an initiative, and breaking it into structured Jira work items, each with its spec filled in, so you are not writing every one by hand.
What is the difference between a spec and acceptance criteria?
The spec defines the whole change: outcomes, scope, constraints, and context. Acceptance criteria are one part, the testable definition of done the agent builds toward and the reviewer checks against.
Is a really good prompt enough?
For small, reversible work, often yes. For anything complex or hard to undo, a prompt makes the agent guess at what you left out. A spec removes the guessing.
Should the spec live in a repo file or a Jira work item?
A work item keeps the spec where work is tracked, reviewed, and closed. That makes it less likely to drift than a markdown file in a repo nobody reopens.
Does spec-driven development slow teams down?
It adds effort up front and removes rework later. On complex work that trade is a net gain. On trivial fixes, skip the spec and prompt directly.
When should I write a spec, and when should I skip it?
Write one for complex, high-impact, or hard-to-reverse work, or anything with real architectural or security constraints. Skip it for small, reversible fixes where a quick prompt is faster.