Spec driven AI development – A Real World Perspective

Thanks, everybody. Before I start, I feel really old at this event. I've been doing this kind of stuff for about forty years. Just so you know, if you're early in your career, this is what a lifetime of software development does to the human body. So anyway, we're going to talk about specs. How many people in the room are involved in their day to day writing software or telling bots to write software for them?

And how many of you work on more than one project at the same time? Okay. A few of you, which is kind of cool. For those of you who only work on one project, your days are numbered. Right? Businesses are going to look at the efficiency the AI brings, and they're going to say, you need to work on more than one project.

There's also some other things businesses do which annoy people like me. And one is to think that software is never finished. Software is never finished because you have to keep updating it and maintaining it. So every time your bots write a line of AI slop into your code, you're creating a bunch of technical debt. And the spec is the way to get back to it.

So here's the thing to think about. We've all been backing up the wrong files. How many in the room write code without a version control system? GitHub or that stuff from Atlassian? Anybody write it just using the file system and Hopium? No. Excellent. So you're backing up the wrong files, right? What we see is the asset.

And your management see it. Everybody talks about it. It's the code. We review it. We version control it. We protect it. We rewrite our prompts every time and instantly forget what they were. But the intent of what you're writing as code gets thrown away. Right? The asset is actually the spec in a number of ways. It's not just the context for your AI agents.

And just out of interest, another show of hands, how many people are using a AgenTiKi orchestrator? So something like Symphony or those also one, two, three. How many people aren't using one of those? Put your hands up. Okay. Good. Good. That's a binary question. That's to check that the people who didn't put their hands up are still alive and following along.

So it's a Groundhog Day programme. For those of you who aren't using an AI orchestrator, your days are also numbered because you're going be asked to do that because it makes you more efficient. But I don't know if you've had this experience where you've spent the whole afternoon arguing with your AI. Right? You're sitting there. You've built this product.

It's really cool. You need to do something like add some users because you've given the version to the customer. And they've gone, that's really cool. How do I log in again? Hey, just add a user. Well, do I do that? Insert into that's not going to work. So we need to use the management screen. So you ask your AIs to build your user management screen.

And they don't follow what you decided to be your design. And they don't follow how you want it to work. Actually, you're integrated with something like Okta or Entra ID, and they don't follow that because they're missing context. So that's a wrong thing to ask. How many of you write prompts like that? Just a little one liner, just to see what you get at.

Yeah. I could see what's going on. Right. No. Use our design system. AIs need to be grounded in context. Even when we're using agentic AI, they need instructions of how to work. Just putting a folder called design underscore system isn't going to get you there. Even worse is when your designers have mocked up this beautiful HTML and CSS thing, which kind of animates and does everything, and you put it in another folder.

And your AI picks it up, half the time it writes it in your source folder, and half the time it writes it to their mock up, which is kind of fun. So that's wrong. Next one. We no. Support Entry ID or Okta. Well, these ways of doing federated identity are complex and they have lots of options and configurations and your AIs don't know about them.

Right? No, not like that is where you rage quit. Right? Get to 04:00, you go, I've had enough, I'm stopping. So when you get to the world of the orchestrator, when you get to the world of the system which is actually managing your agents and you stop typing things into Claude code or codex or whatever your latest command line buzzword is or base 44 or whatever it is, when you're doing this, you're just arguing with the model.

You're just having this kind of telepathy thing which is going wrong with the AI. And it's frustrating. And it's annoying. And the way we fix that is the spec. So I'm going to spend the rest of the session talk to you about what it is. And then at the end, I'm going tell you how to build one really easily because that's really important too.

So the spec, here's something to think about now. You're going to disagree with me here and I'm going to disagree with me as well. The spec is the source of truth. The code is a build artifact. And boy, I had this great demo lined up for you. And I was chatting to one of the guys who's speaking later today, a guy called Hamish Songsmith.

And I said, Hamish, I'm feeling a bit old. He said, yeah, you are. He goes, your jokes always fall flat on a younger audience. I went, really? Oh, god. I said, what about my demo? He said, what demo are you going to do? I said, well, I've got Bill Gates' original basic written in assembler. And he goes, yeah, Okay.

That's your first problem. And then I'm going to write a spec on it. And then I'm going to build it in.net. That's your second problem. Right? And thirdly, I'm going to make it run-in the browser in Blazor. And he goes, no. That's not going work. So I threw that away. I've changed this deck quite significantly based on feedback.

