Spec Driven Workflow with Claude Code #1 - Making a /spec Command

All right then, gang. So I just recently released a new Cloud Code masterclass on NetNinja.dev, which is a deep dive into Cloud Code and how I use it within my own projects. And I wanted to upload a small preview of that course here on YouTube. So I decided to release a small chapter of it all about setting up and using a custom spec-driven workflow, because I think this small chapter sits well on its own. And I also think it's a good way of working with any agentic coding tools, not just Cloud Code. And I wanted to share it. So if you do like this small free chat... and you want to learn more about the process and dive much deeper into clawed code and agentic workflows, then definitely grab the full masterclass from the netninja.dev website. It's $15, but you can still get it half price using the promo code clawedninja at the checkout. So I'll leave this link down below the video, and now I'll just cut straight into the content. all right then my friends welcome to a brand new chapter and in this one i'm going to share with you one of the workflows i like to use when i'm working with cloud code in a project and that is a spec driven development workflow whereby we create a high level non-technical specification for any new feature then we create a detailed technical development plan based on that spec and then finally we use that plan to implement the feature and by using a workflow like this i find it keeps the model more focused on the task and makes guesswork or incorrect assumptions about any features it's working on to a minimum now the inspiration for this kind of spec first workflow came from a tool by github called spec kit which goes heavy on the philosophy of having a high level spec at the heart of ai driven development personally as a developer who likes to be very hands-on and stay firmly within the development loop myself i think the spec kit makes me feel a little bit too detached from the whole process of adding new features so i've stripped that process back and i've come up with my own lightweight a much simpler approach which makes it easier for me to add my own input and manage the process and therefore it hands a lot of that agency back to me the developer So throughout this chapter then, we'll be putting everything together to implement this spec-driven workflow. To begin with, we'll make a new custom slash command to help us automate the process of generating high-level and non-technical specs for new features. After that, we'll be using Claude Codes built-in planning mode to make detailed technical plans for implementing those specs. And then finally, we'll be using Claude Codes extending thinking mode along with the Opus model to implement those plans. And they're the three core steps involved in this workflow that we're going to be focusing on. on in this chapter spec out a new feature plan the feature then implement the plan now you could also add a review step at the end of this cycle to review the code once the feature has been implemented but that's something we're going to look at in a later chapter and we'll just focus on the first three steps for now i'll also be integrating git into the workflow as well so that every time we start a new specification or feature cloud code switches us to a new branch and that way if things do go south we can just delete the branch and our main code base remains untouched Again, I would strongly advise using Git and GitHub if you ever use AI to touch your code, because without it, things can get really messy really quickly, believe me. Now, if you're new to version control and you do want to learn about it, then I've got a big Git and GitHub masterclass course that you can check out, and I will leave the link to that below the video. Anyway, let's crack on with this workflow by first of all, creating a new custom slash command to generate specs. All right, so now we know about the general process of this spec-driven workflow, let's start off by making a new spec command. And this spec command is going to do a few things for us. First, it's going to generate a feature name and a branch name based on the input or arguments that we provide to the command. Second, it's going to switch to a new branch with the name it comes up with, and then it's going to make a high-level feature specification based on our import and write that spec to a file inside a specs folder. and this specification like i mentioned before is going to be a high level one meaning it shouldn't go into too much detail about how the feature should be implemented from a technical viewpoint but rather focus on the bigger picture and how the feature should behave from a user's perspective i guess including any edge cases and wide implications so then Let's make this new spec command by opening the commands folder in the .claw directory and then making a new file called spec.md which means to run the command later we're going to type out forward slash spec. okay so now we can start to flesh out this file and the first thing i want to do like in all the other commands we've made is make some front matter for the command description and allowed tools at the top and also to add an argument hint as well so then let's start with the three dashes to go either side of this front matter section and then inside those dashes i'm just going to paste in three different keys and values the description which says create a feature spec file and branch from a short idea and argument hint which is the short feature description and the allowed tools which are read write glob and bash to switch to a new branch so that's the front matter sorted and now we just need to write out the actual command itself and rather than me type all of this out from scratch i'm just going to paste this in and walk through it all with you step by step And by the way, like I mentioned before, you can get this entire command yourself from the GitHub repo for the course files. All you need to do is select the Claude Snippets branch from the dropdown up here, then go into the commands folder where you're going to see this spec command plus any other command that we make as well. So if you click on that command, you're going to see all the content for that file, which you can just copy and paste into your own file. So then let me just paste all of this in and then we'll walk through it slowly. First of all then, we have this summary at the top which tells the model it's going to be making a new feature spec for the application using the user input below, which we say down here is from the arguments. So when we run the spec command later, we'll be adding a sentence or two about the new feature we want to spec so the model can use that input. We also tell the model to respect anything inside the clawed.md file. Next down here, we go into a little bit more detail, outlining the steps the model needs to take using that user input, starting with creating a feature title in Kebab case, then making a safe branch name for the feature, and finally writing a detail markdown spec in the specs directory, which we don't have yet, but we will make shortly. Below that outline, we go into each step in more detail, starting with the step one, which is to check the current branch for uncommitted or unstaged changes. If we have any of those, we tell the model to abort the whole process and instruct the user to either stash or commit the changes first. After that, we tell the model to pass the input arguments to extract or come up with the following values. A feature title. a feature slug which follows the below criteria like lowercase letters kebab case only letters and numbers replace spaces with dashes and so on then finally a safe git branch name with the following format claude forward slash feature forward slash then whatever the slug value is and we give an example of that down below So then, once the model has extracted those values, the next step down here is for Cloud Code to switch us to the new feature branch using the branch name the model just came up with. After that, we ask the model to create the actual spec markdown file and save it in the specs folder using the feature slug it just came up with. We also mentioned here that we'll be using plan mode later to plan the spec and we're going to talk about plan mode later in this chapter. But as well as that we tell the model to use the same structure for the spec file as the spec template file right here using the at symbol to manually add that template file as context. Now we don't have that template file created yet but again we will make it shortly. We also tell the model not to add any technical implementation details, such as code examples, because that's what the planning step is for later. Finally, once that spec's been created, we ask the model to respond with a short summary of what it's done, including the branch name, the spec file location, and the feature title. so that is the spec band done now and we're going to be using this in the next lesson to spec out a new feature but for now all we need to do is create that underscore specs folder which is going to create all the new spec files in and we also need to create the template file because it's going to use that file to create those specs right so let's cross this off and then we'll create a new folder in the root directory called underscore specs and the only reason i'm using an underscore right here is so that this folder sits at the top of the tree there's no deeper meaning than that but inside that now we're going to create a new file called template.md and i'm just going to paste in this template it's very very simple but i'll go through it so we have the feature name at the top then the branch name it chooses and then down here we say figma component if used now don't worry about this too much for now later in the course we'll be using figma and we're going to integrate that into the spec command so we'll come back to that later for now we're not using figma anyway we have these different sections that we want cloud code to fill in when it's creating this spec file so we have a summary of the spec or feature any functional requirements uh the figment design reference only you've referenced again don't worry about that too much for now we'll come back to it later and then down here any possible edge cases the acceptance criteria open questions so if it has any questions it wants to ask us put them there and then we can go in and answer those questions are there any testing guidelines at the bottom and i've also said here create a test file in the test folder for any new feature and create meaningful tests for the following cases without going too heavy so obviously i don't know the test cases that's for cloud code to decide when we're speccing out the new feature all right so now we have the new command this spec command and we have this template so that when it's creating specs it uses this template in the next lesson let's create a new spec for a brand new feature

in this series, you'll learn how to implement a spec-driven workflow using Claude Code.

🍿👇 Get the FULL Claude Code Masterclass:
https://netninja.dev/p/claude-code-masterclass

Use promo CLAUDENINJA for 50% off.

🔥👇 Get access to ALL Masterclasss & premium courses with Net Ninja Pro:
https://netninja.dev/p/net-ninja-pro/#prosignup