Transcription
GitHub just released SpecKit. Instead of tossing out half-baked ideas into an AI coding system, it asks you for a little bit more details, product specs, technical design, even user workflows. Basically, it's a recipe book for coding. But can I use it to take my somewhat unfinished product ideas, give them a slightly more polished look and feel? That is what I'm going to attempt to find out today.
GitHub just released SpecKit, a new tool for document-driven, spec-driven development. So the idea is pretty simple. Instead of vibe coding, just starting with an idea and throwing it at your AI editor and just hoping it reads your mind, SpecKit goes completely the other direction. You start with a very specific idea in mind and lay out the exact product you have in mind, including user workflow, and then you give it a technical stack plan. SpecKit then takes that documentation that's been created based on the prompts you've fed in and creates a task list, a very, very detailed task list for your AI coding system to go step by step and complete the tasks in order. Finally, once that task list has been completed, then you can tell your AI system to go implement the tasks. Theoretically, everything at this point has been laid out. There's nothing missed. There have been test cases built and all scenarios should be covered.
So, using SpecKit is really pretty simple. You can find SpecKit, not surprisingly, over in its GitHub repository. It's got a pretty good readme section going through the highlights and how to use it. When you install it, you can cut and paste this command, obviously giving it the name of the project that you're looking for. So, we're just going to ask for a hello world. So, it's going to set up the specified project and then it's going to ask you which AI assistant you want to use. It's got GitHub Copilot, Claude Code, Gemini CLI, or Cursor. Now, usually I would use Claude Code, but I am currently out of tokens for my five-hour period. I'll come back to that. So, I'm going to use Gemini for now.
So, it's laid the groundwork for the SpecKit tools. It has created a directory called hello world. It's created a `specify` directory and it's put some templates in here and some stubbed-out files. And then it tells you the next step to take: change directory into that hello world directory and open up Gemini and use the slash commands in this order: `/specify` `/tasks` and then you should be able to implement. We're going to go into hello world. We're going to run Gemini and then just to verify that everything's installed correctly, you would look to make sure that `specify` is there.
All right, so let me pause here. I watched a bunch of videos of people using this product and it was pretty impressive. However, as soon as they got to this point, they pulled out what was basically an entire PRD, a product requirements document. Obviously, that's what you're supposed to put in here. You're supposed to specify exactly what you want the project to do. No technology yet, but lay out the project, including the user workflow. So, that's great, but I don't usually have that. And that's sort of been one of my problems. We all know the more specific information you give an AI coding tool, the better your product is going to be. But I don't always know upfront what I want. So I was really curious if I could use this process to sort of force myself into coming up with better specifications.
Let me show you the basics of how this would work. So here you would tell it the project that you're looking for, what you want it to do, and what the user interaction would look like. So we're just starting simple. I want a simple web app that will display hello world and have a button, and when you push the button, it plays a musical note. All right. It can be as simple or as complicated as you want it to be. So this is obviously the first step in the SpecKit process.
So here SpecKit is going to go off, create a Git project for you, and create a branch. You are now in the initial branch of your brand new project at the heart of SpecKit. This is a very version-controlled system. All right. So SpecKit has created the branch and created a new file with very specific user scenarios, and we can now find that over here under `specs` in the `001` branch. It's created a `spec.md` file based on the user input I gave it: "I want a simple web app that will display hello world, have a button, and play a musical note." It creates an entire execution flow. What needs clarification? Any errors? Quick guidelines? Creates the primary user story: "As a user, I can see a hello world and hit click a button." Acceptance scenarios, edge cases, requirements. Needs clarification: "How long should the note play for?" It creates this very, very detailed product specification. Okay, that's pretty cool.
All right, so the next phase, we are now at the planning phase. And this is really where it asks for the tech stack that you want. And this is usually where I sort of fall over. So the way I've been using this is trying to take my now better specification and plugging that into like ChatGPT and asking, "What tech stack do you recommend I use?" Their example here is to use vanilla HTML, CSS, and JavaScript. Uh, I am just going to cut and paste their example because for our test purposes, this is kind of perfect. All right, so this is `plan`. I wish they had called this `tech` or something like that. They talk about images and a database. I definitely don't need anything like that. In fact, Vite is probably overkill for my purposes, but I just kind of want to show you how this works.
All right, so it is now going to go off and make a plan using the technology that you have given it. And then once the `plan` command has run and created a plan, you will use this `/tasks` command to create this huge task list that your AI tool can go and code. I've actually done a couple of these. The documentation it creates is so enormous that it actually takes quite a while for some of these steps. GitHub actually has a detailed walkthrough that I used and tried to build a system similar to the ones they had spelled out. They basically wanted to develop something similar to a Kanban board with a bunch of users and a workflow. So I modified that to be a Kanban board for just myself and to track maybe skills that I wanted to learn. So I more or less followed their walkthrough. They were asking to use .NET and some code, and I worked with Claude a little bit to say, "That doesn't seem like that's a strength of yours. Can we build this in a different way?" And Claude said, "Let's use some different technologies." Other than that, I just really wanted to follow their walkthrough. And it is very helpful.
However, I wanted to use Claude Code to create this project, but it creates so much documentation, which of course, in turn, is fed into Claude Code, that I actually ran into my five-hour token limit. I'm on the $20 a month Claude Code plan, and I have never run into that before. And I not only ran into that once, I actually ran into it three times, and it's not done yet. My uh main takeaway is that this is enormous. So I was actually not even able to get that project finished.
So then I switched over to another project. I thought, "I need to start much, much simpler," and I now have to work with Gemini because I've run out of Claude Code tokens. So I started a tic-tac-toe app. So the process is the same. You install it, initialize it, give it a project name, tell it the CLI that you're working with, in this case, Gemini, and I fired up Gemini. And it created a branch, this `01` branch. Now, I started having some glitches in Gemini, and it was uh basically could not finish the command as I had written it. So, I tried again. `/specify` "I want a tic-tac-toe board." And because it had this error, it created a second branch because every time you run the `/specify` command, it's creating a new branch off of main. So, everything I'm working with is in this `02` branch.
Here's where we can see what exactly SpecKit is building for us. It starts out with my product description, which was: "Let's build a fairly standard tic-tac-toe game. But instead of X's and O's, let's use hearts and donut emojis. It's a two-player game. Each player takes a turn. Use the standard tic-tac-toe game rules." And from that, it creates an entire execution. It creates this user story. And this is really the strength of SpecKit. It builds all of this out. "Given a new board game, when player one places a heart emoji, then the heart emoji appears on the selected square. Given player one has placed a heart emoji, when player two places a donut emoji, then the donut emoji appears on the selected square." It is giving all of this documentation, writing it out very, very clearly. "3x3 board." I didn't have to do any of this. Now, obviously, it knows what a standard tic-tac-toe game is, but you can see this is so clearly laid out that it's going to be very hard for the code to have any mistakes built in.
So, then during the planning phase, I specified, "I just want this vanilla HTML, CSS, JS, straightforward." Uh, it's created a data model for me. It's created all of these documentations. And then finally, when it got to the task phase, it created this entire task list with information that the AI tool will run. All of these tests. They have to fail before it can be implemented. And then it goes on to run a bunch of other tests. Basically, everything you could imagine.
All right. So, you can see that is a lot of documentation for a simple tic-tac-toe game. And in the end, I mean, it actually looks pretty great. It works perfectly, exactly as you'd expect. No issues. However, this took probably three hours start to finish because of all the planning steps and the documentation and the basically just the heaviness of the SpecKit tool. Obviously, that's a good thing and a bad thing. If this is a pretty complicated system, that documentation can really save me. But honestly, for what I generally am trying to do, it just felt so heavy. And the project that I started with, I now two days later still have not been able to complete because it is such a heavyweight process.
The other thing that's really important to keep in mind is again, this is the strength and the weakness. Every time you type that `/specify` command, it's creating a Git repo if there isn't one, and it's pulling a and it's creating a new branch off of that, and that's the branch you're working in. If all of a sudden you realize you want to change something, you cannot just go and modify that specification. You literally have to merge your working branch back into the main branch and then start all over. Start the new `/specify` command and basically say something like, "Use the existing documentation as context and then update it with these changes," because that's the only way to pull the previous documents from the SpecKit tool into your new branch because you're starting over every time. I mean, that's a great way to work, and honestly, we should all be checking into Git probably a lot more often than we are. I know I should be uh, and I don't think of it until I hit either a major checkpoint or have made a change and thought, "Oh, dang. I really wish I had checked in before I did this." That was kind of a mistake on my part. So, I do like that it, in some ways, that it kind of forces you to constantly be checking in and merging your changes, but that does make the entire process of starting over just a little bit heavier because then you have to rerun the `/specify` command and the `plan` command and the `tasks` command, even if it's just a minor change. So, to me, that process is just a little bit cumbersome.
The other tool I tried to build using this process was a simple sketchpad. And this is what I got after three hours. I had to build the initial sketchpad. It only had one color. Took me a while to figure out how to update the documentation to get to an entire color palette. Now, does it work? Yeah, pretty much. But does this feel like a four-hour project to you? I mean, it really doesn't to me. And I think I even asked it to make sure that I could save my drawing. And you can see there's no save button. Now, in fairness, I was using Gemini, and I'm on a completely free plan over there. So, it very quickly bumped me down to Gemini 2.5 flash model. So, it was a pretty weak model to begin with. I was curious if all this fully spelled-out documentation could help a weaker coding model become a better coding model. Based on my very limited test of one, my answer is going to be no. It really didn't help.
So, what is my takeaway from all this? It was very interesting to see the entire process at work and to see the output that was made. I mean, the documentation is insane. This is the kind of thing I would expect to see on an enterprise level. That's probably not what I need for most of my projects, but honestly, I could take a little bit of that away. I think what I want to take away is the idea of the process. I would like to remember to work with AI a little bit more in the beginning and get a better product specification out of myself. I know these are my ideas that I'm implementing. Most of the time, they're just something to play with or something to maybe help me with a regular task. But honestly, it wouldn't be a bad idea if I just spent maybe an hour going back and forth with AI, tossing around ideas, and really using that collaborative effort to help me create a better idea of what I might want.
I do think, however, the entire process is enormously cumbersome. It just takes too long. For the projects I'm working on, it's overkill. I was hoping that this tool might be lightweight enough that I could just kind of skim from it and use it for my hobby projects, but unfortunately, I think it's just going to be a little too heavy for my needs. However, this is a pretty amazing product. It creates anything you could ever need, as far as I can tell. Go out to GitHub and take a look at it if you have a larger project in mind that really needs this level of detail. From that point of view, it's pretty cool. All right, I hope that helped. I hope you found it interesting. Thanks for watching. I'll see you next time.
Wait a second. You remember our hello world project? I finally got it working. That was two hours' worth of work. Worth it.