What I Learned Trying Spec-Driven Development on a Side Project

Spec-Driven Development kept showing up in my feed — GitHub’s open-source Spec Kit, the idea of taming AI coding agents with structured, version-controlled specs, and lots of confident takes about how it changes everything.

I wanted to see whether the workflow actually held up, so I tried it on a personal learning project (a mobile app backed by Firebase). This isn’t a “we rolled it out at scale” post. It’s what a solo developer noticed after working through the loop honestly.

What Spec Kit Actually Is

Spec Kit is GitHub’s open-source toolkit for Spec-Driven Development (SDD). The premise: instead of treating AI coding agents like search engines you throw vague prompts at, you put a structured specification at the center of the loop. The agent reads the spec and the rules; you review the plan before any code gets generated.

In the repo, it lives under a .specify/ directory and uses four canonical files:

1. constitution.md — The project’s foundational principles. Things like code quality standards, testing requirements, architectural principles, and performance baselines. It’s the foundation the agent references through every later phase.
2. spec.md — The living product specification. You update this before you prompt the AI. It defines the “what” — focused on requirements and intent, not the tech stack.
3. plan.md — A technical implementation plan the AI generates before writing code. Tech stack choices, architecture decisions, the “how.” You review it before approving.
4. tasks.md — The plan broken into an ordered, file-level checklist the agent works through during implementation.

The whole point is that the AI’s suggestions are bounded by files you control, version, and can review — instead of by whatever it pattern-matched from your prompt.

The Waterfall Question

The obvious critique is that this sounds like Waterfall in a trench coat. Who wants to write long upfront specs in the agile era?

In practice, the files are lightweight and scoped per feature branch — not a six-month design lock. But SDD does introduce real planning overhead. Imagine adding something like Google Sign-In to an app:

• Ad-hoc: You prompt the agent, get working code in seconds, merge it, and discover two weeks later that it pulled in an unapproved OAuth library, bypassed your auth wrapper, and styled its own buttons. Now you’re refactoring.
• Spec-driven: You update spec.md, the agent reads constitution.md ("use the central auth SDK"), generates a plan.md you actually review, and the implementation is more likely to come out aligned the first time. But you spent real time on the upfront loop before any code existed.

The trade is friction shifted upstream against refactoring shifted downstream. Whether that math works depends on the change.

What I Noticed Even on a Solo Project

Two things became obvious quickly, neither of which the official docs emphasize:

It is massive overkill for small changes. Running the full Spec Kit loop to adjust a padding value or fix a typo is absurd. Even alone, I started carving out a mental triage rule: full loop for new features and non-trivial refactors, ad-hoc prompting for everything smaller. If a team forced the full workflow on every change, velocity would crater. The discipline is knowing when not to use it.

Vibe-planning is a real failure mode. The biggest risk I hit wasn’t bad code — it was a confidently written plan.md that sounded completely reasonable but referenced an API surface that didn't actually exist. If you don't read the plan with the same skepticism you'd bring to AI-generated code, you've just moved the vibe-coding one step upstream. Same problem, new wrapper. The plan review only works if you actually do it.

There’s a third thing I genuinely can’t speak to from a solo project: how this plays out on a real team. Spec Kit’s documented workflow is developer-driven — one developer running slash commands with their agent. But once specs are version-controlled markdown, there’s an obvious temptation to push spec.md toward PMs or constitution.md toward architects and design system owners. Whether that distribution actually works in practice — whether non-engineers will edit markdown, whether the contracts hold under deadline pressure — I genuinely don't know, and the docs don't take a position on it.

What I’d Want to Test at Team Scale

The questions I’d want answered before pushing for adoption at work:

• What’s the right triage threshold — by line count, file count, or risk?
• How do you keep constitution.md from rotting? It's only useful if it stays current with the actual decisions being made.
• Does the plan-review discipline survive deadline pressure, or does it become a rubber stamp?
• How much of the value is Spec Kit specifically, versus any structured pre-commit context for the agent?

If you’ve actually deployed SDD on a team — especially on an existing codebase rather than a greenfield project — I’d genuinely like to hear what broke and what held up.

SoftwareEngineering #AIAgents #SpecDrivenDevelopment #DeveloperExperience