We Need More Than Prompts

For those of you who haven't met me, my name's Alex. I'm currently technical education lead at Bitter Brains, working on unlearn.dev. I've taught software engineering, web development for around about 15 years now, started on YouTube, started a company, which was acquired last year, and decided to take a little bit of time off, but then that didn't quite work out and I love teaching, so I joined the fantastic team at Bitter Brains and we've been working on unlearn. So, just sort of past the clickbait title of my talk today, I want to talk to you about spec-driven development, which I believe is probably at least right now the best way to build software with AI. And the whole premise of this is to think upfront about what we're doing before we actually do it, so whether you use spec-driven development as it stands today, or whether it looks a little bit different in the future, that doesn't really matter, and I don't advocate for any particular framework.

So, the journey, I've been thinking a lot about my journey, because the last year has been absolutely mad with AI, and I've been thinking about my journey in terms of my own productivity, and I tend to find that ideas in my head or what I want to build is faster than I can actually get them down onto paper, so to speak, but obviously that's code. So, we're talking like years back now, things like code snippets, just basic snippets where we say log turns into console log, or generating classes, methods, whatever it is, and this was the primitive way to speed us up. Obviously, we go into IDE autocomplete stuff, so static analysis, heavy indexing of our codebase inside of our IDE, and obviously that speeds us up as well.

And then I'm sure most of you remember the early versions of GitHub Copilot where we could effectively just generate snippets of code within the context of our codebase, and this felt like absolute magic at the time. I think there's been a big shift from here to where we are now which is agentic coding. We've taken a step back from our IDEs, or most of us have taken a step back from our IDEs, and we're now telling this thing what to do, rather than generate a code within the context of our codebase. So, it's pretty clear that our roles have changed, and, if they haven't for you now, they probably will in the near future.

We plan whether that's in our head or on paper more than we build. And that lends to this kind of cycle which there's nothing wrong with, but I think there's a better way. So, prompting an agent, pretty obvious, checking that, re-prompting either to add to what we've built or to fix what went wrong, in the worst case, and that looks a little bit like this. So we start off with, you know, a really simple prompt, can you do this for me? The prompts maybe get a little bit longer, a little bit more specific, and then we get to the point where things start to break, and then the caps come out, and we start to shout at our agent, and, yes, I've done this multiple times, so this is a pattern I'm sure most of you are familiar with.

I think the problem is that we don't actually know what we want up front, and it's really hard to articulate that, of course, when we are trying to tell this thing what to do. We are essentially directing another developer on what to do. Which, if you think about it, we are micro-managing another developer what to do, this intelligent thing, which, you know, if you think about doing that to a human being, it just wouldn't work out. So, I think something belongs between the intent that we have in our head, and the code that the agent writes.

So, really quick brief on STD if you're not familiar with it, effectively what we do in this cycle is we plan a change, and that goes as a written spec, so this could be in any form. To do that, it generates modifiable artefacts, and these are markdown files that we can format, commit to our repository which I will talk about later, and we can generally review them. Once we're happy with the spec, there's a little mini-cycle in this step, the agent goes ahead and builds that spec, or from that spec.

Now, the great thing about this, which again I will talk a little bit more about is that the spec acts as this persistent layer, persistent context in your codebase, which can be really helpful, if you do it well, to not only you and your team but also your AI agent. So, let's take a look at the anatomy of a spec. Bear in mind, I'm not advocating for any particular framework, so, whichever framework you do use, or if you build your own pipeline, this is generally what you would include in a spec, compressed down. The first is the less obvious is that why are we making a change?

The most obvious is what changes, so, the actual changes that you want to make to your codebase, whether it's adding a feature, refactoring something, fixing a bug, this will be more like the line-by-line changes or whatever happens. And then of course we have the acceptance criteria which is like when I build against this spec, how do I know it's actually done? This could be like the test that you write, this could be very specific criteria that we check manually, really just anything, we want to know if this has been successful, and we note that down before we build.

