Experience with Kiro's spec driven development methodology
In this blog, I've shared my experience of building an application with Spec driven methodology of Kiro. Will also talk about some additional feature of Kiro.
Recently, I have been exploring Kiro and experimenting with its Spec driven development methodology. In this blog, I'll share my experience of building a real-world application with this methodology with fellow developers. Will also talk about some additional features of Kiro (Steering, Agent hook etc)
How do you start with Kiro?
- Please refer to https://kiro.dev/ to download Kiro (for Windows) and start to use after authentication using either of options (Google, Git, Builder Account, Organization IAM Identity Center).
- You can also use KIRO CLI. Get WSL installed first and then install Kiro CLI by running
- curl -fsSL https://cli.kiro.dev/install | bash.
- Run kiro-cli login --use-device-flow to authenticate.
Let us understand Spec Driven development,
Spec driven development is a methodology that emphasizes requirements gathering, architecture design consideration at the forefront of development. It emphasizes collaborative planning with stakeholders. It provides structured approach towards software development lifecycle.
How is it different from Vibe coding?
Vibe coding is great for quick experimentation. It involves immediate code generation based on ideas. It relies heavily on AI context window for project knowledge. It involves individuals focused development with limited touchpoints.
While vibe coding can be effective for rapid prototyping and spec driven development becomes essential when building production applications and working with multiple teams.
Use case considerations
For this exploration, I’ve considered building a PDF splitter service. A large energy and utility client in Europe often scans and batches multiple invoices into a single PDF file. They have requirement to create a PDF splitter service that divides the batch PDF into individual invoices using blank pages as separators. Additionally, the application includes dashboards that monitor file submission time, file size, the number of split files, and other relevant metrics.
As part implementation, used Kiro’s spec driven development methodology to build cloud native PDF splitter service using serverless technology (API Gateway, Lambda, S3, DynamoDB, Cloud Front Distribution) and React based UI dashboard. Infra was provisioned using Terraform scripts.
Instead of starting with code, I provided a single prompt describing the problem and selected the Spec option. From there, Kiro guided the solution through structured phases.
Prompt used,
I want to build a PDF splitter service using AWS Lambda and API Gateway that can accept PDF document as input and split the PDF file based on blank pages in between PDF file. PDF file size should not exceed more than 5 MB. It contains invoices details. It should also write metadata about PDF file, its size, timestamp to process etc. in DynamoDB table. I also want to build a dashboard which will show details of PDF files processed, size etc. after reading metadata from DynamoDB table. This solution should be able to generate required code as needed in python programming and UI dashboard in React. It should also generate business stories.
As mentioned already, Spec driven methodology starts with the requirement, then requirement gets translated to design artifacts and then it gets scaffolded into all the tasks that need to be implemented by the agent. I liked the discipline it enforced. I had to review and validate each phase (requirement --> design --> task) before moving forward.
It has created requirement.md, design.md to ensure target architecture aligns with it and then follow task.md which has detailed implementations steps for my PDF splitter service.
Requirement.md
It includes user stories with acceptance criteria in the WHEN THEN format, like how a product owner defines requirements.
Design.md
It includes an overview of the technical architecture and implementation considerations. It provides comprehensive details on system components and their interactions. Additionally, it outlines the AWS architecture, along with API endpoints, including request and response specifications.
Task.md
It includes an implementation plan with a detailed task-level perspective. It also ensures traceability of tasks to the previously defined requirements, maintaining a focused and organized approach throughout the implementation process. It makes complex features manageable through small steps.
Next, let's discuss another key feature of Kiro.
Steering documents
As name suggests, steering document steers agent/LLM. It offers guidance for your project workspace. Rather than repeatedly clarifying your conventions in each conversation, steering files help Kiro reliably adhere to your chosen patterns, libraries, and standards.
So, when developers write prompt to Kiro, steering documents along with code, chat history and prompt are fed to LLM as context. So that LLM response is mostly consistent.
It has following benefits,
Benefit | Description |
|---|---|
Consistent code
generation | Generated code follows
established pattern |
Reduced
Repetition | You don't have to repeat workspace standards every time; Kiro
keeps track of your preferences. |
Team alignment | All developers, new or experienced, follow the same standards. |
Scalable
Project Knowledge | Documentation adapts with your codebase, tracking decisions and
patterns as your project progresses. |
Treat it like your code: push it to Git so all developers can access it. Keep it updated whenever your project changes.
Store the steering document in. kiro**/steering/** to apply it only within that workspace. Alternatively, it can be stored in user home directory under ~/.kiro/steering/ and applied to all workspaces.
In case of conflicting instructions between global and workspace steering, Kiro will prioritize the workspace steering instructions.
How do I create a steering document?
You can create foundational steering files which gets created from existing code that you have loaded to the workspace. As part of foundational steering files, it creates 3 files product.md, tech.md and structure.md files.
You can generate these files as follows:
- Navigate to the Steering section in the Kiro panel
- Click the Generate Steering Docs button, or click the + button and select the Foundation steering files option
- Kiro will create three foundational files:
Product Overview (product.md) – Summarizes your product's purpose, users, features, and business goals, helping Kiro align technical solutions with your objectives.
Technology Stack (tech.md) – Lists frameworks, libraries, tools, and constraints so Kiro prioritizes your stack when recommending implementations.
Project Structure (structure.md) – Details file layout, naming, imports, and architecture to ensure generated code integrates smoothly into your codebase.
You can also create custom steering file – e.g security.md which specifies security requirement for the project. With custom steering, you can integrate MCP server. Therefore, it facilitates the integration of domain-specific expertise.
Agent Hook
Agent hooks automate your workflow by triggering set agent actions when certain events happen in your IDE.
For the PDF splitter project, added a hook to move all Kiro-generated markdown files tracking its changes into a separate folder. It helped in keeping project workspace structured.
You can also create hook for any change to specific files e.g – if you are adding functionality to your backend python code, it will also update its test script and execute the test. All these route tasks can be automated through hooks.
MCP server integration
Kiro IDE also lets you to integrate any MCP server that you want to be integrated. As part of this project, I had integrated aws-diagram mcp server. Kiro was able to create AWS architecture for this application using that MCP server.
It reduced effort needed to visualize and design AWS architecture. It could generate architecture directly from its context.
Please refer to Welcome to AWS MCP Servers | AWS MCP Servers for list of AWS MCP servers for your usage.
What I’ve liked with Kiro’s spec driven methodology?
- It could potentially be game changer in software development life cycle because of its approach. Fewer iterations are needed to achieve the final output. It promotes clarity and alignment early in the SDLC phase.
- It lets you execute the task from task.md file directly while using Kiro UI.
- It keeps context /chat history for any task because it maintains separate session. You can comeback latter to query on the task and act further on the specific task.
- It shows context usage % in your context window, allowing you to monitor its consumption
- When context usage hits its limit, it summarizes the context and starts a new session. It helps you manage context window for you.
Where can it improve?
It would have been better to have retry mechanisms for the task that has already been completed in the task.md detailed task list. Otherwise, you need to provide prompt in the chat to retry the task
Conclusion
Kiro spec-driven methodology enforces human in the loop in every phase (requirement, design, Implementation). As requirement and design are confirmed upfront, it ensures quality of the outcome because your implementation would follow design & requirement. It uses AWS Bedrock to make calls to LLM. While generated code must be validated, structured approach significantly reduces ambiguity and rework. Keep in mind, you as developer are doing git check in, not Kiro. It is important that you are comfortable with each line of code generated before pushing to git repo.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article