Spec-Driven Development in Practice - Running Requirements Definition Through Code Generation End to End with Kiro
A three-stage spec of requirements definition / design / tasks controls the output quality of the AI agent and has it generate code as intended. This article explains the structure of spec files and effective writing patterns.
What Is Spec-Driven Development
Conventional AI coding tools centered on chat conversations and code completion, in a style that responded to the developer's instructions one at a time. This approach is effective for small tasks, but in feature development that spans multiple files or in architecture changes, the AI cannot grasp the big picture and tends to generate inconsistent code. Kiro's spec-driven development is an approach to this problem. When a developer describes requirements in natural language, Kiro (1) organizes functional / non-functional requirements in a requirements document (requirements.md) and (2) defines the architecture and data flow in a design document (design.md). Kiro then (3) breaks down the implementation steps in a task list (tasks.md). These three documents become the "specification" for the AI agent, which runs each task in order to generate code.
Rule Control with Steering Files
Steering files are a mechanism for conveying project-specific rules and policies to the AI. You place them as Markdown files in the .kiro/steering/ directory and describe coding conventions, architecture policies, the libraries to use, prohibited practices, and so on. For example, you can define rules such as "always enable TypeScript strict mode," "use Zustand for state management and do not use Redux," and "always validate API responses with Zod". Steering files have an inclusion setting, and you can choose always (always loaded), fileMatch (only when a specific file pattern matches), or manual (only when specified manually). Global steering (~/.kiro/steering/) applies to all projects, and workspace steering (.kiro/steering/) is used for project-specific rules.
Agent Hooks and Subagents
Agent hooks are a feature that runs automated processing triggered by specific events (file save, Git commit, etc.). For example, you can define workflows such as running ESLint and applying automatic fixes every time a TypeScript file is saved, or running tests at commit time and aborting the commit if they fail. Subagents are specialized agents that operate in a context independent of the main agent. You can split complex tasks and, when the groups of files are independent, gain efficiency through parallel execution. For example, you can use them to proceed with the backend API implementation and the frontend component implementation at the same time. The planner agent is a special read-only agent that specializes in breaking down requirements and drawing up implementation plans. It helps you check the design before implementation and notice oversights and contradictions.
Working Together with Steering Files
Steering files (.kiro/steering/) function as a complement to specs. While a spec defines the specification for an individual feature or bug fix, steering files define the coding conventions / design policies / quality standards that apply to the whole project. With three inclusion levels, always (always loaded), manual (loaded when needed), and fileMatch (when a file pattern matches), the necessary rules are loaded while keeping context consumption down. Because the rules in the steering files are referenced automatically when spec tasks run, it becomes easier to keep code quality consistent.
Benefits of the Requirements / Design / Implementation Flow
The core of spec-driven development lies in explicitly going through the stages of requirements definition / design / implementation instead of starting to write code right away. First you organize what should be built as requirements, then turn how to achieve it into a design, and then proceed to implementation. By keeping each stage as a document, the AI and humans can share the same understanding, and you can reduce rework caused by misunderstandings. If you start implementation while things are still vague, you often end up with "this is not what I had in mind" once it is finished. However, if you firm up the intent in the earlier stages, you can reduce that mismatch at an early stage. The flow of clarifying intent step by step helps improve the accuracy and efficiency of development.
Summary - Guidelines for Using Spec-Driven Development
Kiro's spec-driven development is a method that aims to improve the quality and consistency of AI coding by proceeding from requirements definition to implementation in a structured workflow. Making the project rules explicit with steering files and automating quality checks with agent hooks helps maintain the quality of the code the AI generates. We recommend an approach of first trying spec-driven development with small feature additions and gradually building up your steering files.
References (Official AWS Resources)
The primary sources for this page are the official AWS website and documentation. Check the official pages below for the latest specifications and pricing.
If this page and the official documentation disagree, treat the official documentation as authoritative.