Vibe coding got me 80% there. Spec-Driven Development got me the other 20%.

I like vibe coding. I'm not here to shame anyone out of it. Some of the best things I've shipped started as a half-formed idea typed into a chat box at 11pm. But if you've done this for more than a weekend, you know the shape of the problem. The first prompt is magic. The fifth one is negotiation. By the fifteenth you're re-explaining a decision you already made twice, the agent has quietly renamed your data model, and you're one "fix the header" away from deleting the folder and starting over. The bottleneck was never the code. The agent writes code faster than I ever will. The bottleneck is clarity - and clarity is the one thing I kept keeping in my head instead of in the repo. That's the gap Spec-Driven Development fills, and Spec Kit is the toolkit that makes it practical. What is Spec-Driven Development? SDD is a simple inversion: the specification is the artifact you maintain, and the code is what gets generated from it. Not "write a PRD, then throw it away once real work starts." The spec lives in the repo, next to the code, in version control, and it's the thing you edit when you want the software to change. A real spec answers three things: - What the system does - entities, flows, screens, rules - How it must behave under constraints - auth, performance, compatibility, accessibility - Why the key decisions were made And it deliberately does not answer "which framework." That comes later, on purpose. The reason this matters more now than it did in 2015: your agent doesn't have your context. It has whatever you gave it in the last 4,000 tokens. A spec is context that survives a new chat window, a new model, and a colleague who joins on Tuesday. So what is Spec Kit? Spec Kit is GitHub's open-source toolkit for doing this. It launched in September 2025 as an experiment and it did not stay an experiment: 130K+ stars, 270+ contributors, 38 agent integrations, and a whole ecosystem of community extensions and presets. Install and scaffold: uv tool install specify-cli specify init my-project --integration copilot That drops a .specify/ folder plus slash commands into your agent (Copilot, Claude Code, Codex, Gemini, Cursor, Kiro, Zed - most of them). Then the workflow runs in chat: /speckit.constitution → /speckit.specify → /speckit.clarify → /speckit.checklist → /speckit.plan → /speckit.tasks → /speckit.analyze → /speckit.implement Every step produces a Markdown file that feeds the next one. Nothing is a black box. No proprietary editor. You can open any of it and type over it with your own hands, which you absolutely should. Two pieces deserve special attention: The constitution (.specify/memory/constitution.md ) holds your non-negotiables. "Static-first delivery." "No new dependencies without justification." "Every migration ships with a rollback." Every later phase is checked against it. This is the single highest-leverage file in the whole setup, and most people leave it as boilerplate. The gates - /speckit.clarify , /speckit.checklist , /speckit.analyze - are what separate this from prettier prompting. clarify hunts for ambiguity before you plan. checklist grades the requirements themselves. analyze cross-checks spec vs. plan vs. tasks before a single file gets written. For a quick prototype you can skip them. For anything you'll have to maintain, don't. Why would I use it? Four honest reasons. 1. It moves the argument earlier. Fixing a misunderstanding in a Markdown file costs a minute. Fixing it after 40 generated files costs an afternoon and your patience. 2. It makes the work reviewable by people who don't read code. This is the one that changed things for me. A spec is something you can send to a stakeholder, a PM, or a boss, and get real feedback on. Try doing that with a chat transcript. 3. Model churn stops being a threat. If the agent produced something mediocre, you don't lose the thinking. Delete the source, switch models, re-run /speckit.implement . Your spec is the durable asset; the implementation is disposable. That's a much better position to be in every time a new model drops. 4. It scales past one person. Chat context doesn't merge. Markdown in a git branch does. How will my projects actually improve? Concretely, from the pattern I keep seeing: - Fewer "start over from scratch" cycles. The rework loop shrinks because the misunderstanding gets caught upstream. - Edge cases you wouldn't have thought of. The spec templates force sections for acceptance scenarios and edge cases. The agent fills them, you correct them. Free QA thinking. - Onboarding stops being a conversation. "How does this work?" → read specs/001-*/spec.md . - Better decisions, because you had to write them down. Half the value shows up before you run anything. Writing the spec is where you notice that you never decided how episodes are ordered, or what happens when the list is empty. - Structured additive change. New feature = new spec folder = new branch. Your third feature doesn't quietly rewrite your first. The honest trade: it's slower on day one. For a landing page you'll ship this afternoon, this is ceremony. For anything with more than one screen, more than one contributor, or a lifespan longer than a demo, it pays for itself fast. Are there real-world examples? Yes, and I want to give you both halves of the picture. The supportive side: GitHub dogfoods Spec Kit on Spec Kit itself for substantial features. AWS built the same philosophy directly into Kiro and publishes customer cases where multi-day features shipped in a fraction of the human time when authored spec-first. There's a growing academic literature framing specs as the version-controlled contract between humans and agents, and community walkthroughs now cover brownfield adoption in .NET, Java, and Go/React codebases. The skeptical side, which you should read too: Thoughtworks put SDD in the Assess ring of their Technology Radar, not Adopt, and they push back hard on the idea that specs replace code as the source of truth. There's a fair critique circulating that SDD is contract-design and waterfall with better branding - and the sharpest version of that critique is also the best argument for it: the value is the thinking you do while writing the spec, not the tooling around it. Vendor-reported multipliers should be treated as directional, not proven. My read: the durable, less-disputable finding is that the human's time moves from typing implementation to specifying and reviewing. Whether that's a 3x or a 1.2x depends entirely on you. How do I apply it to a Product Engineering pipeline? This is where it gets interesting, because the workflow maps almost one-to-one onto roles you already have. | Phase | Command | Who owns it | |---|---|---| | Guardrails | /speckit.constitution | Tech lead + product, once per repo | | What & why | /speckit.specify | Product / PM | | Kill ambiguity | /speckit.clarify + /speckit.checklist | Product + eng together | | How | /speckit.plan | Engineering | | Breakdown | /speckit.tasks | Engineering | | Consistency audit | /speckit.analyze | Whoever reviews the PR | | Build | /speckit.implement | The agent, supervised | A few things that make this work in a real org rather than a demo: - The spec review is the new design review. Put it in the PR. That's your approval gate, and it's a much better artifact to argue over than a diff. - One feature, one branch, one spec folder. Spec Kit picks up the active feature from your git branch, so this falls out naturally. - Brownfield is supported and it's the normal case. Don't try to retro-spec your whole system. Initialize in place with specify init --here --force --integration on a clean review branch, write a constitution from rules that are already true in your repo, then pick one bounded change - a CSV export, one endpoint - and run the loop on that. - Decide up front how specs age. Frozen historical snapshot per feature, or living contract you regenerate from? Both are valid. Choosing neither is how you end up with docs that lie. - Wire the constitution into CI eventually. Community extensions already do architecture and compliance gates. That's where this stops being a personal workflow and starts being governance. Tips to actually get value out of it - Write the constitution yourself. Let the agent draft it, then delete two-thirds. Short and true beats long and aspirational. Unrealistic rules become noise the agent learns to ignore. - Use different models for different phases. Reasoning-heavy models are good at scaffolding specs and plans; I switch for implementation. Experiment - it's the only way to find out what works for your stack. - Never skip /speckit.clarify on real work. Unresolved[NEEDS CLARIFICATION] markers are the agent telling you where it's about to guess. - Edit the Markdown with your hands. People freeze up because "the LLM wrote it." It's a text file. If you want the logo centered, add a functional requirement and move on. - Don't over-specify. If your spec has become pseudocode, you've written the program twice. Specify behavior and constraints, not implementation. - Implement in phases. Core flow first, validate, then the rest. Dumping 60 tasks into one run saturates context and quality falls off a cliff. - Keep the spec free of tech choices. It feels unnatural. Do it anyway - it's what lets you regenerate the same product on a different stack later. - Feed it real design context. Hook up MCP servers (Figma, your issue tracker) so the plan references your actual design system instead of inventing one. - Treat a bad output as a spec bug first. Before you re-prompt, go read what the spec actually said. Nine times out of ten it's ambiguous there. What should I research before starting? Set aside an afternoon, not a week: - Your toolchain: uv /uvx for the CLI, and which integration key matches the agent you already use. - The core concept pages in the Spec Kit docs - "What is SDD?" and "Spec Persistence Models." Those two decide how you'll work six months in. - EA