SpecKit: Not Impressed

SpecKit

Several months ago, I was organizing a Hackathon in London to promote agentic software engineering. One of the attendees mentioned that Github was working on a new tool called SpecKit, which was supposed to be a specification-driven development tool that would allow developers to write specifications in natural language and have them automatically implemented by AI agents.

SpecKit is not just a set of tools, but a whole development approach that emphasizes the importance of specifications and the role of AI in software development. The idea is that developers would write detailed specifications for their software, and then AI agents would take care of the implementation, testing and maintenance. The specifications would be the source of truth for the project, and the AI agents would ensure that the implementation always aligns with the specifications. This approach is takeing the name of Specification-Driven Development (SDD), and it is being promoted as a way to improve the quality and maintainability of software.

My Expectations

I’ve been meaning to give SpecKit a go for while. I had high hopes for it and it sounded like going in the right direction. The ability of coding agents to quickly implement features created the opportunity to do everything in one go. The cost of fixing a specification that is wrong is close to zero, because the cost of implementation is converging to zero.

Natural language allows for imprecisions that can be resolved by the agent during implementation, and it also allows for a more flexible and creative approach to problem-solving. Many software engineers are saying that English (or natural language in general) will be the programming language of the future. I thought that SpecKit would leverage these advantages and provide a more efficient and effective way to develop software.

I have to admit that it has been a few decades since I did a proper waterfall project with specification documents and all that, but I don’t remember it being this bad. Perhaps the nature of software in the 90s was different, perhaps my expectations were different or I simply got used to the flexibility of Agile practices.

The Reality

Nowadays I typically start chatting to Claude or Copilot about the software I’m trying to build. We iterate over the requirements, explore different functionalities and approaches and then I ask the agent to write a Product Requirements Document (PRD) that captures our discussion.

SpecKit on the other hand asks you to provide a description of the software in the first prompt:

/speckit.specify help me build an application that is the read-through mirror of the english wikipedia translated to Montenegrin. We will be using an LLM for the translation. The translation should happen in a lazy fashion to keep the cost low. The application should mimic the Wikipedia look and feel, but at this point the articles should be read-only. It should implement search functionality with autocomplete. It should only search in the text of the translated titles. therefore we might need to translate the titles upfront.

This is a very different approach, and it is not surprising that it doesn’t work well. The problem with this approach is that it assumes that you can provide a complete and accurate specification of the software in one go. Of course I could still have my chat with Copilot and then ask it to write a prompt for SpecKit, but I’m then what is the value added by SpecKit?

SpecKit asked me a few clarification questions that were very helpful, but left me with a feeling that we still didn’t discuss all the requirements, but that we covered details that were unimportant at this point. It generated a specification for three user stories, a dozen functional requirements and more stuff. This was the point where I started feeling excluded from the process.

To be fair, I went for the full experience and included the optional steps in the SpecKit process. That might have made the process even worse, but from the generated artifacts I think it wasn’t the sole reason for the poor results.

Next I asked it to generate a plan. It asked a few more clarification questions and generated an impressively detailed plan. I was still not sure if it was a good plan. In the documentation I could read the various options considered and it did a pretty good job, but I didn’t feel involved. I normally like to chat with the agent about the alternatives one by one, but perhaps it is just a matter of getting used to the new approach. I could still edit the plan.

The Nightmare

This was followed by the analysis, the task breakdown and the checklist. The analysis was pretty good and it identified some potential issues and risks. The task breakdown started to feel overengineered and I just didn’t want to go through 47 tasks to verify 3 user stories. The checklist was just a nightmare. It identified around 30 different issues that I needed to clarify. The issues were very low level implementation details. If felt really strange to have to go through all of this detail before even starting to implement anything. I felt like I was trying to plan a trip to the moon in the 60s, rather than building a software application in 2026.

The worst part was that there were inconsistencies in the plan and when I tried to correct them, the agent modified just some of the documents and left the others unchanged. It was difficult to keep track of which document parts were depending on which ones and even for a trivial application, the amount of documentation was overwhelming. I felt like I was drowning in paperwork, and I hadn’t even started coding yet.

As a cherry on top, no tests were generated and unsurprisingly the application did not work at all. I guess testing should be easy to add to the process, but at this point I am not sure whether it aligns with the SpecKit approach and whether it would just be another document that I would have to keep consistent with the others.

Conclusion

I understand that the idea behind SpecKit is that the specification IS the source of truth, but I learned that in practice, code coupled with a modern IDE, tools and testing frameworks is a much more malleable and effective source of truth. It is not a matter of being closer to the actual behaviour of the software or the risk of introducing errors during the implementation process, but the actual model that is used for specifying the application (i.e. English language) is difficult to manage even at a small scale.

I’m not saying it projects shouldn’t have requirement, plans and other documents, but trying to bring that documentation to the level of detail that allows no ambiguity is just not practical. The documentation becomes difficult to verify, difficult to change and difficult to keep consistent.

Documentation should be intentionally vague and incomplete, and it should be used as a communication tool rather than a source of truth. It should be a guideline rather than a strict contract. It should allow for flexibility and creativity. SpecKit, by trying to do the opposite, is getting the worst of both worlds: the complexity of code and the lack of verifiability of documentation.