TutorialVibesAI

Addendum, December 29, 2025

I’ve since parted ways with GitHub Spec-Kit. And I no longer recommend it.

Forced Branches

Let me start with a softer objection: for one thing, it bothers me that every spec inevitably and unavoidably creates its own branch the moment it’s created. This behavior is documented, but it’s not apparent from the README on the landing page or explained in the introductory videos. I like to decide for myself whether and when to branch. The consequence is that you can’t create multiple specs simultaneously. You can try, but they’ll all start with “001-” because each branch considers itself the first. You forfeit the ability to have multiple specs processed agentically in parallel — and that parallel processing is precisely the key innovation of modern AI-assisted software development.

Debugging Only Possible by Going Around Spec-Kit

My second objection is that a spec must run to completion before you can begin the next one. The problem here is the assumption that a spec can only be started and run through without errors. Because Spec-Kit progresses through the phases constitution - specify - plan - tasks - implement. That’s all there is. Which brings me to my fatal argument against spec-kit: Spec-Kit’s design assumes that this cycle is complete. Notice anything? Something absolutely critical is missing: debugging. There is simply no slash command for it. In a quarter century of practice, even with AI, I have almost never encountered a case where implementing a plan produced no errors that needed debugging.

In the absence of a corresponding spec-kit command, you have no choice but to debug around spec-kit. All the elaborate agreements in the constitution don’t apply then. They live in the hidden .spec-kit directory, inside the memory folder. None of it applies at precisely the moment when what I consider the most important work — debugging, revising decisions already made — takes place. If you can only handle important things by going around the system, you shouldn’t start with the system in the first place. You could argue: yes, but you can jump back to the chat after the implement command and prompt your problem there. Theoretically yes. Practically no. Do you know what a chat window looks like after it has implemented a complete plan? The window is at least 70% full. Every further prompt in it invites hallucinations and errors. Which then need to be debugged in the same place… It simply doesn’t work in practice. I had to learn that the hard way. You need to be able to start a new chat to debug something, and that’s not possible with spec-kit.

Two months on, I believe you’re better off setting up a sensible AGENTS.md that applies to every AI, rather than spending time with spec-kit. Maybe then a few additions for specific AI tools — for example a CLAUDE.md entry about when to use the self-created skill for Context7, and so on.

Besides, the IDE landscape has already shifted significantly in just two months. Cursor now has its own plan mode. That’s no longer Kiro’s unique selling point. All the IDEs are investing heavily in parsing prompts as efficiently and intelligently as possible. But you also need to let these tools breathe, let them play to their strengths. You do that by simply telling them what you want in plain language. Talking to them, answering follow-up questions. That’s what they are and will increasingly be optimized for. What you feed them through the filter of spec-kit is a straitjacket.

In December 2025, it doesn’t even have to be an IDE. I’m doing more and more directly in Claude Code. In daily work, where you switch between projects a lot, it’s often simply faster and more direct.

That said, here is my original blog post from October 22, 2025, unchanged:

Using GitHub Spec-Kit

Introduction to Spec-Kit: How to Build Production-Ready Applications with Cursor and Spec-Driven Development (SDD)

This blog post was created in part with the help of Gemini and is based on an analysis of the following sources:

https://github.com/github/spec-kit

Why Spec-Kit? The Structure AI Agents Need

You know the problem: You have a great idea for an application, write the prompt, hand it off to your coding agent and think: “All right, let’s go!” And then you get results that are buggy, missing important features, or the agent has even added things you never asked for.

Coding agents are incredibly powerful, but they need structure. They need the same details that real developers use: edge cases, user stories, and architectural decisions.

That’s exactly where GitHub Spec-Kit comes in. It’s a structured workflow that executes scripts and finely tuned prompts to generate high-quality context for your AI agent. Essentially, Spec-Kit introduces Spec-Driven Development (SDD) into your workflow. SDD is a proven methodology where everything is planned and documented upfront.

Spec-Kit is not an AI model — it’s an open-source framework and command-line interface (CLI) that provides the structured process. It acts as the “conductor”, supplying the score and setting the tempo.

The Symbiosis: Spec-Kit as Conductor, Cursor as Virtuoso

Spec-Kit is agnostic about which coding agent you use. You can use it with Claude, Codex, or Cursor.

In this division of labor, Cursor is the “virtuoso” — the intelligent, AI-powered code editor that executes the instructions from the Spec-Kit framework.

Using Cursor

When you use Spec-Kit together with Cursor, you work with the built-in slash commands. Instead of entering prompts manually, you execute predefined, context-rich prompts provided by Spec-Kit, such as /Spec-Kit.constitution or /Spec-Kit.specify. Cursor’s internal AI engine reads this prompt, understands the context from the Spec-Kit templates, and then generates the corresponding files.

A key advantage of using Cursor is the multi-LLM environment. Spec-Kit has no language model of its own; instead, it uses whichever model is selected and configured in the Cursor IDE. This gives you maximum flexibility:

The Spec-Kit Workflow: Phases of SDD

The Spec-Kit workflow is divided into several critical phases that ensure the AI has all the necessary information before it starts writing code:

1. Constitution (The Laws of the Project)

This is often the first step you run. The Constitution establishes the non-negotiable project principles and standards.

2. Specify (What and Why)

This is the start of the Feature Life Cycle. In this phase, you tell the agent which feature you want to build, using exclusively business requirements and user stories.

3. Clarify (Optional Precision)

This optional step is highly recommended. The agent analyzes the generated spec.md and asks clarifying questions about ambiguities or missing details (e.g., sort order or pagination).

4. Plan (The How)

The planning phase follows from the finalized specification.

5. Tasks (Granular Steps)

The plan is broken down into individual, executable steps.

6. Implement (Code Execution)

This is the step where the coding agent writes the actual code.

Advanced Technique: Context Management with Cursor

For complex projects, especially with greenfield development, you may need to analyze logic from legacy systems.

Conclusion

Together, Spec-Kit and Cursor offer a structured, transparent, and scalable methodology for modern software development. The process is dialogue-oriented and requires careful review and refinement of all generated artifacts on your part. By clearly separating process (Spec-Kit) from intelligence (Cursor/LLM), you retain control over the architecture and ensure that your AI agents build applications that actually match your vision.

The generated documents (spec.md, plan.md, tasks.md) are not just instructions for the AI — they become living documentation for your team and are invaluable tools for code reviews. You can reuse these specifications in the future, even if you switch the entire technology stack.

Legal notice | | My GitHubRSS