The inefficiencies of Spec Kit (and how I'd optimise it)#
TL;DR — Spec Kit is a great idea wearing too much armour. Its core job — helping you define features — is genuinely useful. But it tries to be a whole harness: it hogs context and drains tokens (so models compact and lose the very intent you wrote down), it's heavily opinionated (TDD and "best practices" enforced whether you need them or not), and it's simultaneously too heavy for small projects and too hard to track at scale. My answer is Spec Kit Lite: keep the spec, drop the harness.
Where I'm coming from#
I like Spec-Driven Development. Writing down what should exist before an agent generates how is one of the highest-leverage habits you can build in an AI workflow. Spec Kit deserves real credit for pushing this idea into the mainstream and giving people a concrete starting point.
So this isn't a takedown. It's a critique of scope. The more I used Spec Kit, the more it felt like a spec tool that had quietly grown into a full build harness — and that growth is where the inefficiencies creep in. Below are the four that bother me most, and the direction I'd take to fix them.
1. It's a context hog, and that drains your tokens#
Spec Kit injects a lot of scaffolding into the model's context: a constitution, a spec, a plan, a task list, research notes, contracts. Every phase adds more text, and a single feature can restate the same requirements across spec.md, plan.md, and tasks.md. One idea, paid for three times.
The real damage shows up when the context window fills. Most models will compact to keep moving — and compaction summarises away detail. The cruel irony is that the original spec intent, the thing Spec Kit exists to preserve, is often the first casualty. You end up with a tool that's supposed to protect context actively pushing you toward losing it.
How I'd optimise it: treat the spec as an artifact of record on disk, and feed the model only the slice relevant to the current task. Reference by pointer instead of inlining everything. The spec should be something the model consults, not something it has to carry in full on every turn.
2. It shouldn't be a whole harness — it should define features, full stop#
Defining a feature, planning it, breaking it into tasks, and implementing it are different jobs with different failure modes. Bundling them into one pipeline creates a monolith where a weakness in any stage contaminates the rest.
A spec tool should produce a clean artifact that any build workflow can consume. Instead, Spec Kit couples you to its own opinionated pipeline — its phases, its file layout, its way of working. If you already have an agent loop you trust, you're now fighting two harnesses instead of using one.
How I'd optimise it: stop at the spec. Produce a clean, portable feature definition and hand it off. "Spec Kit as a linter for feature definitions," not a factory that also swings the hammer.
3. It's highly opinionated when it doesn't need to be#
Opinions are fine. Enforced opinions are friction when they don't match your project's stage or domain. Spec Kit's constitution nudges — sometimes mandates — TDD and a fixed notion of "best practices."
But TDD-first isn't universally optimal. Prototypes, spikes, data and ML exploration, and genuinely throwaway code often don't benefit from writing tests first — yet the workflow pushes you there anyway. And "best practices" are applied without context: the tool doesn't know your team size, your risk tolerance, or your deadline. A rule that's wise for a payments backend is pure ceremony for a weekend experiment.
How I'd optimise it: opinions should be opt-in defaults, not gates. The constitution should be a template you delete from, not a compliance checklist you have to satisfy.
4. Too much overhead for small projects, too hard to track at scale#
This is a barbell problem — Spec Kit is awkward at both ends.
On small projects, the ceremony (constitution → specify → plan → tasks) dwarfs the actual feature. You spend more effort operating the process than building the thing.
At scale, you drown in spec folders with no cross-spec dependency view and no single source of truth once the code evolves past the docs. Specs are written once and rarely updated, so they rot — and misleading documentation is arguably worse than none.
How I'd optimise it: right-size by project. A lightweight, single-file mode for small work with no constitution and no phase gates. And for large work, treat specs as living documents with clear ownership and a cheap way to detect drift between spec and code.
The root cause: scope creep#
Every one of these problems traces back to the same thing. Spec Kit started as a way to define features and grew into a harness that wants to own planning, task management, and implementation too. Each added layer costs tokens, adds opinions, and increases the tracking burden — often without adding proportional value.
The fix isn't to patch the harness. It's to remember what the core job was.
Introducing Spec Kit Lite#
Spec Kit Lite is the direction I'm taking this — a lightweight tool that does one thing: help you define a feature, cleanly, and then get out of the way. It's a project I'll be building next, and it's designed as the direct answer to the four problems above.
The design principles map one-to-one to the critiques:
| Spec Kit problem | Spec Kit Lite principle |
|---|---|
| Context hog / compaction loss | Minimal footprint — one spec file, reference by pointer, feed the model only the relevant slice |
| Whole harness | Single responsibility — define the feature and stop; clean handoff to any build loop |
| Enforced opinions (TDD, best practices) | Opinions are opt-in — sane defaults you delete from, never gates |
| Overhead at both ends | Right-sized — tiny by default, scales by adding, not by ceremony |
What it deliberately won't be:
- No constitution or governance layer.
- No enforced workflow phases.
- No task execution or implementation — it hands off instead.
- No multi-file artifact sprawl per feature.
And the open questions I'm still chewing on:
- Single-file vs. minimal folder — where's the line before it becomes Spec Kit again?
- What's the minimum viable spec schema? (Goal, scope, non-goals, acceptance criteria — and stop.)
- Should handoff be a convention other tools read, or just clean markdown anyone can consume?
- Can optional modules (TDD, contracts) exist without recreating the bloat?
- What's the cheapest useful way to detect spec/code drift?
Closing#
Spec Kit got the important part right: define what before you generate how. It just kept going past the point where it was adding value. The optimisation isn't more structure — it's less. Keep the spec, drop the harness.
That's the bet behind Spec Kit Lite, and I'll write more as I build it.