So if it's rubbish, you can blame him. So what is spec based development? It's a discipline loop. Software is one of those very few disciplines where you don't know what you're going to build before you start building it. It's an innovative discipline. It's complicated. It's not like almost every other aspect of business.

And how many people still use waterfall development in the room? Good. None of you. Right? Everybody use oh, you do. You work for government, do you, sir? Or big bank. You're the Cobalt developer, aren't you? But anyway, saw somebody written doom in Cobalt, just for interest. So spec based development is starting off with the contract, right?

Kind of saying, we think we're going to build this thing. And it's not just a contract between you and the agents. It's a contract between you and the customer, whoever that customer is. So you'll use AI to build this really complex and detailed spec. You'll give it to the customer. They'll use AI to summarize it into eight bullet points.

And that will just go on in a loop. You need to kind of walk them through it. So the spec. It's your intent and guarantees. So it's written to be testable. I've got some skills. At the end of this, I'm going to give you a QR code. There's a whole website where you can download some of my skills on how I build specs, and I'll update it as I go along. But I think the specs, your most important piece of context. I actually build two, just so you know.

I build a requirement specification, which is the human one, and I build a technical specification, which is the technical one. And the two of those work well together. Once we got a spec, we build a plan. Right? How many right? We don't just go and say, here's a spec slash goal. Build me the product. It's fun, but it never quite delivers what you want.

It never quite works. So we then go, okay. Now we've got a spec. We're gonna build a sprint plan. And out of our sprint plan, we're gonna build every work item we need to build that product. You remember when I talked about agent orchestrators? They work off work items, Whether you're using GitHub or whether you're using Notion or even some people using Azure DevOps, they can read work items and work through them.

So this is how you want to break up your plan. Almost think of your agents like a human dev team, which is better than a human dev team because an underperforming agent, you can kill. Last time I tried to kill a developer, they got frowned on by HR. Only a little bit. Right? So we create a set of atomic ordered and independently checkable tasks. But all of you would know, if you've ever built software, that as you get through this process, what you're actually building changes as you go through.

So you want your agents to update the spec as they move. This is super important, and I learned it by getting it wrong. So this is why I'm saying it's important. And you need to tell your customer when the spec changes and what changes. So your spec becomes a managed artifact like any piece of code. And you use that with code and tests and documents to build everything together.

Is it am I making sense? Or am I smoking crack? Probably smoking crack. Right. Everything under the spec you can regenerate in whatever language you want, at whatever time you want. If you've got your spec right and I would say probably if you build a web app and your design system those two things together mean if you decide you're going to build it in Rust tomorrow or your management come down and say, we think COBOL has the most RAM, to quote a 1999 Dilbert cartoon.

Do you see? Nobody gets that either. It's gray hair. But if you do I won't do the joke. It's quite funny, but I won't do the joke. Anyway, so a spec is your key artifact that moves as you're developing, and you should be able to recreate your product from it. Specs are not hand created anymore. How many people when's the last time how many people in the last year have written a specification?

Put your hands up. Yeah. A few of you. It's fun, isn't it? I find some characteristics that make people who run software development for a living. One is they love writing documentation. Two is they love writing unit tests. Right? And number three is they love communicating with the customer. All of those things go to make an excellent result.

But this is not a fringe idea. This isn't just Nick saying you should do it. Every major vendor get up with their spec kit, AWS or Cairo. There's a whole bunch of systems to help you build and manage specifications. So there's eight vendors all converging on this. And the reason they're converging on spec first is it seems to be the way to give your agents the context.

So how do I build a spec? What I do is I sit down with the customer. There's always a customer who has an idea of what they want built. And it normally veers between something sensible and a little bit of magic. We used to call it the two birds paradox before AI appeared, where somebody comes to you and says, can you build a piece of software?

Yes, I'm a software engineer. That's what I do. I want to be able to take photos on my phone. Yeah, Okay. I can build new software that does that. And I want it to record where that is in the world. Yep. I can do that too. There's a GPS and stuff like that. And they say, and I want it to tell me how many birds are in the photo.

And ten years ago, we were saying, well, that's nine PhDs, twenty years of development, and probably a bunch of research and development grants. Now we plug it into chat GPT so you see how things have moved. So when you start doing this, when you start building the spec, we tend to see in teams about 10 times less regeneration cycles for phases of an application.

