Spec Driven Development: AI Assisted Coding With Doc at the Core | Bruno Borges, AI By the Bay 25
Uh my name is Bruno. I work at Microsoft. Um a part of the uh Java developer community team there. Um and uh I was part of the Java engineering group at Microsoft until recently where I was the uh product manager for Microsoft build of open JDK. So Microsoft has its own JDK now since uh 2020 201920. Um we also have a bunch of Java libraries for AI development and we are working on the new Microsoft agent framework Java implementation should be coming soon um sometime next next year 2026. We did implement a library called semantic kernel for Java. uh that library is now out of maintenance because we are moving on to this new uh agent framework um library but one thing that we learned working with the .NET team, the Python team uh the TypeScript team at Microsoft uh and with GitHub teams um is the importance of having specifications for LLMs
GitHub announced recently a project called GitHub spec kit and which helps you um develop specd driven development with any agentic uh tool not just github copilot of course for this demonstration for this presentation I'll focus more on github copilot and the spec kit tool but um uh please do know and you're going to see in the demo that you can use whatever um aentic assistant that you may want But before we dive into the tooling part, let's discuss about specdriven development. Specdriven development is not necessarily new. I mean, we all have been writing documentation for many years, decades at least for software. Um, ADRs is an a great example. Our architectural decision records uh is is a document that many engineering teams use to uh write down the decision why that decision was made uh for specification reasons. Um many teams will use waterfall models for project management and usually the first few steps on a waterfall project is documentation, specification, use cases etc etc. In many cases those documents are written in a very technological agnostic way. There's no definition of what technology will be used uh just use case UML diagrams etc
So are we talking about going back to those days to some level? Yes. We want to be able to have documentation but in a way that not just developers should consume but also agentic AI should be able to consume those artifacts and specific development is more about that. It's about writing documentation, write specifications that AI can implement against or upon. So specifications um or specdriven development when you think about it what it is um is the source of truth. I mean code is the source of through of the implementation but specifications are the source of truth of the thinking behind or even before the implementation. We think about an idea we have a use case we have a user story and then you write a specification of that that becomes the source of proof of our thinking once you have that you can ask AI to implement whatever it wants. If you give let's say you have an specification that has no techn technology details in it and you give that specification to one Java team, one .NET team, one Python team, one TypeScript team, JavaScript node, you can have four different implementations. Fingers crossed they all implement the same features, right? The same use cases, the same user stories
So that becomes the source of truth of those requirements, of those ideas. But once you go into specdriven development, you start having these ideas of version control for your thinking. You don't have just word documents lost in a folder somewhere. You have actual markdown files that you can easily commit, diff, manage, and so on. Um, technical decisions are more explicit, reviewable, and evolvable. Word documents are great. PowerPoints are great. UML diagrams are great
But if you can have another format that allows you to um use tools that will learn from those things from those artifacts, it makes it even better. Specifications capture the why behind decisions just like ADRs and the specs involve alongside your code. This is the one interesting part of specdriven development. Sometimes we have the repo is here, the documentation is here or the specifications are here. With specdriven development, those should be combined in a way. There are techniques that you can think about like maybe use subm modules uh you can use subm modules with git or maybe you can have a repo for your specification and a repo for your implementation. But the idea of putting the documentation in formats that are more source control verifiable, it it it allows you to have a much better control of the evolution of those specifications. So it is similar to a conjunction of ADRs uh that together from form this comprehensive context
And when we talk about context, we talk about LLMs. But why why assumptions hurt when we talk about specifications? So imagine a notification system configuration. You have this app that has a notification system feature that needs to be added. The product manager assumes that okay we're going to have per channel toggles. The backend engineer assumes we're going to have single onoff switch flag in the database. That's the change that they need to implement and some API. The front-end engineer needs to have these OS level integration like the UI has to change a little bit and integrate with the Windows or Mac OS notification systems and the designer needs to think about what needs to change in the user service what needs to change in the front end what are the things that the user needs to interact uh with that changes with those changes. So a specification can mean different things for different people in the team and without details in those specifications depending on who you ask to implement they will give you different requirements they will give you different tasks
So having the full context of the notification system configuration idea is critical when you go to the AI and ask for that because AI will actually act with those four roles to some degree. So spec driven development helps with that. The AI agents do rely on the context, not just the code. So they have to have full understanding otherwise you're going to be just wearing one or two hats when in fact you need AI to wear all hats. Um these specs they do unlock these scenarios like uh I want to generate like I mentioned before different implementations from the same classification for whatever reason. Um I want to have different UI implementations. I can have maybe Figma mocks and I want to also compare architectural directions. So I have this specification and I want to actually what if I go monolithic? What if I go distributed microservices? What if I go uh CLI? What if I go web or mobile app? Give me some options and some ideas out of the same specification for that feature for that product
So when you do SSD, SDDD or respect driven development, you it it allows you to have this multivariant AI generated explorations, it's just like having this agnostic technology agnostic specification and you give it to four different product uh sorry engineering teams at the same time and you're going to see what comes out best. If you have worked at a large corporation, it's not unheard of that two or more teams got the same task to go and implement something, right? With the genti now you can do that a little bit faster, okay, with a lower cost to some degree. So how how do we do um um specdriven development? I mean you can go and write documents along your code. You can go and write LLM instructions. Some Aentic AI tools have that now custom instructions for LLMs like uh this this agents.mme um and uh prompt mess some files for different tools and with that you ensure that your ID or AI coding tool reads them right make sure that it has those that context. One way to do that is with Visual Studio Code and GitHub Copilot. You can write custom instructions. We have this capability called prompt files
Uh we have custom modes and custom agents. These are all features that Visual Studio Code integrates with the files in your project. There's a special folder called.githubinstructions and those files can be used by the developer or by the agents in GitHub copilot to read those files and have better context of what you want to do. So let's take a look at GitHub spec kit. So GitHub spec kit is this project. Actually before I look into this slide, let's just go take a look at the repo here. So, GitHub spec kit. So, this is GitHub spec kit
This project is kind of new. This was released this year, but the adoption and the interest from the community has been great, right? It's it's a tool that gives you a process and a bunch of subtools to allow you to do specdriven development. So when you think about specit and and generating artifacts for your specifications to organize the information to organize the context, the main reason you do that is so that the LLM can work the best way possible. So um LLMs can provide variable outputs. The specs they try to guarantee more deterministic out uh out output or the guard they sorry they will set the guard rails so the outputs vary less the specifications they become the truth as I mentioned before source of truth and they become executable imagine like the specification is the source code the LLM is your language runtime so the LLM will execute that so the code just becomes a representation of this classification And it can be represented in many ways. Just like you can represent an idea in different languages, Portuguese, English, Italian, Spanish, you can have an idea represented in different implementations. And the other important thing is specifications are becoming contextual not just for the current work, but for the future, just like ADRs help us determine why we made those decisions and how that can impact future decisions. The part of the splitting the process allows the LLM to work step by step
If you go to an LLM any and you say do this and don't provide much context, God knows what comes up. But if you provide a lot more details and then you say get this into your context into your memory and then you say now let's start with task one and then two and then three and you break down the LLM does a much better job. So with specifications it's important to break down into those components. Specitate works with these four concepts. The constitution very strong non-negotiables. Think about processes that your company has to follow, your team has to follow. The specification itself, the idea of your product or feature uh or component. Then the plan which comes with implementation details
I want this to be a NodeJS application or I want this to be uh a shell script for automation of my infrastructure management. And then the tasks for implementing that plan. Let's do this, this, and then this. And that's when the Agentic AI assistant tool whatever you're using will start actually implementing task by task. So what is what is specit? I mentioned before it's this open source project on GitHub. At its core, it's a bunch of files, prompts, templates, and some shell scripts and PowerShell scripts if you're on Windows to help you organize your ideas into specifications and files so that the LLMs can do the heavy lift for you. Your job becomes more like as an architect, project manager, more like a product manager as well or designer where you work with this broader vision of what you have in mind. But it is important that you do review those artifacts as they get created because you don't want use you could use AI here's an idea and then AI generates the plan you don't review the plan and then ask go implement and then you have something but then that's like firing someone just do the work and you don't review that's bad it's important you review every step so you don't get surprised after minutes or sometimes even hours of work by your agentic AI So it's it's important that you review and don't waste your time or the agent AI or those tokens that do get charged eventually
Um and specit does use um MCPs um implementation wise there's a bunch of MCP behind the scenes as well from your platform either it's cloud code or visual studio code with copilot and as I mentioned before the artifacts live in the code live with the code of your implementation as well. So, what is what does the flow look like? Sorry for the size of the text. Um, I can't I don't know how to zoom in on this thing. I'm a Java developer at Microsoft using Mac. So, I apologize for that. Uh, [laughter] I'm not too good with the zoom. So, the first step is initialize. I'm going to initialize this project with using spec kit if and that is that works more from like green field projects
You're still working out, the project is still working out on how to better adapt it with existing project. It's doable, but I'm not sure about the process yet. So, let's imagine a green field brand new project. You initialize that and then you start with the constitution. That's the pink purple box, the first box. The constitution sets those non-negotiables and then you're going to specify or create a specification. As you create a specification, you can clarify a few things. So, you can use the clarify command
That's part of your review process of that specification. Okay, you feel confident about specification. Now let's go into the planning phase. Let's plan the implementation of this. That's where you put your technical requirements. I want this to be a Java GUI application or a Node.js web application or a Go CLI application. And then finally we run tasks to break down each task individually so that the agent can work one by one step by step. You can run this command called analyze just to make sure this is like a read only
It doesn't change your files. It's not supposed to change your files. Okay. The instructions in those prompts and scripts are very clear. Do not change files but make sure it doesn't change files. And then the analyze will look at all the files, the constitution. Sorry, not the constitution, the specification, the plan, and each task. Finally, you run the command implement
When you hit implement, this is when you hit enter and go get coffee. Okay, this is when the agent will actually do most of the work. But so far, here is just markdown, writing markdown files. So, let's take a look at how this works. Now demoing spec kit is a little bit tricky because even though it's fast we have we have 10 15 minutes tops 10 minutes tops. So let's focus on initializing a project and creating a specification and then I show you a project that I built before I came on stage and walk you through the chat with AI to show you what happened. Okay. All right
Let's take a look at that. So, here I'm going to create u uh who here has ever had to call travel agency? Let's say everybody, right? Okay. You know when they ask you what is your reservation code and then you have to say something LKM4B. The best way to talk to your travel agents is to say Lima, Kilo, Quebec, Mike for Bravo. All travel agents know this, right? So if you learn this NATO alphabet Oh, somebody's like, "No, not all of them." Okay, all the ones that I spoke to, they know >> me, >> they still don't get it. [laughter] >> Okay, thank you. [snorts] Um, so this still helps even if they don't know, it still helps when you just use words for the letters, right? So what you're going to do is create an application that does convert uh a code like this into this, right? So let's go and specify um in it NATO booker. So here the UI will ask which agent copilot or AI assistant do you want to use and the reason it asks is because some agents may have certain type of file structure where to look for the instructions and the prompts
So that's why the the project has this. I'm going to stick to copilot here for presentation purposes. Here it asks for uh uh shell or powershell. Sure, it could assume infer from where I'm running, but maybe you're on shell, but your development team will actually use PowerShell. So, I don't know. It just asks. Okay, so it created everything. So, now what I'm going to do is open this project on Visual Studio Code
Awesome. So you see it already suggests a few actions that it found from the the instructions. See here you can see the prompts. These are all the prompts and the agents that were customized for GitHub copilot from specit. So let's create I'm going to cheat here. I'm just going to copy the instruction. So here's my constitution. Okay
So I'm going to choose the constitution agent and I'm going to paste create principles for a small tool called NATO booker. It has to be the preies are has to be clean, readable, fast start up, accurate, nato, phonetic, mapping, etc., etc., right? Okay, let's run this thing. Now, what this will do is create files locally and will generate um the constitution with those non-negotiables. It's basically, you know, when you go to chat, you have an idea, but you're tired and you want don't want to to expand the idea yourself. So you go to chat GPT and ask, hey, I have this awesome idea. Can you help me write the email with it? You know, like that's all cool. We do that. So this is basically doing that
I have some principles, some priorities, some non-negotiables. Now expand that into a constitution file. What it will also do is update some template files because these template files were copied from the initialization task without details from the project. But once I do have the constitution, those templates will be adjusted. Okay. So it changed those templates and now it's creating the constitution based on those principles and you can see those files. So here on the GitHub folder you have all the files that are from the tool generated on the specify file is where you have the things specific to the project. There's some tools but here the memory this sets the constitution
Okay. So it created the constitution file. Here it is. It's making some adjustment. See how it went from a template into a specific because that's what that's what it does. Okay. Okay, so we do have a constitution now. Let's just hit kip
Let's close this thing. Awesome. Sounds good. We We have a suggested commit message. Uh I'll just do this thing. I'm going to add here. I'm going to actually click on this button to generate you with AI the commit message and commit. Cool
Now I'm going to go to the next step which is the specification itself. So create a functional. So let's take a look at this specification. Create a functional specification for a CLI application called NATO Booker. You see how the specification gets into more details about the project, but still not necessarily technical stack, right? And here's some user stories. I could actually maybe I didn't I didn't need to say CLI at this phase. We could try that. do not mention implementation language or libraries in this spec because the AI can hallucinate and just make decisions for you
So that's why that prompt I I wrote down that prompt to ask it do not try to guess. So let's go to specify. So now it's going to write the the spec MD. This is where it will create a dot uh sorry a spack folder or spaxs folder in my project. Always allow. It's going to I think it it will create a branch. I don't think it creates a branch. It just works on the current branch
No existing features found. Oh, this is the process of like am I working already on a project that has specifications? Cool. There you go. So, it created a specs folder and it has a draft for the spec file which is based on the template. You see this is the template. Now the the the AI agent will start writing a specification based on my initial prompt but respecting the constitution of the project. So this is a step that will take a little while and we only have five minutes left. So let go let me go to the project that has this implementation already
Okay. So this this was the prompt the conversation that I had. This took me about I would say 30 minutes 40 tops to go through this considering that I did review some of the files not all of them but some. And uh here was the initial right I asked for the constitution. Uh then I asked for the specification. Here it is. Then I asked for the plan. Here's the plan
The plan is we're going to implement this using Java 21 with Maven. It's going to be a single JAR file application CLI. We're going to use this library called Pico CLI which is an open source Java library for writing CLI applications. The local history will be history.json uh with some with three commands. Convert history and clear history. Here's the nato mapping part. The persistent strategy should read and write the JSON history file. How to handle missing or corrupted files should be also part of the implementation plan and so on so forth
Cool. Now technical implementation complete. So, we have a plan 001 NATO converter. That was the name that I used for this one. Here's the specification for that. And then I said now create a list of tasks. Sorry, the text was too small. There you go
Create a task list for implementing the application. Cool. So uh here are the suggested tasks from my prompt which follows the same asks that I did in my specification plan. And finally I just add oh it jumped. Did you see a blue box there at the very bottom? This is a buggy thing on on the chat. Tasks complete. Oh, this is the implementation. It just jumps over
Don't Don't Oh, there you go. Follow instructions in the implement prompt. That's it. I just said /specit.implement and it started implementing. And how it does, it starts from the tasks. each task and then from each task it goes and looks into specification and it goes looks into the constitution it goes look into the plan etc etc and then it started implementing the whole project so now I can come here and say I know it's the most silly example but it works and I can say uh LKP4 HJ and here it is Lima Quebec Papa for hotel Juliet cool so I have I have this implementation I can I can actually run without anything. I have these commands. So, let's run the command history
And cool. I already submitted a few of them as you can see over there. And uh it's yeah, it's a full Java project with Maven. It has unit tests for uh all the all the classes and Java 21 Maven super nice well implemented well clean history command convert command history history entry sounds really well done. So if I get these specifications files the the constitution and the spec file and I start from scratch but I keep those files and then I ask okay now let's plan an implementation using Node.js with with a similar prompt. I just changed the technology stack. It will likely have very very similar output. The convert command, the history command, the clear history command, similar output
Right? That is the idea. Have more deterministic in uh output from a very welldetailed specification document set of documents. So I hope you enjoy that. Uh we can go for a few questions. Oh, by the way, yeah, uh, specit some some future ideas, uh, artifact management, you know, how to move those files into another project so you can better manage that. Uh, better integration, improve, continue to improve the integration with VS Code, uh, top of funnel for SSD experimentation, better support for brownfield projects, which I mentioned for for existing projects. The team is still working on how to better match this kind of experience with existing source code. But do check it out
A lot of people are checking out and I think it's a great project to experiment with spec development. Thanks. [applause] We'll open for questions. >> Just one sec. We >> Yeah, I have the microphone. I'll go ahead. Yeah. >> Um, >> so if I'm developing an end toend system, I might vibe code an app and do some backend work and get some other front-end stuff working
And where I find my problem is I want to bring it together. And I didn't architect it for the purpose of bringing those work products together into a final solution. And so I'm I'm curious about your guidance on the development process for that you know for testing in in branches or in um separate projects but with the end goal of then merging these kinds of projects together. >> I think what you were asking does touch on the uh some of the feature ideas for the project on how to better organize that source of truth of those pack files. So then you have this imagine this repo of all these very generic specification documents not technology specific not the plan or the tasks. Um but one thing that you you can do is nothing stops you from having a plan that triggers the implementation of your project in multiple stacks. So I can have the web front end with node, the back end with java integration tasks with playright or selenium and you have all these things separated even though they are still in the same repo but different folders right so your specification because one thing that it does in the specification file the folder sorry you see this is a subfolder so this is one specification I can have multiple specifications sorry here's one specification the 001 specification I can have multiple specifications for different things right and then from for each specification I can have uh a different plan and then I can have multiple tasks so it does allow you today to break down into different chunks of work for different uh things in your project one thing that GitHub copilot and visual studio announced just this week uh is GitHub copilot background agents that you can trigger from visual studio code. So those tasks that we see, they could be broken down into GitHub issues in your GitHub repo and then you can go and assign them to copilot and then it can be paralyzed implemented in parallel
Um actually we can see that here in the tasks file. So in this file we can see some tasks. Let's see phase one setup shared infrastructure. So uh it needs to be a maven project with pom file the plugins for assemble the source folder the task folder and then foundational uh create the native alphabet mapping on this folder like those data models that need to be created. Here's the phase three user story basic booking reference conversion. There is a step. There you go. At this point, user story one should be fully functional and testable independently
[clears throat] So here's one step. So in phase three, user stories can then proceed in parallel if staffed and they can be staffed by parallel agentic AI agents, right? And they can be done in in the background with GitHub remote agents. So um I can go here and for example I can say this is not a demo that I've tested. I will not hit enter because I don't know but hypothetically speaking for now I could go and say uh implement task two and then hit this icon here which is the cloud icon. I'm not sure if you can see there are two icons now. One is to send which runs the local agent and the other send icon has a cloud behind which sends to the GitHub copilot in the background. As long as your project is fully committed to GitHub repo, you don't have unst unstaged changes and uh you have an issue and then you can associate that issue to GitHub copilot. So then you have this background work happening in the cloud for you
Does that help? >> It does especially your first advice. I'm too pedantic. I think I create a different repository for every platform and technology, >> right? >> And I think your idea of just start the project in in its own repo and develop all the technologies in that repository might be a solution >> because eventually your project will outgrown the specification. So it's important that you also keep the specification up to date. But if it doesn't, I mean that's part of your process. That's part of your way of managing things. But the idea here for especially for green field applications is start a specification and maintain the specification. So keeping everything together is the best way for now
But as we saw in the road map, we wanted to better manage those artifacts in a way that you can have multiple repos perhaps referencing those centralized documents. Okay, we had a question here from the sir in the >> Yeah, and that would be the last one. >> Uh, hi, great talk. Glad I made it. Specdriven development is super cool. I'm part of a domain driven development crew here in San Francisco. Have you thought of co-mingling uh methodologies like DDD and SDDD? >> I'm not a super expert on domain driven development. Uh but this kind of touches on on the topic, right? >> Because part of the specification does cover the domain models used by the application >> and and that's the AI coming up with that
We do have the templates that provide you know if you identify a domain model document it go into details etc. But I think it's it's I it's this is proof that domain driven development uh is important because the LLM's learned from them. All the books and articles and material that is available in the internet about domain driven development did help LLM behave the way that allows this package driven development. Right. So yeah, thanks for your comment. >> One more round of applause for Bruno. >> Thank you. [applause] >> Thank you.