Spec-driven agentic development turns a vague product request into a sequence of reviewable artifacts before any code is changed. Instead of asking a coding agent to jump directly from prompt to patch, the workflow separates intent into requirements, design, and implementation tasks. Each phase has a different review question: what behavior is required, how should the system satisfy it, and what concrete edits should be executed.
The pattern is useful because autonomous coding agents are very good at filling in gaps, and that strength is also a risk. If the request is underspecified, the agent may silently choose product behavior, architecture, edge-case handling, and rollout order. A spec workflow creates explicit checkpoints where humans can correct those choices while the cost of changing direction is still low.
Kiro’s feature-spec workflow is one concrete implementation: a feature starts as either requirements-first or design-first, then produces structured files for requirements, design, and tasks. The transferable lesson is broader than one IDE. Any agentic engineering system can improve predictability by requiring structured requirements, traceable design decisions, and executable task decomposition before opening the edit loop.
A requirements-first flow captures externally visible behavior before choosing an implementation. The source material uses user stories and EARS-style acceptance criteria, such as WHEN [condition] THE SYSTEM SHALL [behavior]. This structure makes each requirement testable and makes missing edge cases easier to spot.
The design artifact translates requirements into architecture: components, sequence flows, data models, interfaces, error handling, and testing strategy. It is not just documentation after the fact. It is the contract that prevents the implementation phase from inventing architecture while files are already being edited.
The task artifact breaks the design into discrete units with dependencies and expected outcomes. A coding agent can then execute one task at a time, preserve progress, and expose a small review surface after each change. This is especially valuable when the overall feature spans many files or requires multiple verification passes.
A spec is not only a planning document; it is a control surface. It constrains what the agent may change, defines success criteria, and provides checkpoints where humans can approve, reject, or revise the next phase.
The workflow begins by converting a user request into behavior statements. Good behavior statements identify the actor, triggering condition, expected system response, error cases, and non-functional constraints. For agentic work, the important shift is that the prompt is no longer the whole source of truth; the generated requirements become the artifact under review.
## Requirement: Password Reset
User story:
As a registered user, I want to reset my password so that I can regain account access.
Acceptance criteria:
WHEN a registered user requests a reset link
THE SYSTEM SHALL create a single-use token that expires after 30 minutes
WHEN a reset token is expired or already used
THE SYSTEM SHALL reject the password update and display a safe error message
WHEN a password reset succeeds
THE SYSTEM SHALL invalidate all active sessions for that accountOnce requirements are approved, the agent derives a design. This step should include enough technical detail for another engineer to predict the edits: affected modules, storage changes, API contracts, sequence diagrams or request flows, security decisions, failure modes, and test strategy. If the design cannot explain how every requirement is satisfied, the workflow returns to requirements or design refinement before code generation.
The final phase turns design into a checklist. Each task should be independently reviewable and ordered by dependency. A task like “implement password reset” is too broad; a better breakdown separates schema migration, token creation, endpoint handler, email dispatch boundary, session invalidation, tests, and documentation. This gives the agent a clear stopping point and gives reviewers a smaller diff.
Spec-driven development is strongest when product behavior is not obvious. Authentication, billing, permissions, deletion flows, imports, and notification systems all contain edge cases that should be decided before implementation. Requirements force those edge cases into explicit acceptance criteria.
A design-first variant works well when the technical direction is known before product behavior is fully written. For example, a team might know that a service must move from synchronous request handling to an event-driven pipeline. The design can define the target architecture, then requirements and tasks can be derived from that architecture.
In an autonomous coding environment, spec artifacts provide natural approval gates. A human reviews requirements before design, reviews design before tasks, and reviews task execution before merge. This keeps the agent productive without allowing it to make irreversible product or architecture decisions unnoticed.
Keep feature specs in the repository near the code they govern. This makes the spec visible in review, lets CI check task completion conventions, and gives future agents durable context for follow-up work. A common layout is one directory per feature with separate requirements, design, and tasks files.
.specs/
password-reset/
requirements.md
design.md
tasks.md
# tasks.md
- [ ] Add reset token table with expiry and used-at fields
- [ ] Implement token creation service with rate-limit boundary
- [ ] Add request-reset and confirm-reset endpoints
- [ ] Invalidate active sessions after successful reset
- [ ] Add unit and integration tests for expired, reused, and valid tokensAssign stable identifiers to requirements, then reference them from design sections, tasks, and tests. Traceability helps reviewers verify that every requirement is implemented and that no task exists only because the agent improvised extra scope.
REQ-3: WHEN a password reset succeeds
THE SYSTEM SHALL invalidate all active sessions for that account
Design mapping:
- SessionStore.invalidateAll(userID) runs in the same transaction as token consumption.
- Existing refresh tokens are deleted before the endpoint returns success.
Task mapping:
- T4 implements SessionStore.invalidateAll.
- T7 adds integration coverage for REQ-3.When requirements change after design, do not manually patch every downstream artifact by memory. Regenerate or explicitly reconcile the design and task list against the revised requirement. This avoids stale tasks that implement behavior no longer desired.