When Kiro first introduced spec-driven development, the concept immediately resonated with me. I joined the waitlist early, but for a long time I mostly stayed in “vibe mode”: coding interactively, using spec mode only when a feature or user story required more deliberate planning.
During this hackathon, I flipped the paradigm. I built an entire studio application—end-to-end—fully driven by spec mode. The goal was straightforward: give users an intuitive environment for controlling and managing image generation, without the repetitive prompting or node wrangling that tools like ComfyUI often require. In this post, I’ll walk through the approach, focusing on how I used steering docs, hooks, and spec prompts.
Preview
This studio lets users generate images, edit objects within those images, and refine results through direct manipulation instead of constant prompting.
Development is still ongoing, and I’ll release the full project soon.
Methodology
Steering doc
I began with the steering docs from the repo kiro-best-practices. They provide a strong, opinionated baseline for consistent development.
From there, I adapted the docs to match my own preferences:
- keep all folder names lowercase
- no emojis anywhere—comments or console output
- enforce short, clean, structured code comments
- standardize file naming and module layout
These documents became the “constitution” for the codebase. Agents followed them automatically, which minimized how much instruction I needed to include in each spec.
Hooks
If the steering docs define the “laws,” then hooks are the reusable tools. They encapsulate repeatable actions that the agent can call when needed. I used many hooks, but three were especially helpful during this hackathon.
1. Git Commit Generator
Spec mode often spans multiple features in a single development pass, making commit messages harder to summarize manually.
This hook analyzed all relevant changes and produced structured, meaningful commit messages automatically.
2. Cleanup Unused Files
As specs evolve, agents rewrite code, and old files accumulate.
This hook:
- identifies entry points in the frontend and backend
- builds a dependency graph
- removes anything not referenced
It kept the repository clean and manageable.
3. Reorganize Hook
Specs can generate dozens of files inside one folder. The reorganize hook groups files by feature and dependency, making the entire codebase easier to navigate and maintain.
Specs
With a UX background, spec mode fits naturally into my design process. I typically begin with the interaction flow:
- What should the user be able to do?
- What are their inputs?
- What processing stages are required?
- What is the expected user-facing output?
Once this is defined, Kiro derives:
- requirements
- design docs
- tasks
Then the agent executes them. This let me focus on architecture, interaction design, and catching subtle issues, while the agent handled most of the implementation.
Discussion
I was able to build a fully functional application from scratch in two weeks. The agents produced the bulk of the feature code, and I focused on guiding the design, resolving deeper issues, and ensuring architectural consistency.
Still, I ran into several UX challenges worth discussing.
Managing Requirements, Designs, and Tasks
Kiro’s structured requirement and design documents are extremely useful—until you try to edit them manually.
If I removed a requirement, my instinct was to look for a “Save” button. Instead, the only option was Refine, which regenerates the entire document and discards my edits. This felt counterintuitive and created uncertainty around whether changes were being preserved.
Refining design docs can also override edited requirements, depending on how the system resolves context. This breaks the expected editing flow.
Context Management in Specs
Sometimes the agent ignored existing context—even after reading the codebase and the requirements.
For example, a feature needed my existing image-editing module, but the agent generated a new image workspace instead. I assumed it would reconcile this during execution, but it didn’t.
The burden is currently on the developer to remember to manually include # references. A more collaborative context-management mechanism—where the agent proposes relevant contexts and asks you to confirm—would significantly reduce cognitive load.
Credit Efficiency and Model Selection
I used around 1100 credits for the entire development.
Most of the time I stayed in Auto mode, switching to Opus 4.5 for complex reasoning tasks. Auto mode clearly saved credits, but the model selection process wasn’t very transparent.
Ideally, Kiro would allow developers to:
- choose different models at the task level or spec level
- declare that a particular feature should use a stronger model
- view or audit which models were used for which tasks
As inference costs decrease, I hope credit budgets will become more flexible.
UX Observations
Two UX issues stood out during the hackathon.
1. Using # as the Hook and Context Operator
Using # to reference files and documents felt unnatural.
Across tools—code editors, Slack, email, project boards—@ is the default mental model for referencing something. I repeatedly typed @ by muscle memory.
Images are also part of context, yet they use a separate “add image” UI. It would be helpful to allow customization or a unified reference system.
2. Session Navigation
Spec-driven development generates many sessions. Navigating them is not frictionless.
- Active tasks are accessible through Task List.
- Historical sessions require clicking a small restore session button.
This creates unnecessary precision requirements (Fitts’ Law). Clicking the entire session row would be far faster and more intuitive.
Closing Thoughts
This hackathon demonstrated how powerful spec-driven development can be. I shipped a complex, fully functional application in just two weeks. The agents handled implementation at scale, while I focused on architecture, UX, and the complex logic that required human judgment.
There are still UX gaps—especially around document editing and context management—but the overall development experience was impressive. I’m excited to share the full project soon.
Top comments (0)