Journal · The AI Architect · 2026-08-18
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 between planning and doing. It’s between the feeling of progress and the fact of it. Opening your editor and writing code feels like progress. Sitting with a blank page, sketching what the thing should actually do, feels like stalling. So most people stall on the sketch and rush the build — and pay for it later, when the rebuild costs weeks instead of the ten minutes the sketch would have taken.
The pencil line is cheap because it’s honest
A pencil line on paper doesn’t pretend to be finished. That’s its power. When you sketch a data model or write three sentences describing what a feature should do, you’re not committing to anything — you’re exposing your own assumptions to yourself before they’re wearing the disguise of working code. Code, once it runs, starts to feel true. Even bad code. It compiles, it returns a result, and something in your brain relaxes and says “that’s settled.” But it was never settled. It was just built before it was checked.
Try this: before you write a single function for your next feature, write five plain sentences describing what it does, who uses it, and what “done” looks like. Do this on paper or in a throwaway text file, not in a ticket system where it’ll feel official. If you can’t write those five sentences without hitting a fork — “wait, does it do X or Y?” — that fork was going to show up in your code anyway, except then it would’ve cost you a rewrite instead of a rewrite of a sentence.
Specs aren’t about being thorough — they’re about being wrong cheaply
People resist specifying because they imagine it means writing a twenty-page document nobody reads. That’s not the point, and it’s not what “spec” needs to mean. The point is finding out where you’re wrong while wrong still costs nothing. A spec can be four bullet points. It can be a rough sketch of three screens and an arrow between them. It can be one sentence: “when the user cancels, we keep their data for 30 days, not delete it immediately.” The value isn’t in the document’s length. It’s in the moment you write that sentence down and realize you don’t actually know the answer — better to hit that gap now than three weeks into a build, when the database schema, the API, and the UI have all quietly assumed different answers.
Try this: for your next task, write down every noun that matters — user, order, session, whatever — and one sentence for what happens to it in the main paths: created, changed, deleted, expired. If two sentences contradict each other, you’ve just found a bug for the price of a sentence instead of the price of a migration.
Build the smallest real thing, not the biggest imagined one
The other half of “spec twice, build once” is knowing when to stop specifying. Some people take the lesson too far and spec everything, forever, afraid to type a line of code until the design is airtight. That’s its own kind of waste — you’re now paying in time what you saved in rework, and you still haven’t learned anything real, because paper doesn’t push back. Code does. It shows you the edge cases your sketch missed.
So the discipline isn’t “plan everything.” It’s “plan the part that’s expensive to undo, and build the part that teaches you something.” A database schema is expensive to undo once there’s real data in it — spec that carefully. A button’s color is not — just build it and look at it. Learn to tell these apart, and the whole rhythm of spec-then-build stops feeling like bureaucracy and starts feeling like common sense.
Try this: before starting, ask “if I got this wrong, what would it cost to fix — a sentence, a file, or a migration?” Sentence-cost decisions, just build them and see. Migration-cost decisions, sketch them first.
Closing
None of this is really about pencils or paper. It’s about noticing which of your decisions are cheap to reverse and which aren’t, and giving the expensive ones a little more thought before they harden into something real. I go into more of the mechanics — how to spec without over-specifying, and how to tell which decisions actually deserve the extra ten minutes — in the fuller chapter in the book. But the instinct itself you can start practicing today, on whatever you’re about to build next.
Go deeper. The full method is in The AI Architect. New here? Start with the free companion pack, or explore the series.