Journal · The AI Architect · 2026-07-23
Spec twice, build once. A wrong idea costs a pencil line on paper — and a whole rebuild once it's built.
Spec twice, build once. A wrong idea costs a pencil line on paper — and a whole rebuild once it’s built.
The tension isn’t really about planning versus doing. Most people already believe in planning, in theory. The trouble is that planning feels like stalling when your hands want to move, and building feels like progress even when it’s the wrong thing being built. So we build first and think later, then wonder why the third rewrite still isn’t right. The real problem isn’t a lack of discipline. It’s that thinking on paper feels slower than thinking in code, even though it almost never is.
Cheap mistakes are a feature, not a failure
A pencil line costs nothing to erase. That’s not a throwaway fact, it’s the entire argument for specifying first. When you sketch a plan, a data model, a flow of screens, or even just a paragraph describing what the thing should do, you’re creating a space where being wrong is free. Nobody has to refactor a sentence. Nobody has to migrate a database because you changed your mind about a diagram.
Once code exists, wrongness gets expensive fast. A misunderstood requirement buried in a spec document takes two minutes to fix. The same misunderstanding buried in three thousand lines of working code can take days, and it usually surfaces at the worst possible time, when someone else is depending on that code already.
Try this: before you open your editor for a new feature, write five sentences describing what “done” looks like. Not code, not pseudocode, just plain sentences. Then read them back and ask what’s missing. You’ll often catch the wrong idea right there, on the page, where it costs you nothing.
Specs are for arguing with yourself
The reason spec-first work feels unnatural to a lot of builders is that it looks like paperwork, like something you do to satisfy a manager or a client. But the most valuable audience for a spec is you, an hour from now, or you, tomorrow morning, having forgotten half of what you were thinking today.
Writing the spec is where you find out you don’t actually know what you meant. You’ll write “the user updates their profile” and then have to stop and ask: which fields, what happens to old data, what if two people edit at once. Code doesn’t ask you these questions until it breaks. A spec asks you immediately, while the answer is still just a sentence away from being changed.
This is especially true now that so much building happens with AI assistance. An AI will happily generate a full, working, wrong system from a vague prompt. It won’t push back on your unstated assumptions, it will just build on top of them, confidently, at speed. A short spec is the cheapest way to catch your own bad assumptions before they get compounded into three hundred lines of generated code that all depend on the same wrong idea.
Try this: for your next task, write the spec as if you’re handing it to someone who isn’t in your head, even if no one else will ever read it. Not because they need it, but because forcing yourself to be explicit exposes the gaps you’d otherwise carry straight into the build.
The rebuild is the real cost, not the delay
People resist specs because they feel like a delay before the real work starts. But a rebuild isn’t just a delay, it’s a delay plus the original delay plus the emotional cost of throwing away something you already made. Nobody enjoys deleting code they were proud of an hour ago. That reluctance is exactly why bad ideas survive too long once they’re built: we get attached, and attachment makes us defend decisions we’d have abandoned instantly on paper.
Specifying first isn’t about being slow and careful for its own sake. It’s about making sure the thing you eventually get attached to is the right thing. A day spent sketching, questioning, and revising a plan is a day spent making your future self’s job easier. A day spent building on an unexamined idea is a day you might have to spend twice.
Try this: the next time you feel resistance to writing a spec because “it’s obvious what to build,” write it anyway, in under ten minutes. If it really was obvious, you’ll have lost nothing. If it wasn’t, you’ll have just saved yourself the rebuild.
None of this is a rule that gets easier to follow just because you understand it once. It’s a habit, and habits need more than one explanation to stick. The book goes further into how to write specs that are actually useful rather than just performative, and how this plays out differently when an AI is doing much of the building alongside you. This essay is just the doorway.
Go deeper. The full method is in The AI Architect. New here? Start with the free companion pack, or explore the series.