Software developers with a lot of experience using software agents are increasingly writing longer prompts and detailed plans to generate code that has fewer errors than they would get with simper feature requests. But Amazon’s new Kiro agent IDE is taking that much further. It coerces you into holding off on generating code until you have created a sequence of technical documents that feels a lot like… waterfall methodology.

It was quite a shock to be using a cutting edge AI tool that is suggesting a philosophy that is almost forbidden in an industry where no one would claim to be using anything other than agile.

As Kiro dragged me through a requirements document, a technical design document, and a detailed implementation plan, I couldn’t help but think, “AI or no AI, this feels wrong. We abandoned this years ago.”

However, I know the problems that Kiro is trying to solve. It cleverly tells you up front that you can either “vibe” or you can “spec.” Kiro clearly prefers the latter, which is why this tool exists. Its creators know that a lot of developers aren’t telling their agents enough details to get great results, and it is going to be your project manager.

So I went through the steps to create a generic bookmark manager, the kind of demonstration you see in YouTube coding agent demos. Kiro helped me write the requirements document (which it calls a ’spec’). Then, and only when I was done with that, it guided me to create a technical design. That you are told to finish each step before proceeding is the clincher that this flow is based on waterfall ideas, though that unpopular word is, of course, used nowhere in Kiro.

After competing the next two documents, I was able to execute the resulting tasks sequentially, checking each stage before the application was finished. As I expected, the resulting application was of good quality.

I realized that a lot of how fast you can move using coding agents is dependent on how much of the requirements you know at the start. This is why people are often so successful creating custom applications for personal use: they can describe all the requirements early on, and are not going to change them later, which will cause problems. This is also why all of the YouTube demonstrations are so compelling. They are starting with a known set of features.

If you do know a lot of your requirements ahead of time, you probably are better off doing this, as you are pausing to consider many important details instead of just continuing to prompt without a good plan in place. And planning is very important for agent use! Everything else is just vibecoding, where you aren’t concerned about the code or architecture, only that your primary use cases work.

But if your client isn’t sure at the beginning what all the features will be, you aren’t going to be able to write the requirements document that Kiro wants. At least not for the whole application.

Can you still use this workflow when requirements are under development?

I remember in the industry transition from waterfall to agile, some larger organizations tried to do a series of waterfall phases, where each one was a release of a product. This didn’t work out well, because they didn’t get enough benefits from either methodology to make it worth it. Often, they ended up with the downsides of both.

But can agents handle a series of small waterfall workflows inside a project? I think the answer is yes. I tried out a few more spec, design, and implementation plans for just a few features on an open source codebase. It felt like a little too much documentation, and reminded me of why we all adopted agile. Yet I saw that this is just a lot more discipline around what some expert agent users are already recommending: that you spend a lot of time creating specifications, and then type out fewer prompts asking for code. Because the agents we have right now need what waterfall provides even more than people do.

I then left the Kiro environment and went back to Claude Code, which is my preferred tool. I tried to use waterfall there, typing out requirements, then doing some design, then generating the steps to complete. I then executed. It worked out well for the same reasons it did in Kiro: it got me to consider tradeoffs and include details I might not have with a series of prompts.

I will continue to use ad-hoc prompts for simple features and bug fixes. But after my experience with Kiro, I will try out the waterfall approach for larger features, complex coding tasks, and refactoring. It feels strangely old-school. Yet amid this chaotic revolution in software development, perhaps it’s exactly what we need to keep our agents doing what they are supposed to do.

Strong Project Specs are the Enabler of AI Coding Agent Success by Ed Lyons