New spec types: fix bugs and build on top of existing apps
Ankit Sharma
Product
You're migrating your monolith to microservices. The architecture is already clear: event-driven, async messaging, specific latency requirements. You just need help implementing it. Or you're fixing a bug. You know what's broken and what needs to stay the same. You want a surgical fix. What's the best way to work with an agent to achieve these goals without changing other parts of your app, or wasting tokens going in circles?
When we launched Specs and the spec-driven development workflow, we built them around the traditional PM/engineering flow: requirements first, then design, then tasks. This works great for many projects and we’ve seen hundreds of thousands of developers default to this approach when building anything new.
However, when we talked to Kiro users, we heard a clear pattern: not everyone starts from requirements. Especially when working on existing, brownfield apps, some developers came in with the technical architecture already mapped out. Others were fixing bugs and needed to carefully define what should change and what shouldn't. They didn't want to give up the structure of specs, but the current flow was not flexible enough for these types of tasks.
We didn’t want to ask developers to change how they were already approaching these projects, so today, we're shipping two new ways to use Specs: the Design-first workflow and the Bugfix Spec.
Why rigid workflows fail
When we first designed Specs, we were motivated by what Laurence Tratt calls "the circular specification problem" and "the observer effect" in software development. Tratt identifies a fundamental tension: the only way to know exactly what software we want to build is to fully specify it, but a complete specification is at least as much work as creating the software itself. This creates a catch-22 where we have to build the software to truly specify it. This is wishful thinking, especially for large projects. As Tratt observes, software occupies a "liminal state" between fantasy and reality—full of soft constraints that are hard to quantify until you actually build something. The act of creating software is itself an act of specification. That doesn’t mean working with no plan, but reaching a middle-ground that gives you enough structure so you can make progress quickly.
Requirements-first and Design-first are two sides of the same coin, each addressing different aspects of this circular specification problem:
Requirements-first works when you understand the behaviors and outcomes you need, but the technical path is unclear. You're exploring "what should this do?" before "how should it work?" Great option for net-new projects where your options are open.
Design-first works when you already have a technical vision—perhaps from experience, architectural constraints, or prototyping—and need to work backward to formalize what that system actually accomplishes. It's like whiteboarding a solution and then summarizing "what this product does." This can apply to building a new feature on top of an existing app - you have to work within your current architecture and tech stack.
Both approaches embrace iteration and feedback. Neither pretends you can perfectly specify software upfront. Instead, they meet you where you actually are in your thinking, then help you work through the circular specification problem from different starting points.
Design-first specs: start with your technical approach
Let’s consider this prompt.
The developer already knows the stack (FastAPI and mcp-python), the high-level architecture (an MCP server), and the constraints (no UI capabilities). They're not asking "what should I build?", they're asking "help me build this thing I've already designed." In this case, starting with a design document makes more sense, because it matches how they're already thinking about the problem.
So now, when you create a new Feature Spec, Kiro asks you to choose: Requirements-first or tech Design-first. If you choose tech Design-first, you pick your level of detail. High-level design for system diagrams and components, or low-level design for algorithms and function signatures. Kiro generates your design document first. You iterate on it, exploring different technical approaches. Once you're happy with it, Kiro derives the requirements from your design, which ensures they are feasible. The rest of the spec workflow is the same: tasks, implementation, property-based testing to check if implementation matches what you want.
Tech Design-first works especially well when you have a pre-defined architecture, when you're prototyping to see if something is feasible, or when you're working with strict non-functional requirements that constrain your design choices. It's ideal when the technical approach is the starting point, not the destination.
Bugfix flow: fix bugs with precision
When fixing bugs, you have a different set of constraints and goals. You're not building something new, but correcting something that exists. Your surface area is different too. Change too much, and you risk breaking something that was working fine. You want the minimum change that fixes the problem.
So what’s the best way to work with an agent to do that? We found that developers who used Specs to successfully fix bugs shared two characteristics. First, they defined the detailed scenario that caused the error, not just the error message itself. Second, they explicitly stated what should not be modified. This is how experienced developers think about bugfixes, they fix what's broken but don't touch anything else.
When you create a Bugfix Spec, Kiro follows a similar approach by generating a structured document with three sections:
Current Behavior describes what's happening now: "WHEN a user submits a form with special characters THEN the system crashes with a validation error." By being more comprehensive in this step, Kiro will better diagnose the conditions where the bug happens.
Expected Behavior describes what should happen instead: "WHEN a user submits a form with special characters THEN the system SHALL sanitize the input and process the form successfully." This tells Kiro what the solved state looks like so it can later check that it actually fixed the bug.
Unchanged Behavior describes what must stay the same: "WHEN a user submits a valid form THEN the system SHALL CONTINUE TO process it exactly as before." Instead of being implicit about what should not change, the Bugfix Spec explicitly states it. This helps Kiro check that regressions are not introduced and informs the property tests to validate.
This structure forces you to think explicitly about what changes and what doesn't, and helps the underlying model understand your intent more precisely. Kiro builds these sections for you automatically, you don't need to spend time writing this .md yourself. You can review and refine these conditions, then Kiro proceeds to create a design.md and tasks.md, just like a Feature Spec, but tailored for surgical fixes.
What makes this work well is the unique way Kiro does testing. Kiro generates property-based tests (PBTs) for all three categories. Tests that verify the current implementation has the bug. Tests that verify your fix resolves it. And tests that verify unchanged behavior continues working exactly as before. Without these PBTs, it’s difficult to check if the agent actually fixed the bug for a comprehensive set of conditions, and that the changes were indeed surgical.
Bugfix Specs shine for complex bugs that benefit from structured problem-solving, situations where regression risk is high, or when you need documentation for your fix.
Tools that adapt to you
Specs changed the way many developers approach AI development to ship solid software. But when working with existing apps, especially over large codebases, you might prefer a different approach. Sometimes you begin with requirements, because you know exactly what you want to build. Sometimes you already know the technical approach, and it’s non-negotiable. Sometimes you're fixing a bug and need surgical precision because you don't want a regression to affect all your users. Now Specs support all three use cases.
Learn more in the docs about feature specs and bugfix specs. Download or restart Kiro IDE to try these new approaches to specs.