Then again, less obviously are non-goals and boundaries. It's pretty obvious, most of you have probably found this, that agents like to wonder, they like to build things that you don't want, they like to try and be helpful, but actually, a lot of the time, that creates, you know, not just bad code, but it just complicates you, your codebase. So what does this look like in practice? At the moment, I'm using OpenSpec which is a great open-source framework for spectrum development. There are others. The first thing I would do jumping into this could be a feature, a bug fix, a performance refactor, it doesn't really matter what this is, but you prompt, of course, because you need some way to get that idea from your head into your agent, and using whichever framework that you've chosen, this will then go ahead and generate the documents for you.

So you either explore an idea, I'm sure a lot of you have used plan mode and stuff like Claude code before, and this is kind of similar where we explore and go through stuff before we commit to generating these specs out. In this example, I've got an emailed one-time passcode to the auth of the code. So from that, you get a bunch of artifacts, so you'll get a proposal which includes that why that I spoke about a moment ago, why we're doing this, what's changing, this is a document that you should be able to give to anyone. So not just developers, you should be able to give it to anyone on your team, any stakeholder, and they should be able to understand exactly what this change is doing.

So not just developers, you should be able to give it to anyone on your team, any stakeholder, and they should be able to understand exactly what this change is doing. And then we have a design document usually, which is a more technical approach, so this will be something that developers particularly would review, and then we have my absolute favourite, which is the list of tasks. So even back before I started using spec-driven development personally, I created a skill in Claude code to take the output of Claude code's plan mode and convert that over into a checklist because I found I wanted to see what the agent was doing, and I wanted to stop it maybe mid-way. I might have finished for the day, and I wanted to wrap up and pick up the next day, and we lack that ability in something like plan mode.

Now, before we even start to think about generating code, we prompt to refine the spec, and this might seem weird and counter-intuitive that we're prompting within this other cycle, like, why are we doing this, are we wasting time? But the point is that at the moment, we've not committed any code. And, of course, code is super cheap, but also it's expensive in terms of technical debt, we all know that, so at the moment, we're just talking about words, we're generating a bunch of documents with a bunch of words in that we can just review. Now, after that, of course, once we're super happy with everything, the agent builds stuff, which is the fun part, we can watch the output, we get a beautiful checklist where we can mark stuff off, our agent will mark stuff off for us, and we can watch it build, we can stop it, we can adjust guard rails, which is another reason I love this approach, and of course, at the end of that, we get the result we wanted, but where do we go from there?

So I ran a workshop on spec-driven development a couple of weeks ago online, and someone asked a really good question, so I was using OpenSpec, I had all the spec documents, I set the agent to go ahead and build it, and they asked, can we dry run the spec to see what our agent will do before we spend all these tokens, you know, running through this task to build this thing out? And I couldn't actually answer the question at the time, so I was pretty honest, and I said, well, I don't know, there might be a feature for that, I'll go ahead and check it out, and then I very quickly realised that the spec is the dry run, you spend that little bit of up-front time planning something with the task list which is actually very technical, you know exactly what your spec, or what your agent is going to do. Of course, not all the time, but it does reduce hallucinations. So, as developers, or me, I'm talking for myself here, I like to just get in and start to code, which is where that originally when I started using AI, I would just go in and prompt.

So, as developers, or me, I'm talking for myself here, I like to just get in and start to code, which is where that originally when I started using AI, I would just go in and prompt. So I've had to really shift my thinking here in that we now have more up-front planning time, or we should have more up-front planning time, and it's not always 80-20, but I like to use 80-20 because it's a common model to think about things where we have 80 per cent of planning, and 20 per cent of execution and other things which you could include things like adjusting guardrails, changing the model that you're using, it might just not quite work out with what you're building and you might need to switch half way through, all of that kind of stuff to everything else. But this mental model or this way of working is of course an investment in changing the way that you work. So, I found a case study, there are quite a few of these, this is XP software, they used GitHub spec kit, and this is exactly what I was speaking about happened, they used spec kit to build a feature against a ticket which raised some assumptions about the codebase, and the difference between the codebase and the ticket, and also just generally the task, they reported that the tasks took half the time. It's spec-driven development is a hard thing to nail down in terms of case studies because people use it in different ways, they build their own pipelines, but this is just one of the interesting ones I found, and you can of course read about it here.

