Spec
In AI-assisted development, a spec is neither a decorative document nor a bureaucratic formality. It is the artifact that allows humans and agents to share the same interpretation of the work.
A spec answers questions that a user story does not usually aim to settle completely:
- What exact behavior should be produced?
- What is out of scope?
- What technical constraints must be respected?
- What edge cases must be considered?
- How will we know the result is right?
- What decisions should the AI not make on its own?
By internal Scrum Manager convention, the term takes the feminine gender in Spanish: una spec, la spec, las specs.
What it is for
A spec serves to reduce ambiguity before delegating work to a person, a team, or an AI agent.
In AI contexts, its importance grows because the agent tends to fill in the gaps with probable decisions. Sometimes it gets them right. Other times it introduces assumptions that the team discovers too late: unnecessary dependencies, incomplete security criteria, integration errors, code duplication, or unwanted behaviors.
A good spec helps to:
- align product, technology, and business;
- turn intent into verifiable behavior;
- prevent the AI from inventing critical decisions;
- make human review easier;
- create tests and acceptance criteria;
- maintain traceability between need, implementation, and validation;
- reduce rework;
- prevent a prototype from being mistaken for production-ready software.
Difference between user story and spec
A user story and a spec do not compete. They serve different purposes.
| Artifact | Main function | Question it answers |
|---|---|---|
| User story | Communicate a need from the user's perspective. | Who are we building this for, and why does it matter? |
| Spec | Define behavior, boundaries, constraints, and verification. | What exactly must be produced, and how will we know it is right? |
The user story keeps the focus on value, the user, and conversation. The spec translates that intent into a more precise format, which is especially useful when part of the work will be carried out by AI.
Example:
| User story | Spec |
|---|---|
| "As a user, I want to receive a notification when an assigned document is modified so that I find out about relevant changes." | Defines allowed channels, user preferences, events that trigger notifications, maximum frequency, templates, errors, permissions, tests, and acceptance criteria. |
The story opens the conversation. The spec prepares the execution.
What a good spec should contain
A spec doesn't need to be long, but it does need to be clear enough. Its content depends on the type of work, but it usually includes:
| Element | Purpose |
|---|---|
| Goal | Explains what is to be achieved and why. |
| Context | Places the task within the product, user, system, or problem. |
| Scope | Defines what is in and what is out. |
| Expected behavior | Describes how the system should behave. |
| Acceptance criteria | Indicate how it will be checked that the result meets expectations. |
| Edge cases | Cover boundary situations, errors, invalid data, or exceptions. |
| Technical constraints | Architecture, APIs, data models, security, performance, or compatibility. |
| Dependencies | Required systems, teams, services, or decisions. |
| Boundaries | Always / Ask First / Never rules. |
| Verification evidence | Tests, logs, screenshots, commands, results, or review criteria. |
The quality test for a spec is simple: a person or agent who was not part of the original conversation should be able to understand what is expected, what they must not touch, and how to show that they are done.
That test has a name in the ecosystem: the Clarity Gate. Can a different agent, or a new session of the same agent, generate functionally equivalent code by reading only the spec? If not, the spec contains implicit assumptions (knowledge that lived in the original conversation and was never written down), and those assumptions are the main cause of drift between spec and code. It also serves as a diagnostic when something fails: if the spec is correct and the code does not comply with it, the task is regenerated; if the spec is incorrect, it is corrected and the task is regenerated.
Basic example
Spec: user email change Objective: Allow an authenticated user to change their primary email without compromising account security. Scope: Includes email change, verification of the new email address, and audit logging. Does not include password change or two-factor authentication management. Expected behavior: - The user enters a new valid email. - The system checks that it is not associated with another account. - The system sends a verification link to the new email. - The primary email only changes once verification is completed. - The event is recorded in audit_log. Edge cases: - Invalid email. - Email already in use. - Expired verification token. - Unauthenticated user. - Email service unavailable. Always: - Keep an audit log. - Do not reveal whether an email belongs to another account. Ask First: - Before modifying the existing authentication flow. Never: - Do not change the email without verification. - Do not log full tokens. Acceptance criteria: - Given an authenticated user When they request to change their email to a valid, unused one Then they receive a verification email And the primary email does not change until it is verified.
Specs in Given/When/Then format
A practical way to write parts of a spec is to use Given/When/Then scenarios.
Given [context or initial state] And [additional conditions] When [action or event] Then [verifiable expected outcome] And [additional behaviors]
This format helps because each "Then" can become a verifiable test. It also forces specificity: "the system works correctly" is not a checkable outcome; "the server responds with HTTP 200 and returns a token that expires in 24 hours" is.
The Given/When/Then format is not mandatory for every spec, but it is very useful for functional behavior, acceptance criteria, and edge cases.
What a spec is not
A spec is not:
- a longer user story;
- an improvised prompt;
- documentation written after building;
- a contract closed to any change;
- an endless list of requirements;
- a generic explanation of the idea;
- a collection of wishes without verifiable criteria.
The spec comes before implementation. If it is written afterward, it may be useful documentation, but it does not fulfill the purpose of Spec-Driven Development.
Spec and Prompt
A spec is not the same as a prompt.
| Concept | Function |
|---|---|
| Spec | Defines what must be built, within what limits, and how it will be verified. |
| Prompt | Operational instruction given to the model or agent to carry out a task. |
The prompt can use the spec as its basis. For example: "implement task 2 of this spec, respecting the boundaries, and update the tests." But if the spec does not exist, the prompt tends to carry too many responsibilities: context, intent, architecture, limits, criteria, and verification.
For simple work, a good prompt may be enough. For production work, the spec reduces risk.
Spec and Spec-Driven Development
In Spec-Driven Development (SDD), the spec is the central artifact. The team does not jump straight from wish to AI-generated code. First it defines the specification, reviews it, and only then uses it to guide the implementation.
This changes the relationship with the AI agent. In vibe coding, the agent acts as a conversational partner: you ask it for something, test the result, correct it, and ask again. In SDD, the agent works against a spec: it has a contract of behavior, boundaries, and verification.
The spec turns the agent into a controlled executor, not an implicit decision-maker.
Levels of spec usage
Not all specs carry the same weight in the work system.
| Level | Use of the spec | Example |
|---|---|---|
| Spec-first | Written before implementation; can be discarded once the work is done. | A specific sprint task. |
| Spec-anchored | Kept as living documentation of the feature. | A module that will keep evolving. |
| Spec-as-source | The spec becomes the main artifact; the code is generated or regenerated from it. | Advanced contexts with mature tools and high discipline. |
Most teams should start with spec-first or spec-anchored. Jumping to spec-as-source too early can create rigidity and false expectations.
Living specs
A living spec evolves with the product. It does not stay frozen after the first implementation.
It can change when:
- a new edge case is discovered;
- a business rule changes;
- an ambiguity is detected;
- an API is modified;
- a technical constraint emerges;
- something is learned in production;
- a retrospective identifies a definition flaw;
- a test reveals unspecified behavior.
Maintaining living specs requires discipline. If the spec and the product diverge, the spec loses its value as a source of truth.
A practical pattern separates what is the current truth from what is merely a proposed change: the system specs live in one directory, the proposals in another, and when a change is completed, its spec is merged into the current one and the proposal is archived. What is completed gets archived; a spec that describes a change already made is history, not living documentation.
Specs in brownfield and greenfield projects
In a greenfield project, the spec helps prevent AI from making foundational decisions without review: architecture, dependencies, security, data model, or testing patterns.
In a brownfield project, the spec is even more critical. The agent must respect what already exists: public contracts, technical debt, repository patterns, migrations, tests, integrations, and behaviors that may not be well documented.
In brownfield, a good spec should include more context and more boundaries. It is not enough to say what you want to add. You have to say what must not break.
Specs and Definition of Ready for AI
In teams working with AI, a task should not be assigned to an agent just because it seems automatable. It must be ready.
A Definition of Ready for AI may require that:
- the spec is complete and reviewed;
- the agent has access to the necessary context;
- the acceptance criteria are verifiable;
- the technical constraints are clear;
- Always / Ask First / Never boundaries are in place;
- the human review time has been estimated;
- there is a person responsible for validating the output.
If the spec is missing or too ambiguous, the agent will produce quickly, but the team will pay later in review and rework.
Specs and Definition of Done
The spec also helps verify whether something is done.
The Definition of Done defines general quality criteria. The spec defines criteria specific to the feature or task. The two complement each other.
An AI-generated change should not be considered done just because the agent says it has completed the work. It must be verified against:
- the spec;
- the acceptance criteria;
- the Definition of Done;
- tests;
- human review;
- security checks;
- integration with the real system.
The spec as a conversation tool
Although the spec is more precise than a user story, it should not eliminate the conversation. On the contrary: a good spec makes doubts visible.
When writing it, questions such as these tend to come up:
- What happens if the user does not have permissions?
- Which data are mandatory?
- What behavior do we expect if an external service fails?
- What must the agent not modify?
- What decision must the Product Owner make?
- Which part requires technical validation?
- Which cases do we still not understand?
These questions are part of the spec's value. If a spec does not spark any conversation, it may be because the task was simple or because the assumptions remain hidden.
AI and the spec
AI can help write specs, but it should not be solely responsible for defining them.
It can help with:
- detecting ambiguities;
- proposing edge cases;
- turning user stories into Given/When/Then scenarios;
- identifying dependencies;
- suggesting acceptance criteria;
- reviewing consistency;
- comparing a spec with the Definition of Done;
- generating draft tests.
But the important decisions remain human: scope, value, priorities, boundaries, acceptable risks, and accountability for the outcome.
An AI can help draft a spec. It cannot decide on its own what risk the product should take on.
Quality of a spec
A good-quality spec is usually:
- clear: avoids vague terms;
- sufficient: contains the necessary context;
- scoped: does not try to solve everything;
- verifiable: makes it possible to check whether the result meets expectations;
- actionable: serves to execute, review, and test;
- living: can be updated as learning evolves;
- human-readable: is not written only for the tool;
- AI-processable: reduces ambiguity and implicit decisions.
A bad spec can be long and still useless. A good spec can be brief if it defines what is essential.
Signs of a weak spec
A spec probably needs work if:
- uses expressions such as "easy," "intuitive," "fast," or "appropriate" without being specific;
- only describes the happy path;
- does not include errors or edge cases;
- does not state what is out of scope;
- does not define verifiable acceptance criteria;
- does not mention relevant technical constraints;
- allows several incompatible interpretations;
- does not say when the agent must ask for approval;
- cannot be translated into tests;
- nobody knows who should validate it.
Best practices
To write and use specs:
- Start with the intent. Don't lose the link to the user problem.
- Define the negative scope. Stating what is out of scope prevents a lot of rework.
- Include edge cases. The happy path is not enough.
- Use Given/When/Then when it helps verify behavior.
- Add Always / Ask First / Never boundaries.
- Separate facts, decisions, and assumptions.
- Avoid huge specs. Split the task if it is too large.
- Update the spec when learning changes.
- Have someone review it before delegating it to AI.
- Connect the spec to tests and the Definition of Done.
Each task is given only the portion of the spec that applies to it, not the whole document: the more instructions pile up in the context, the lower the probability that the agent will comply with each one (the curse of instructions). And for the acceptance criteria that matter most, EARS notation ("While [precondition], when [event], the system shall [response]", with five patterns) makes them verifiable and narrows the agent's room for interpretation; it is used where it reduces ambiguity, not on every line.
Common mistake
Confusing detail with quality. A spec doesn't get better by piling up pages, screenshots, or instructions. It gets better when it reduces ambiguity, makes boundaries clear, and allows the result to be verified. A huge but imprecise spec can be worse than a short, well-structured one.
Resources
🏦 SDD - Spec Driven Development en equipos ágiles [SDD - Spec Driven Development in Agile Teams, in Spanish]Skill Arena · Scrum Manager
📊 Guía didáctica SDD [SDD Teaching Guide, in Spanish]Resources · Scrum Manager
References
- Böckeler, Birgitta. (2025). "Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl," MartinFowler.com.
- GitHub. (2025). "Spec-driven development with AI: Get started with a new open source toolkit," GitHub Blog.
- GitHub. (2025). "Spec Kit," GitHub.
- Osmani, Addy. (2026). "How to write a good spec for AI agents," addyosmani.com.
- Scrum Manager. (2026). SDD – Spec Driven Development en equipos ágiles [SDD – Spec Driven Development in agile teams, in Spanish]. Scrum Manager.
- Scrum Manager. (2026). Scrum en equipos con IA [Scrum in teams with AI, in Spanish]. Scrum Manager.
See also
Want to advance in agility? You can search for course and exam calls or go at your own pace by becoming a member of the Agile Club. This membership includes exclusive resources, e-learning classrooms, and access to Skill Arena: a space to practice and measure your agile skills at your own pace.