Spec-Driven AI Development / lesson 2 of 4

Spec Kit Integration for Existing Projects

Play
Transcript

[00:00] Spec kit is a set of commands and skills from GitHub that allows us to take specifications for a feature and convert those using any agent into a clean code and commit history, as well as a documented set of decisions from one specification to the next.

[00:20] I’ve talked in the past about beginning a greenfield project with spec kit, which works great. And in this video, we’re going to take a look at a very messy older project, and we’re going to look at introducing spec kit into an existing messy project. So this is the project we’re going to be looking at. It’s called Zaphod. What it does is somewhat irrelevant, but I will show you I have tried all sorts of different things. I’ve got a bunch of different agent skills in here. I’ve had, um, uh, a loose set of features for an agent to explore. I have some context about the application; I’ve done improved planning. So I’ve got a whole bunch of these guys in here, and, uh, honestly, I really like those. But mostly I just depend on this agent’s, uh, Markdown file, which uses like an old Klein memory bank structure. So basically it just tells the agent, like you have no memory, you, uh, here’s all your tests and you need to write everything to this memory bank. And that’s worked pretty well for me. It’s, um, a very loose structure, and I need to always make sure that it’s actually updating that information. Uh, so this is the project we’re going to introduce spec kit into.

[01:37] If you don’t already have spec kit installed on your machine, you can install it with UV tool install specify dash CLI. Once that’s done, you’ll have access to all the commands we’re about to run. So we’re here in the project and I’m going to initialize this guy by saying specify a knit double tack here, which means in this repository, and then my integration is going to be my agent of open code. That’s going to fire up the specify CLI, and it’s going to recognize that this isn’t an empty repository. I’m going to tell it to continue by choosing yes, and I’m going to pick my shell script. Now that we’re in here, you might be thinking that, oh, I need to run some sort of command that says go learn everything there is about my application before we do anything. But that’s not what we’re going to do. We’re going to start it just like we would any other spec kit project.

[02:29] And we’re going to begin with our constitution, which is a set of principles we want the agent to abide by. So I’m going to run spec kit constitution, and I’m just going to type in a list of rules. I want the agent to pay attention to preserving public API compatibility, following all the existing service boundaries, and ensuring any database migration includes a rollback plan, and then run the repository’s established test suites. That’s going to kick off the process of creating the constitution by which our agents will abide.

[03:50] So now we need to start thinking about the specification we want to create. Specification is really just a new feature. Now I’m looking at my application here right now that keeps track of various analytics with my YouTube channel, and one of those things that keeps track of is the number of views. However, YouTube recently introduced a difference between views versus engaged views, so you can see I’ve got views all over the place here and I’ve also got it in my code. What I want to do is have spec kit produce the specification and the task and then the implementation for tracking views versus engaged views. This is not a small task. There’s a Postgres database, a whole bunch of endpoints, a fallback to a SQLite database—there’s a whole bunch going on here. It’s honestly not something I want to do by hand myself. So I’ve got a specification I wrote up here that says to extend those analytics to capture the engaged views and how to deal with the metric, the database, and the UI. This is going to be our first spec. I’m going to come into my coding agent, say spec kit specify, paste in my specification, and it’s going to go to work creating that structured specification for us.

[05:17] So it says it’s done. We are going to jump over into the project and take a quick look at that specification. Here in the specs folder, I’ve got a checklist, which is a bunch of requirements for a specification, not the specification itself, and then I’ve got a spec that explains all the different user stories and functional requirements for this task. We’re going to jump back over to our agent and run spec kit clarify. This will challenge our specification and see if it can find any gaps or edge cases we might have missed. When it comes up with those, it’ll return some options for us to deal with those gaps or edge cases, and usually it’ll also provide a recommendation. This one has an option A, which is really just saying, how do I display a placeholder when there’s no data? I’m going to stick with A, and it’s going to go ahead and update the specification using that new information.

[06:14] So once that’s done, we’re going to jump into spec kit plan, which is going to create all of the requirements and the overall plan for agents to follow before it begins any tasks. If we jump over to our editor, we can see we’ve got this spec and plan in place, but our plan right now is just a template. When the agent finishes figuring out what the plan is, it will use this template to populate that plan. If we put this off to the side and watch our agent complete, we should see it update with the actual plan data instead of the template information. And there we go. There is our plan, all marked up and ready to go covering our actual specification, the actual feature we’re going to be building. And now our agent is working on a research document, which should show up in just a second.

[07:14] Cool. Here’s our research document, which is just a series of questions and answers, evidence and notes about why it made various decisions as it pertains to different requirements for this specification. Now we’ve got a data model covering our video analytics, which is obviously at the core of what we’re trying to change about our application. It’s covering the various database columns, features, and schemas—everything an engineer would research before making these types of changes. We also have a contract we can look at, which essentially explains what already exists and how we know where to get this information, identifying the API that I already have in place for this data. Finally, we have a quick start, which is just a head start for the agent before it begins working out any tasks, which we’re about to create now.

[08:12] To create our tasks, we run spec kit tasks. The task command creates all the individual and very manageable tasks that we expect our agent to do in order to complete this new feature or specification. If we look at our task.md, which has just been created, we can see an entire list of not only the user stories as they relate to each task, but also a phase, a purpose, a checkpoint, completion criteria, and how to test it—everything we need for each task is outlined here. With that in place, we can now run spec kit implement, which is the actual implementation of each of these tasks. This is the heavy‑lifting portion of the spec kit CLI. As that’s running, we can monitor changes to our application, seeing the creation of tasks and updates to the various sections of code involved in this specification.

[09:00] As it’s running, we monitor changes to our application, seeing the creation of tasks and updates to the various sections of code involved in this specification. We can see it actually committed the code and also updated my progress.md, which means it’s picking up on the existing agent rules I already have in place. I’m super happy with that; that’s perfectly acceptable to me, though I could remove it later. It says it’s done, so we take a look at our application. I can see I now have a column that says engaged views, and in the panel I can see views versus engaged views.


Share this post on:

Previous
Spec Kit Introduction
Next
Spec Kit Assess Extension