Now, another really great thing about a spec is it's collaborative. So, rather than you as a developer sitting there prompting your agent over and over again until you hopefully get the result that you need, you can share your spec with other developers, with other stakeholders. So, just as an example, going back to the OTP example here, when someone signs in, we email them a six-digit code, codes expire after ten minutes, that's what's in the proposal, but then someone jumps in and says, well, actually, can we modify this? Can we drop the expiry to two minutes? A regulatory framework requires it, I don't know if that's true, and then, of course, because it's technically code, it could be pushed up to GitHub, you just go ahead and collaborate on it. Of course, like I said before, the proposal that you generate is generally suitable for sort of everyone to look at, so it's a very collaborative process, particularly on higher-stakes features where you do want multiple people involved. The other thing about spec-driven development is that I mentioned at the start, your code base remembers why you did things. Remember, we have that why within our spec. So your code base sees the changes you have made along the way, which you don't get both with traditional development when you are writing the code yourself, but also you don't get by prompting your agent, because you lose all that, well, why did I change from this to this? So, particularly within OpenSpec, we have the ability to archive a change. So once we're finished with this proposal, the agents implemented it, we can archive the change at any point. That might be when it's shipped, it might be when we're done with the feature, it doesn't really matter, but we archive this into our code base, this lives alongside of our code base, and you get this like backlog of stuff that you've done. It's these two in particular, because you might have the ability to, you know, you might have added the ability to use one-time passcodes, you might have then updated this to use ten minutes, or have a ten-minute expiry, then you might shorten that expiry to two minutes. Everyone on your team and your agent know why you have done this, and these over time build up, so your agent gets that really great context on not only what you're doing, but also why you're changing these things as well.

Now, I'm a very sceptical developer. I don't like to jump on new tools without giving it a little bit of time and thinking about whether I actually need things. I tend to just be like, yes, I want Claude Code and my editor, everything else stays away. I'm going to be honest with you about where this breaks down as well. I think that's super important. First of all, trivial work, so, I would not create a spec, for example, to change the colour of a button. There's not really any wire behind that. I sort of came up with this own rule for my own projects and my own work, that, if it's a behavioural change, so if it affects the way that a user does something, if this happens, then this happens because, then I would go ahead and use it. For trivial work, there's not much point using it. I'm talking about very small changes here. STD is quite a commitment. You have to use it properly.

The other thing is I absolutely love using AI to prototype. I think it's one of the main benefits that we can get out of this, and I absolutely still use Claude Code on its own just prompting away or plan mode to explore a codebase, explore a solution, or prototype a solution. I still pull up Claude Code, enter plan mode and say build me this thing within a couple of lines. I would then use that build to then go in and build the spec, because I've taken maybe ten or 15 minutes and however many tokens to explore a problem before I plan it out properly. So I think exploration and prototyping, it would be a waste of time to use spec-driven development.

The other thing is you need to commit to spec-driven development because your spec and codebase live together and they need to be in sync. If you neglect to use spec-driven development for a while, and your spec documents that we've just spoken about get archived, they come out of sync with your codebase, then you basically just have another problem on your hands, and there's no point doing it. So spec rot is a real thing you need to make sure that you commit to it. What I love about spec-driven development is it doesn't really change the way that your codebase looks, you just have to change the way that you think. So you can just experiment with this and, you know, if you can't keep up with it, and if it's not for you, then it's not a problem. But as a big team, or, you know, if you're using it seriously, you need to be careful with spec rot. Definitely not for everyone and not for all teams, but I think for the majority of people, it can really help.

So, I'm going to leave you with this, and this is something I've been thinking about a lot. It's that however good AI gets at one-shotting what we're building, or building things, you know, how we want them, it can't expect, or you can't expect it, or we can't expect it to guess what we actually want in the first place. So, edge cases, we all know them as developers, there are multiple things that could go wrong with something that we build, so I think we need something in between that. And I think at least at the moment, spec-driven development, in whatever form it looks, is a really, really good start. Thank you.

