Spec-Driven Development vs. Waterfall: What's Different for AI Coding? Transcript, AI Summary & Key Points

00:00 If you've been using AI coding tools, you're probably familiar with the scenario where you say, "Hey, I want you to add a new feature to my application or maybe fix a bug and bam, it goes off and with the help of that AI coding assistant or tool generates you that code and functionality. But is it exactly what you wanted?" Well, in some cases, no. and you have to go again and again through the prompt in order to explain something maybe that you could have just done if you had written it down first.

00:32 And so a lot of teams are doing that and emphasizing the initial specification and the prompt that they want this AI model to follow. And this is a technique that's known as specd driven development that has become increasingly popular recently. But when a lot of developers hear about this, they say, "Wait, isn't this just the waterfall method," and that's a fair question.

00:57 So today in this video, we're going to draw out both of these techniques and see the similarities and differences between them. So here's the waterfall method to building software. It's a very traditional step-by-step approach where we start with the requirements for the project. We take those and build out some type of design. Once that's been validated, we go to actually build the project.

01:21 And then once that artifact is ready, we test it to make sure it's validated for what the users or customer wants. And then finally, we take that and deploy that to some type of production environment. But the key here is that each step finishes before the next one starts. So when we take a look at the requirements, this is where our specification actually lives for waterfall, right?

01:37 It's all the way up here at the top. And a few things happen when we had this specific methodology of waterfall. First off, that spec is written up front and all of the spec is written before anyone even writes a single line of code over here. Now, there's also handoffs because one team might be writing requirements and they'll hand that off to design which then hands off to developers and so on.

02:09 And because of that, change can get very expensive because if we learn that during the build process the requirements might have been wrong, well, going up the stairs in order to fix that cost a lot. And then finally, validation also happens late and we don't really find out if we built the right thing until we get all the way down to testing the software.

02:30 And plus, by the time we deploy, that spec at the top is probably stale because no one went back up to update it. And that's a big reason why for years the industry moved away from these big upfront requirements to shorter cycles and user stories and agile. So when we're told to write a spec, some folks are skeptical. Is it just waterfall in markdown files?

02:55 Well, honestly, if you write the entire spec up front and you freeze it and hand it off to an agent, yes, it is waterfall. You end up having the same problems, but you just end up failing faster. The difference shows up once you actually start building. So let me explain. So here is specd driven development. We're also starting off with this specification, but this time it looks a bit more like a loop because that agent is then going to build from the initial spec and we'll validate the result that we got from our

03:21 agent. And when we learn something new or there's a edge case, we refine this specification and continue on. And this loop is short. I'm talking hours or days for one feature instead of months for an entire project. So, let me give you an example of how this looks. Let's say the spec that we're working on right now is a password reset functionality for our users in the app.

03:39 And this spec could be three lines. So maybe one of them is to email a reset link. Another is that the link expires in 15 minutes. And that it only works one time. So we go through this loop during spec driven development and we see that the link never really expires, but we notice we never said what happens when someone requests two links. So we add one more line and we say hey only use the latest link and go through this process again starting from our spec to the AI agent building and that validation.

04:18 And what's nice is because this is a markdown or a similar type of file, it's version controlled right next to the code in our repository. So it doesn't end up going stale like it did with waterfall. And it does more than a requirements doc could ever do because from this specification, we're able to guide the implementation because the AI agent is building from it.

04:41 But we're also able to guide things like testing because we know what working means because of this spec. And it also guides validation because you can check the result against what you said was going to happen. So if you've ever written a failing test before writing the code, that test is a tiny spec. What spec driven development does is it just takes the idea up a level to a whole feature.

05:04 Specs were always a good idea in theory, but they were expensive to keep up to date. And AI is changing that in two big ways. The first is with context. Because let's say you're working on a new feature or app and maybe something that you're working on is unclear. Well, if you're working with a teammate, you can just ask them or they can ask you and maybe they know the codebase well enough to figure out the problem that they're working on.

05:29 But in working with an AI agent, it's a little bit different because the AI agent is going to guess or assume for specific information that it doesn't know. And what a good spec does here is it hands this agent the context it would otherwise have to assume. So information about what we're building, the constraints of the project, and how we'll know it really works.

05:55 But on the other side, ambiguity is something that's changed with AI as well because now every unclear requirement turns into extra prompts and those extra prompts turn into extra iterations where we have to check the result of that work. And at the end of the day, this is going to cost us a lot of money, but also time that we could be spending on other work.

06:16 So, this is really important to have a clear spec so that you have fewer cycles to get something that works. Plus, the agent can help you draft and even update this spec as you're working on the problem. Specs aren't just for features, either. They can include security, compliance, and governance requirements, too. For example, maybe every endpoint needs proper authentication, that we don't want to have any personal data from our users saved in the logs, or that we don't want to have any hard-coded secrets lying around

06:48 in our application. Back in Waterfall, things like security showed up during testing or QA, which can be a little bit too late. But don't spec everything because a quick bug fix doesn't need a spec. But a large feature that touches multiple services or a modernization project will really benefit from spec coding. So as Waterfall tried to lock in requirements before development began, what specdriven development does is keeps them connected the whole way through.

07:18 And as AI takes on more of the building, the quality of your spec is going to matter more and more for the quality of what you get back. Thanks so much for watching. Please like the video if you learned something today. and subscribe for more on technology and AI. We'll see you