Cheap Code, Expensive Decisions: Why We Still Write the Design Doc
The first thing a team wants to delete once the model can generate a working draft in minutes is the design doc. The logic feels airtight: why argue on paper about an approach we could just build and look at? Generation is nearly free now — so prototype three options, run them, keep the one that works. The doc looks like the ceremony of a slower era, a tax you paid because writing code used to be too expensive to do speculatively. That reasoning is exactly backwards, and it took my team one genuinely expensive quarter to see why.
What got cheap was the typing. What did not get cheap — what got more expensive, in relative terms — was deciding what to build and being able to say why. A design doc was never really about the code. It was the place a team made a decision legible: here's the problem, here are the options we considered, here's the one we chose and the tradeoff we're accepting, here's what we're deliberately not doing. None of that is something the model produces for you. The model will happily generate any of the options you didn't think hard enough to reject. It has no opinion about which one your team should have to live with for the next two years.
"Just build it and see" hides the disagreement
The seductive failure mode is that generating a prototype feels like resolving a disagreement, when all it does is postpone it. Two engineers who disagree about an approach can now both produce a running version of their side in an afternoon, and then the argument isn't smaller — it's the same argument, except now there's working code on both sides and everyone's a little more attached. We shipped a feature that way once. It demoed fine. Three weeks later we were unwinding a data model that nobody had ever actually chosen; it was just the shape the first draft happened to generate, and by then four other things depended on it. The decision got made. It just got made by accident, by whichever prototype ran first, and no one could point to where.
A prototype answers "can this be built?" The design doc answers "should we, and what are we agreeing to own?" Cheap code only made the first question easier.
The doc got shorter and more valuable at the same time
So we kept the design doc — but the version that survived is not the version we wrote in 2021. The old doc spent most of its length on how: pseudo-code, class sketches, the mechanical plan for construction. That's the part the model is now good at, and it's the part that's cheap to throw away, so it doesn't need a document. The doc that earns its place is almost entirely about decisions. What problem are we actually solving, stated concretely enough to be wrong. What are the two or three real options, and why are we rejecting the ones we're rejecting. What's the tradeoff we're accepting on purpose. What does this commit us to that will be expensive to reverse. Ours are shorter than they've ever been — often a page — because we stopped writing down the parts a model can regenerate and kept only the parts a model can't decide.
The tell for whether a doc is doing its job is simple: could a reader disagree with it? A page of architecture diagram invites nodding. A page that says "we're choosing Postgres over the event log because we'd rather pay in write throughput than in the two engineers it takes to operate a second system" invites an argument — and the argument is the whole point. You want the disagreement to happen over the doc, cheaply, before the model has generated six thousand lines that quietly assume one side won. Generation being free makes it far too easy to skip straight to the code and let the code become the decision. The doc is where we make ourselves decide out loud first.
What this changes for how a team works
A few things follow once you treat the doc as a decision record and not a construction plan. Design review stops being a code walkthrough and becomes a conversation about the tradeoff — reviewers push on the option you rejected, not the syntax you chose, because the syntax is the cheap part now. Juniors write docs earlier, because the skill that matters most in an AI-tooled team isn't producing a draft — the model does that — it's being able to defend why this draft and not another one, and the doc is where that muscle gets built. And we let prototypes do what they're genuinely good at: killing an option fast when it turns out it can't be built at all. That's real information. We just make sure the prototype informs the decision instead of silently becoming it.
The honest version of "AI made us faster" is that it moved the expensive work upstream. When any option is minutes from running, the scarce thing is the judgment to choose the right one and the discipline to write down why — so that six months later, when someone asks why the system is shaped this way, the answer is a paragraph a human wrote on purpose, not a shrug and "that's what the model gave us." The design doc survived because the decision was always the expensive part. Cheap code just made that impossible to keep hiding.
If you're rethinking how your team designs now that a working draft is always an afternoon away, I'm happy to compare notes. Reach me at arun@arunjalota.com.