So, the first question with the most upvotes is what does a workflow in a team look like with spec-driven development? How do we work on features together? Yeah, I mean, I guess I sort of covered it, but it's something that you would need to experiment with, with your team, and just like I said, spec-driven development is really easy to experiment with, so you can very easily install open spec, it's like one or two commands to get it set up on a codebase. You can experiment with maybe two or three developers using it. But I think it really comes down to anything like any collaborative process, you need to have something in place to do it. But technically, because you're pushing up the spec to your codebase, it's kind of like asking, like, how do we collaborate on code? You just make changes to the spec, and you end up with something that everyone agrees on, and then you let your agent build it.

Okay, so there's a concept within spec-driven development called deltas, so I didn't cover it specifically in my talk because I didn't have time, but effectively what you do is you get these archive changes, but then with most frameworks, you get a compressed delta of how the behavior in your system has worked, and that folds into the overall spec. That's specific to OpenSpec, and I know that a couple of other frameworks use that approach as well. So you don't just end up with a bunch of, you know, like thousands and thousands of changes. They are great for context, but you also end up with a more refined version, and again, that depends on the framework. But yeah, you don't end up with lots of bloat that you need to manage.

Does one need to keep the specs up to date? If there are a lot of features, specs accumulate, and some features affect or override others, so how do you handle that?

Okay, so there's a concept within spec-driven development called deltas, so I didn't cover it specifically in my talk because I didn't have time, but effectively what you do is you get these archive changes, but then with most frameworks, you get a compressed delta of how the behavior in your system has worked, and that folds into the overall spec. That's specific to OpenSpec, and I know that a couple of other frameworks use that approach as well. So you don't just end up with a bunch of, you know, like thousands and thousands of changes. They are great for context, but you also end up with a more refined version, and again, that depends on the framework.

Next question is how much of the spec should live next to the code versus in an issue tracker like Jira or Linear? That's a really good question. I mean, most of the solutions do live in the code base. I think one of the things that I have done in the past is, yes, you can have high-level specs or even low-level specs outside of your code base and outside of whichever framework that you're using. What you can then do, though, is you could just chuck that spec into your agent's spec framework, so you can build specs on the side, absolutely. Just know that the source of truth is the actual one that lives next to your spec. So, they can live anywhere, but effectively, the spec that is the source of truth must live next to your code base.

What you can then do, though, is you could just chuck that spec into your agent's spec framework, so you can build specs on the side, absolutely. Just know that the source of truth is the actual one that lives next to your spec. So, they can live anywhere, but effectively, the spec that is the source of truth must live next to your code base. Awesome.

I think the next one is quite a timely one because as we've seen the development of these AI tools and agents, more non-technical people are getting involved in the code base and writing code. So, this question is how do you collaborate with non-engineering disciplines on specs? I think, for my team, non-technical people use GitHub, but I guess, yes, that's a tricky one. I mean, you basically you get markdown documents or whatever form that they're in, and I think if you could build a pipeline that pushed them somewhere that could be collaborated on, you could potentially make it work. My lack of experience with working with non-technical people on specs, I can't fully answer the question, but, yes, it's definitely something to think about, yes.

On a similar kind of issue, somebody has asked, do you think it would be helpful or useful to identify the parts of the specs with the highest change inertia to help avoid making bad decisions that are difficult to fix later down the line? Yes, I don't know how you would do that, but that's a great idea, yes. As it scales, you would want to be selective, and yes, I don't know how to answer it! I feel like that's super context-dependent, and the right answer will depend on a lot of different variables. Yes, for sure.

There's a way to do it. There's a way to do everything. The next question is what is your favourite opening prompt? Oh, okay. So, I give a lot of background info, so I would say, like, I am trying to solve this particular problem, and we need to discuss how we can solve this. I like to have a really collaborative approach with an agent. Actually, one of my favourite, it doesn't fully answer the question, but one of my favourite modifiers to any prompt is any questions. In almost every prompt I do, if it's slightly ambiguous, or could be slightly ambiguous, I just tack on the end any questions, and usually, there will be questions. Otherwise, there usually isn't questions, and your agent will make an assumption. So, I guess, favourite opening prompt is just the normal stuff, but then that modifier is great. Yes, for sure.

