Here is the complaint I hear most about spec-driven development, and it is not wrong: “I tried it, and I spent more time feeding the process than building the thing.” Proposal, spec, plan, tasks, review gates. For a solo developer or a small team moving fast, the ceremony can cost more than the code it is supposed to guard.
The usual response is that you just need more discipline. I think that is backwards. If a process only works with heroic discipline, the process is too heavy. The fix is not to try harder. It is to write a smaller spec.
The overhead is real, and pretending otherwise loses people
Full spec-driven pipelines were shaped in part by tools built for teams and larger changes. Spec Kit formalizes a flow through proposal, specification, plan, and tasks. That structure earns its cost when many people touch a change, when the blast radius is large, or when the decision needs a paper trail.
It stops earning its cost on a two-hundred-line feature you are building alone this afternoon. There, the same structure is friction. You write a proposal to convince yourself, a plan you already have in your head, and a task list you will not read again. By the time the ceremony is done, you have spent your energy on the artifact instead of the work, and the artifact starts drifting from the code the moment you close it.
Telling that person to be more rigorous does not help. They already know the full process. They abandoned it because it did not pay. The real move is to admit the overhead exists and design it down.
What a spec is actually for
Strip away the templates and a spec does one job: it is the contract that says what must change, what must not, and how you will know it worked. Everything in a spec that does not serve that job is overhead you can cut.
That reframing is the whole trick. You are not trying to document the feature. You are trying to write down the smallest contract an agent, a teammate, or future-you needs to build the right thing and prove it. Most of a heavyweight spec is not contract. It is restatement, hedging, and process artifacts that exist to satisfy the template rather than the work.
The lightweight recipe
Here is the version I actually use for a normal change. One page, three sections, written before the agent starts.
Intent (2-4 sentences)
What behavior changes and for whom. Not a user story ritual, just the sentence you would say out loud. “Guest users can check out without an account; the flow is three steps; nothing about logged-in checkout changes.” If you cannot say it in a few sentences, you do not understand the change well enough to hand it to an agent yet.
Boundaries (a short list)
What must stay true, and what is explicitly out of scope. This is the highest-value part of a lightweight spec and the part people skip. When an agent can generate plausible code fast, the constraints are worth more than the instructions. “Do not touch the payment provider integration. Do not store card data. Do not change the logged-in path.” Three lines here save you a day of untangling later.
Acceptance criteria (checkable, not prose)
How you will know it is done, written so a machine could check it, not so a human can nod at it. “Given a guest with items in the cart, when they complete the three steps, then an order is created and no card token is persisted.” These are acceptance criteria an agent can actually verify, which is what keeps a lightweight spec from becoming lightweight theater.
That is the spec. Intent, boundaries, acceptance. No proposal, no separate plan, no task breakdown unless the change is big enough to need one. For most changes, this fits on one screen and takes ten minutes.
The ten minutes are not overhead. They are the cheapest debugging you will do all week. Almost every time I have skipped this and let an agent run straight from a one-line prompt, the failure was not in the code, it was in the gap I never wrote down: a boundary I assumed was obvious, an acceptance condition I had in my head but never stated. The agent did not read my mind, so it filled the gap with something plausible and wrong. The one-page spec is not documentation of the change. It is the thinking you would otherwise do badly, in your head, halfway through the agent’s run, when it is already expensive to correct.
What you cut, and what you must not
The cuts: the proposal document, the design essay, the task list for anything you can hold in your head, the review gate on a change only you will touch, and every section that restates another section in different words.
The non-negotiables: intent, boundaries, and acceptance criteria. Cut any of those three and you do not have a lightweight spec, you have a note. The boundaries are the one people are most tempted to drop and the one that pays the most, because they are what stops an agent from breaking a working feature while adding a new one.
The other non-negotiable is keeping it current. A one-page spec you update as the change lands is a living spec. A one-page spec you write and abandon is just faster drift. Lightweight only works if cheap-to-write also means cheap-to-update.
When to add the weight back
Lightweight is a default, not a religion. Add structure when the change earns it:
- More people touch it. A shared change needs the shared artifact. A proposal and a review gate stop being ceremony and start being coordination.
- The blast radius is large. Migrations, auth, payments, anything where a mistake is expensive, deserve the design section and the explicit plan.
- The decision needs a record. When you will be asked “why did we do it this way” in six months, the decision log is worth writing down at the time.
The mistake is not using heavyweight spec-driven development. The mistake is using one weight for every change. Match the ceremony to the risk, and most changes get the one-page version.
Where PaellaDoc fits
A lightweight spec still needs somewhere to live that connects it to the code and the evidence, or it drifts as fast as any other. PaellaDoc holds the small contract in a local model wired to the repository and the run results, so a one-page spec stays cheap to write and cheap to keep current. You get the discipline of spec-driven development at the weight of a note, and you add structure only where the risk asks for it.
FAQ
Isn’t a one-page spec just an under-specified spec? No. Under-specified means the contract is missing pieces, usually the boundaries and acceptance criteria. Lightweight means the contract is complete but nothing else is there. A tight one-pager can be more complete than a ten-page document that buries the contract in restatement.
Does lightweight spec-driven development work with agents? It works better, because the parts you keep are exactly the parts an agent needs: intent to build the right thing, boundaries to not break the wrong thing, and acceptance criteria it can verify. The parts you cut were mostly for human process.
When should I not go lightweight? When the change is shared across people, high-risk, or needs a decision record. Match the weight to the blast radius. Lightweight is the right default for most changes, not a rule for all of them.