AI Harness Engineering · Essay Seven · derek wang (derekwang85)
Dwight Eisenhower said it in a way that outlived every war plan it ever rode along with: plans are nothing; planning is everything. He meant that the document you write before the fight is worth next to nothing — what matters is the disciplined thinking the writing forces on you. AI coding has turned that insight upside down. We hand the model a one-line wish and watch it produce code instantly, skipping the planning and jumping straight to the execution. Then we spend the afternoon arguing with the result.
The fix isn't a better prompt. It's a correct sequence: the constraint files come first, the code comes last. If the order is right, the AI builds to a blueprint. If it's wrong, the AI improvises while it builds, and every decision it makes is "reasonable" and different from last time.
The default is backwards
Almost everyone uses AI coding the same way: open the editor, describe the feature, watch the code pour out, then review and patch. There's nothing wrong with the AI writing code. The problem is the sequencing — you've sent it straight to the chopping and pushed the sharpening (naming boundaries, pinning decisions, installing gates) to later, or never.
The toolmakers don't rescue you either. Their default interaction is "prompt in, code out," and they never once nudge you to think first. So most projects grow up code-first: fast, and increasingly crooked.
I learned this one the expensive way. On a trading system, I let the AI start writing immediately, and got the classic trio: the same "order status" named OrderStatus in one controller, Status in the next, and a string constant in the third; a quote_id field in the database today and an invented quoteNo in the DTO tomorrow, two fields that can't find each other. By the end I spent more time reconciling style and aligning fields than it would have taken to regenerate the whole thing.
The AI wasn't dumb. I'd never told it what to build first and what to build second, so it guessed. And what an AI guesses is always "looks right, differs from last time."
Four phases, code last
So I stopped trying to police what the AI writes and started policing the order in which files come to exist. Call it the project anatomy: a project has a fixed sequence in which its files grow, and the correct order has the code — the actual product — arriving last.
- Manifest — the pre-execution contract: what, why, how, which files, what counts as done, when to stop.
- Spec + ADR — pin what you're building and record why, so the decision survives longer than the session.
- Gate — install the automated check before the code lands, not after.
- Manual + Runbook — capture how to operate and how to recover, so the next agent (or human) can pick it up without re-learning.
The counterintuitive part: not one of these four phases produces a single line of runnable code. They're all constraint files. That's the whole distinction between this methodology and "just have the AI write it." Most people see a feature and reach for code. I reach for four files first. Drucker's old split applies: letting the AI write immediately is racing on efficiency — doing it fast. These four files brake on effectiveness — making sure it's the right thing being done at all. The files run nothing, but they decide whether what does run was supposed to.
The six fields of the manifest
The most valuable and least natural phase is the first. The Pre-Execution Manifest is a thinking-tool with a fixed shape: state, in one line each, WHAT you're changing, WHY, your APPROACH, the exact FILES involved, the objective way to tell SUCCESS, and the STOP conditions that should halt you.
The point isn't that it reads well. It's that it forces you to settle why, how, and what "done" means before you spend an hour generating code. The machine writes the code; answering these questions is your job. And the STOP field is the one that earns its keep: naming, up front, the moment you'd want to be consulted is what keeps an autonomous system from becoming a runaway one. Honest caveat — STOP is a soft constraint. It won't stop anyone by itself; that's the gate's job in Phase 3. Its value is moving the braking decision from after-the-regret to before-the-start.
The incident: a cache on the wrong side of a rate limit
A scar that proves the sequence. I had an agent add caching to a reporting endpoint. Two minutes, looked perfect. Only at acceptance did we find the endpoint sat behind a rate-limited upstream — the cache was the right thing done in the wrong place. If I'd filled in the manifest first, WHY would have made me write "because the endpoint is slow," and I'd have asked myself: slow because of caching, or because of the upstream throttle? The answer was obvious. A caching job that took two minutes cost me an afternoon, because I'd skipped three minutes of manifest. [ORIGINAL DATA]
The damage wasn't the bad code. It was the afternoon spent rediscovering a constraint that six fields would have surfaced in under a minute.
The plan trap
Fair objection: planning can turn into ritual. Fill six fields, get the AI to nod, then trust the nod as governance — that's the trap. A manifest isn't a protective spell; it's only worth ink if the spec and the gate actually check the work against it. A team that writes beautiful manifests and never wires them to execution has added bureaucracy with nicer formatting. The guard is to connect the paper to the pipeline: if FILES matters, the gate enforces it; if SUCCESS matters, the acceptance criteria test it.
Here's the test I'd grade myself on: if you left for a month, would the project hold together by its files alone? If not, the missing piece is almost never more code — it's this layer of written intent. The constraint system you build is, in the end, a road you're paving for the next AI and the next person, in an order that lets every later hand see where the boundaries are, why the decisions were made, how to pass the gates, and how to run the thing.
Top comments (0)