Okay, we've got a cost question which is how would this scale in terms of token usage on longer running projects? So, what I just spoke about with the other question is that your delta describes the behaviour of your system, and what is happening. I had this question recently, actually, in a workshop that I ran, and my suggestion was to come up with a way to ignore certain older specs within your agent, so you could of course clean up your older archived specs, but I would do like a clawed ignore or a cursor ignore file to maybe ignore things that I didn't need. But from what I've seen, even for longer-running projects, you don't see that much token usage because your model won't immediately look inside of your archive, it will look in your delta specs where you've got that much more compressed version. It depends on the framework, but my advice is always just to monitor this as you go, and course-correct, but it's never something that you couldn't correct in the future.

Today, the why behind a feature work usually exists in Slack, Linear, or Jira, and other sources of context. Why would collaborative specs be better than any of these other collaborative sources? Different to Jira and Slack and stuff like that? I guess it's mainly because they live next to your codebase, and I think it's very easy to lose context elsewhere. If we were still, you know, let's imagine a world where we're not using AI, and we are all writing code by hand, we've slowed right down, we can obviously monitor the output because we are writing the code, and if specs did live elsewhere, we can keep that context because we've slowed right down, but I think as soon as you introduce this thing that rapidly generates code, you do need a way to have these quick why did we do this, what did we do before, what went wrong before, which is something I didn't say in my talk, but we need to know what happened before so it doesn't happen again. I think that's the most important thing, and we lose that when we, like, you know, generate thousands of lines of code a minute. So, yeah. Sure, for sure. Another one on that kind of importance of context and organising it, how do you organise your specs in a way that it doesn't just become bloated? So, we've touched on this already, but should we be selective about what specs we are committing to main? I don't think so, no. I think any context helps. Again, it's framework-dependent, so it doesn't, you know, some frameworks will not put everything together, some will sort of get rid of your, some parts of your specs, but, yeah, I don't think we should, at least initially, don't be selective about what you're pushing up because you want to see how it works for you and your team until it scales and then it's a problem and then you can figure it out. Awesome.

I think any context helps. Again, it's framework-dependent, so it doesn't, you know, some frameworks will not put everything together, some will sort of get rid of your, some parts of your specs, but, yeah, I don't think we should, at least initially, don't be selective about what you're pushing up because you want to see how it works for you and your team until it scales and then it's a problem and then you can figure it out. Awesome.

And somebody has asked, are there any useful agent skills to use in combination with spec-driven development? So, with OpenSpec in particular, it is just a set of skills. There's no MCP servers or anything like that. The reason I chose that as the framework that I use is because it is just very, very simple. So, actually, what you get with OpenSpec initially is quite a very simple set of commands, which I love because you install it for the first time and you just get I want to either explore a feature, I want to create this proposal, in which case you can just create a proposal from a single prompt, you want to apply a change, or you want to archive a change. Simple. But you can go into OpenSpec and you can enable more advanced workflows, so I think most of the skills that we build as developers are trying to tweak our workflow so we can go through the entire process of idea to building as quickly as possible, reviewing, debugging, whatever we need to do. But I think OpenSpec encapsulates most of that. And then, to be honest, I would just take the normal skills that I use and I would just add them on to the process within the workflow. So, once a feature is built, of course, you still want to review the code. I'm not saying this is like just build it and let it do its thing. It will make mistakes, of course. So, yeah, like a code review skill, for example, or something like that, super important in your workflow as well, yeah. Sure.

And I feel like you might have touched on this a little bit just now, but somebody has asked, but what are the benefits of OpenSpec as compared to Grill with Docs or other such skills? I think they're all very different. I did try and research this and I just found that it came down to personal preference. And I think most developer tools are exactly the same. You just prefer something. I prefer OpenSpec because it's incredibly simple and I can't really do anything wrong with it. I just have a set of three or four commands. But some people and some teams, of course, will need tools that are either more collaborative or built into the IDE, something like Kiro. There's GitHub Spec Kit. There's a few others. Or build your own pipeline. Like I said, I'm not advocating for any specific tools, but yeah, building a pipeline yourself is good. Thank you so much. I've got a ton more questions. So, I would say that to follow Alex into the Q&A booth because that's all we have time for today. So, a massive thank you to Alex for this talk. Brilliant. Thanks so much.