You know when you get down the world with your bots and you go rage quit and go, Okay, we're deleting all that code and we're starting again, right, because it's a Wednesday and I've run out tokens. And the chat GPT model, which was great on Monday, is crappy today and all of those exciting things, Right? So that means when you get it right, the human time spent in and around a feature and this is a full human cycle, right? The cycle of working out what we do, checking the issues go in, making sure the tests are right, playing with the code, giving it to the customer, we can reduce that into under eight hours per major feature in a big application.

It's an enormous difference. So there's one test to keep in your head. If you can regenerate it, if your bots, if your agentic orchestrator, if your symphony can regenerate it, then it becomes a build artifact, not something you're keeping. Now I kind of I swing both ways on this.

And the reason I do is because there are some things which you can't write in the spec. That little animation when you click the top button that someone in design created, which is just the right number of seconds to evoke the emotion of calm in the end user, That normally doesn't end up in the specs, so you need some things to be kept.

But if you can regenerate it from something, everything you regenerate is a build artifact. The build artifacts are source code, tests, API references and documentation, scaffolding, wiring, config, even the infrastructure you're deploying it to is a build artifact. Now, so the spec becomes the most important thing. Right? So the specification is important.

Your architectural decisions are important. Your acceptance criteria are important. And the judgment calls that make them happen are important. That's what you have to capture. So how it feels sometimes. It's like this. I'd run a for my whole career, I've read code written by people. And now I read code written by nobody.

And I don't really read the code much anymore, to be honest with you. I read the tests. I read the results of them. I refactor things. I do all of it without looking at code. All right? So half of our careers, when I was in this, used to be archaeology. Right. Oh, look. I've got a code base.

Yay. Oh, look. It's not documented at all. Right. In fact, there's no code comments apart from the ones where they got frustrated and write slash slash angry or other words. So figuring out what the engineer meant is critical. That's why the spec is important. And you need to keep updating it. So the way I build them is sitting with that meeting with the customer. We sit down for about an hour.

I start with the question, what business problem are we trying to solve today? What's the human problem this software is meant to fix? If they can't articulate that, maybe go and find someone else. And we use Zoom or Teams, and we take the transcription of that meeting. And I guide them through not only what problem are we trying to solve.

I'm an architect. So I go, Okay, how are we going to solve it? Do we want a web app? Are we going to do something on mobile? And we start delving in and answering all these questions. We put that back through the spec skill, and it builds a specification for us in Markdown. We then share that with the customer.

Business people love Markdown. Right? So markdown to words is your friend. And we give them a word document. They mark it up. We do that a few times. Once we lock on that, that's the spec. Right? We don't need to read the code. We need to get that bit right. I spend more time now on the spec than I actually do on running the code.

That's all done agentically. So finally, who you're building for. You're not actually building. This is not building for the customer. This is building for the future you. Because remember I said software is a destination, not a journey? Software is not a destination. It's a journey. Let me get it the right way around. You have to go back and maintain your code.

You have to go back and make changes. Sometimes years, or if it's COBOL, decades or centuries later. It gets really hard. Who wrote this? Oh, it's Bob Jones. Can we ask him? No, he's dead. You laugh. It happens more and more at my age. So the customer yeah, it's just the thing.

Right? The customer, right, is you when you have to go and make a change. That spec is the key thing which drives stuff as you're moving forward. Right? So today, think of how it goes. Claude added this feature. Three months later, why did Claude add that feature? Six months later, who approved this feature? Twelve months later, can we change it safely?

No idea. It's in production. I have 800,000 users use it every day. And that whole feature that drives the back end and makes it optimized was written by Claude and nobody read the code. The documentation is what captures that. It's what gives your AI context. It's what makes it work. Right. So this is a governance conversation.

And every time I say this in front of developers, they run away screaming. Governance is fine. Did you know, just as some side, cyber. The word cyber means the gift of governance. There you go. Nobody knew that. That's exciting, isn't it? Right. Governance, branch protection rules, pull requests, the spec. These are governance from a software point of view.

You can use these things to go back to your governance team and say, we're doing things in a grown up professional manner, unless you're not doing things in a grown up professional manner and then do them in a anyway, moving on. All right. I'm going to I've got thirty four seconds left. So I'm going to talk about where it doesn't work.

Shitty specs deliver shitty software. They always have. They always will. All right? Nondeterminism is a thing in the world of agentic software development. You ask the bots the same question twice. You get different results. All right? But finally, AI changed who writes the code. It doesn't change who owns the decisions. I've created a little microsite for you here.

That's got some downloads. I will be keeping that updated for the next month or so with new things I find. Feel free to log in there. There's my LinkedIn contact details. Thank you very much. Eighteen minutes.