Writing

From Guesswork to Specs: GitHub Spec Kit

Author

Andrew

Date Published

This piece riffs on and extends the ideas from the Microsoft for Developers article “Spec‑Driven Development: Spec Kit” and its companion video walkthrough embedded in that post. Big thanks to the GitHub + Microsoft folks for putting clean scaffolding around something many of us were brute‑forcing. Original article: https://developer.microsoft.com/blog/spec-driven-development-spec-kit

At 11:58 pm on a Tuesday - two minutes before a release window - I caught myself doing the thing I swore I’d outgrow: guessing. A quick “it should be fine” commit, a prayer to the CI gods, and a mental TODO to circle back tomorrow. Tomorrow arrived wearing steel‑capped bug reports.

That was the moment I tried Spec‑Driven Development (SDD) in earnest. The tool that helped it stick was GitHub Spec Kit - a lean set of templates, prompts, and a tiny CLI that turns “what are we even building?” into something both humans and coding agents can understand without creative misinterpretation.

What I mean by “spec‑driven”

SDD isn’t waterfall cosplay. It’s the opposite of bureaucracy. You capture the why behind a change, then the how, then the work plan - as living markdown in your repo. The win isn’t fewer meetings; it’s portable context you can hand to a teammate or an agent and get the result you intended, not the result you implied.

Meet Spec Kit (and why it clicked)

Spec Kit is purposefully small:

  • A Specify CLI that scaffolds your repo for SDD and injects agent‑friendly prompts.
  • Templates + helper scripts for specs, technical plans, and task breakdowns - kept in your repo, not stranded in a third‑party tool.
  • A tidy constitution.md with a few non‑negotiables (testing rules, security posture, “CLI‑first,” etc.) that guide both humans and agents.

Quickstart:

1uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

From there, Spec Kit encourages a three‑step flow (used with your coding agent of choice):

  1. /specify → the what and why (no tech choices yet)
  2. /plan → the how (frameworks, data contracts, quickstart)
  3. /tasks → reviewable, bite‑sized work with a definition of done

You version the generated markdown under specs/, review it like code, and let the plan drive implementation.

Field notes from my world

Context: I’m building a property‑ops platform with a Dataverse core and React/TypeScript front‑ends. One thorny feature was a temporary access window for on‑site contractors - clean permissions, auditability, revocation without drama.

  • /specify captured user outcomes before tech gravity set in (e.g., “access attempts outside the window are denied and logged; owners can revoke mid‑window”).
  • /plan proposed stack moves and edge cases, constrained by my constitution.md (e.g., structured audit events, e2e tests by default).
  • /tasks split the work into PR‑sized chunks - DB migration, policy checks, API route, UI affordances, test scaffolds - each with a tight DoD.

Stakeholders floated a “what if we…” variation. Instead of refactoring live code, I branched the spec, asked my agent for an alternate plan, and weighed trade‑offs side‑by‑side. That’s the superpower: decisions become diffable.

Why this beats guess‑and‑go

  • Shared language beats lore. New devs don’t need to spelunk through Slack archaeology to find the “real” requirements. The spec is the shared memory.
  • Agents do better with guardrails. A precise spec + plan + tasks yields fewer uncanny deliverables and more boringly correct PRs.
  • Change becomes cheap again. Specs are markdown, not marble. Edit, review, regenerate plans - and only then touch the implementation.

Try this in under an hour

  1. Initialise Spec Kit in a sandbox repo with specify init, pick your coding agent, and commit the scaffolding.
  2. Write one crisp /specify for a bite‑sized feature (two–three user outcomes, explicit non‑goals).
  3. Run /plan, skim the quickstart and data contracts, and tune anything your constitution mandates.
  4. Use /tasks, assign a couple to your agent, keep one for yourself, and validate the flow end‑to‑end.

Practical tips:

  • Front‑load clarity. Treat /specify like a mini‑PRD: who, what, why, done.
  • Keep the constitution short. A handful of hard rules beats a novella nobody reads.
  • Tweak the templates. The defaults are opinionated; bend them to your org’s shape.

Credit, sources, and the video

  • Original article: Spec‑Driven Development: Spec Kit on Microsoft for Developers - the piece that frames the philosophy and introduces the CLI and templates. It also contains a video walkthrough that demonstrates the end‑to‑end flow. Start there if you prefer a guided tour. https://developer.microsoft.com/blog/spec-driven-development-spec-kit
  • GitHub Spec Kit repo: templates, prompts, and the specify CLI you can pull into a new or existing repo.

I haven’t abandoned intuition; I’ve given it a harness. Write the story first, let the code follow, and keep your decisions reviewable. Midnight “she’ll‑be‑right” commits have left the chat.