News

GitHub Spec Kit Experiment: 'A Lot of Questions'

• By David Ramel
• 09/16/2025

"GitHub Spec Kit is an experiment -- there are a lot of questions that we still want to answer, and if community feedback is an indicator, there are quite a few features we can still add to make the SDD process easier to use," says Microsoft about the new offering unveiled early this month.

The Sept. 15 post apparently seeks to clarify any developer doubt or uncertainty about spec-driven development in general and the Spec Kit in particular. For example, there's a description from author Den Delimarsky, principal product engineer, of what the whole approach is not:

• "Spec-Driven Development, or SDD, is not about writing exhaustive, dry requirements documents that nobody reads."
• "It's also not about waterfall planning or trying to predict the future through extensive planning exercises."
• "And it's definitely not about creating more bureaucracy that slows engineering teams down."

Instead, he said: "SDD is about making your technical decisions explicit, reviewable, and evolvable. Think of it as version control for your thinking. Instead of having crucial architectural decisions trapped in email threads, scattered documents, or locked in someone's head, you capture the 'why' behind your technical choices in a format that can grow with your project and your understanding of the problem space."

Specs as Living Artifacts
Delimarsky explained that SDD aims to prevent the misaligned assumptions that often emerge when teams jump directly into coding. He illustrated this with an example of building a notification system where each team member interpreted "notification preferences" differently. This, he said, "isn't a failure of communication -- it's a failure of shared context."

Under SDD, specifications are "living documents that evolve alongside your code, not dusty artifacts that you write once and forget." They serve as a shared, reviewable source of truth that can be revised as understanding improves

In an accompanying video, Delimarsky emphasized that this approach avoids what he called "vibe coding" -- producing code ad hoc without a clear plan or context. He said spec-driven development can "help you get out of that rabbit hole into a little bit more of a scalable solution for your software."

How GitHub Spec Kit Works
It operationalizes SDD through a set of scaffolding templates, helper scripts, and a command-line tool called Specify. The toolkit creates two key folders in a new project: .github for agent prompts and .specify for specs, technical plans, tasks, and helper scripts. The overall development flow is broken into three explicit gated phases that must be completed in order:

As Delimarsky demonstrated in the video, developers can generate these scaffolds using the Specify CLI: "It actually scaffolds things for you. So if you're a developer and you're thinking like, wow, what do I need to get started with spectrum development? CLI is right there."

Built-In Conventions and Tools
Spec Kit also introduces a constitution.md file that lets teams define non-negotiable project rules before implementation begins. Delimarsky described it as establishing "a set of non-negotiable principles for your project" -- for example, always requiring tests or adhering to specific framework versions. These principles are enforced when generating the plan, helping ensure technical decisions stay aligned with organizational standards.

Another component is a collection of ready-made prompt templates and helper scripts (available for both shell and PowerShell) that automate repetitive tasks, enforce branch consistency, and wire up agent context as work progresses.

Guiding Principles
The original announcement also framed Spec Kit around six core principles for SDD:

• Specifications as the Lingua Franca: Specifications become the primary artifacts; code is just one possible expression.
• Executable Specifications: Specs must be precise and complete enough to directly generate working systems.
• Continuous Refinement: AI agents continuously analyze specs for ambiguity, contradictions, and gaps.
• Research-Driven Context: Research agents gather technical and organizational context to inform specs.
• Bidirectional Feedback: Real-world metrics and incidents feed back into specifications for refinement.
• Branching for Exploration: Multiple implementation variants can be generated from the same spec to compare tradeoffs.

Still Early, and Experimental
Delimarsky repeatedly stressed that the kit is experimental. "We are here to learn. I just want to remind you that this is not a production scenario," he said in the video. "We want your feedback. We want your input. So if something breaks, if something doesn't work, if something that it produces is garbage, let us know." The repository has already drawn strong interest, surpassing 16,000 stars within its first week.

Delimarsky asked developers not to submit large architectural overhauls as unsolicited pull requests, saying, "Do not open a pull request that rewrites the entire thing as an MCP server ... if you have any big changes, make sure you talk about this first in the issue."

Resources
More information is available in the Microsoft developer blog post, the original GitHub announcement, the GitHub Spec Kit repository, and a previous Visual Studio Magazine article: "GitHub Open Sources Kit for Spec-Driven AI Development."

And as far as that community feedback mentioned by Delimarsky in the opening paragraph, you can find it here. In that feedback, the item with the most 👍approvals is: Support Cursor CLI, joining popular calls for support for OpenAI Codex, OpenCode, Warp, Amazon Q Developer and more.