Return of the Spec | caines.ca

Skip to content

Return of the Spec

Agentic development is bringing a resurgence of "the specification". Maybe you've been writing detailed specs all along, but I've been mostly following Working software over comprehensive documentation. To some it'll sound like I'm some combination of crazy and lazy, but historically I have not found heavy specs to be worth the time or effort for a number of reasons I'll get into later. Agentic development is forcing me to take a second look though. Here's why:

Here's what changed

They're easier to write now

Long, detailed specs are cheaper and easier to write now, changing the ROI calculation dramatically. You can have an agent write them for the most part and you can just check them for correctness. I'll talk about how later in this post.

They're better informed

Agents are also capable of understanding complex codebases much faster than I ever could, so the specs can be written much more quickly and can take a lot of the complexity of the codebase into consideration in advance. When trying to add a complex feature to a complex codebase, I used to just start chipping away without much investigation (e.g., I'd start by just writing a failing test, even though I couldn't remember how the code was implemented at all), but now the agents can understand the codebase in a few moments and help you write a much more informed spec up front.

They take the human out of the loop for longer

But the most important advantage of a detailed spec now (and the actual reason for the resurgence) is that it can be used as a detailed prompt.

When the spec is really nailed down, you can sometimes set a /goal to satisfy the spec, let an agent spin up whatever subagents it needs, and let it run until the work is done. This frees you up to do other things.

While this is the most valuable part, I want to be clear about the rationale: The goal is not fewer human decisions; it’s fewer low-value interruptions. You still want human judgment where it's actually necessary.

Why it wasn't worth it before

Traditional specifications are not executable like code or tests, and humans forget to update them after changes, so they get out of sync with reality quickly.

The automated tests (and the application code itself, though often less clearly) described how the software should behave, and they were actually executable.

It took a ton of time that I could have been spending writing code. It's not enough for specs to just be useful; they have to be worth the effort.

Isn't this just waterfall again?

There are 3 aspects of the spec that have traditionally been pretty waterfally:

The spec will invariably be wrong

The spec will invariably be wrong (either incompatible with the existing product/codebase, or not actually the best solution for the user/business) in some ways that we can't foresee. Sometimes it will be disastrously wrong. You just can't know everything in advance. We need to be iterative.

In my experience, agents that have access to the codebase can find many problems/questions/concerns with a plan that I hadn't thought about in advance. This allows the agents to be a tool for writing specs that are "less wrong" than specs I would have written on my own before agents existed.

Spending a long time on a specification doc is spending a long time without delivering actual solutions to user problems.

This is still true, but I think we have the tooling now to write good comprehensive specs really quickly. I hope I can prove that later.

Larger specs create larger batches and will create more problems downstream for reviewing and merging.

When you create a large spec, you can (and probably should) break it up into thin vertical slices for delivery. You don't need to get out of the feedback loop of a large plan; you can stay in that loop and verify whatever you want. A large spec doesn't need to change how you deliver things. It could actually include your delivery and validation plan, e.g., the actual slices, validation points, and stop conditions.

I always recommend delivering the most uncertain parts first when possible (even if just as a limited availability prototype), so if your plan turns out to be a bad one, you learn earlier rather than later.

Unlike in waterfall, these specs can and should be revisited whenever. They're not contracts. They don't promise to guarantee business or user success just by correct implementation. They're still not as valuable as working code. We still want to learn (and iterate) while building.

I still just delete them after implementation

In general I don't care about keeping specs around as documentation; they're meant only to be used for prompting in a short-term way. The codebase isn't necessarily documentation-free; for example I like ADRs to explain WHY I made certain decisions ("Why?" is a question that code rarely answers well).

There's still not really anything to force natural language specs to be in sync...