The AI Builder Principles

Introduction

In the AI era, software is commonly built by people who cannot read its code. Prototypes built this way are judged on whether they impress. Production software is judged on whether it creates value, and on whether it keeps creating it after the person who prompted it has moved on.

The AI Builder Principles are a methodology for building production software that:

• Is owned by the builder, who is answerable for it whether or not they can read it;
• Is held to the standard of software written by hand, because the people who depend on it do not care how it was made;
• And is built by a method the builder can repeat, because the method is the thing they actually own.

The principles do not assume nobody can read the code. Most of this work ends up in front of someone who can, and they are written so that handoff goes well. They can be applied on any platform, using any combination of models and coding tools.

The job of an AI builder

The builder produces the system. The system produces the outcomes.

That is the whole claim, and the twelve principles are its specification. It is also the easiest thing here to skip, because the outcome is what somebody asked for and the system is not.

DORA's 2026 finding is that the largest returns on AI come not from the tools but from the organizational system around them: platform quality, workflow clarity, team alignment. Adoption follows a J-curve in which capacity dips before it rises. Their unit of analysis is an organization and mine is one builder, so whether that transfers is a real question. If it does, the system is the only thing on this page that compounds, and everything that follows is an instruction for building one.

Which means the attribution has to stay honest and the asymmetry visible: their names on their work, your name on the outcome.

It carries a band like everything else, and it is the weakest-evidenced claim here. I have one factory and no measurement that it compounds. Argue with it.

Background

A demo has to survive one showing. A prototype has to answer one question. A personal tool only has to work for the person who built it, on the machine they built it on. Production software is the first rung where someone else is exposed when it breaks.

Nothing about how the software was made moves it up or down that ladder. Only who depends on it. An internal tool with four users is production software. A model answering customer questions is production software.

That is the whole reason this set exists. The tools got good enough that a domain expert can produce something that works, and the ladder didn't move to accommodate them. The standard is the same standard it has always been, and it is being met by people who cannot personally check whether they met it.

I have been on the other side of this. I joined Microsoft in 2000 as a technical product manager on Visual Studio and .NET, and spent the next several years evangelizing to people in businesses and communities all over the world how to do it properly. We told several million developers that their tightly coupled applications needed to be taken apart: separate the tiers, put a real boundary between the interface and the data, secure it, scale it, expose the seams as web services. And they did it. The guidance was correct, and it was adopted at a scale most methodologies never reach.

The pile kept growing anyway. Not because the guidance was wrong, and not because people were careless. It grew because the same tools that put good architecture within reach also made building faster than judging, and guidance loses that race every time.

That is the part I would ask a reader to take seriously before taking anything else here seriously: last time, being right and being adopted was not sufficient. Nothing in this document is durable unless it survives the same race, which is why the thesis above the principles matters more than any single one of them.

The race is now measured rather than merely suspected. Faros telemetry across roughly 22,000 developers found throughput climbing — epics completed per developer up 66.2% — while incidents per pull request rose 242.7%, with no evidence that teams with strong pre-AI engineering performance were insulated. Google Cloud's DORA team reached a compatible conclusion from the other direction: AI amplifies the organizational system it lands in, and code becomes a liability when volume outruns the verification around it.

What I have done since is the reason I am writing this rather than reading it. For the past several years I have built and rebuilt production software with AI, as someone who cannot read the code, long past the point where building was the interesting part. What I have now is closer to a factory than a project: a standing team of agents with defined seats, a supervision ladder they climb on evidence rather than on my confidence, a specification pipeline that will not start work it cannot verify, and enforcement that is mechanical rather than advisory. The principles below are what that cost. Each one is something I got wrong first.

They come in two sets because the factory has two halves. Some are decisions only the builder can make, and they would hold if no agent were involved at all. The rest are how you direct something that does what you inspect rather than what you expect. The first set is older than AI. The second is what AI added.

None of this requires you to learn to read code. It requires you to stop treating that as the only way to know. Every principle below is a way of establishing what is true about software you did not write and cannot inspect directly — which is a discipline, not a workaround.

What this set does not claim

It does not claim that specifications replace code. Thoughtworks currently places spec-driven development in the Assess ring of its Technology Radar rather than Adopt, on the grounds that executable code remains the source of truth and still requires maintenance. That objection is correct and this set concedes it. A specification here is not a substitute for the artifact; it is the instrument through which a person who cannot read the artifact still exercises judgment over it.

It does not claim that more specification is better. When a spec becomes pseudo-code, the program has been written twice and neither copy is trustworthy.

It does not claim novelty for the inherited four, and it does not claim ratification for anything marked Hunch.

Who should read this document?

Any domain expert building applications with AI that run as a service. Founders, product managers, and functional experts in finance, operations, marketing or sales who are responsible for code they can't read, and the engineers and architects who end up operating what they built.

If you are building the agent itself, Horthy's set is the one for that.

How the bands work

Every principle carries a confidence band and the date it last moved. Bands are claims about my evidence, not about the principle's importance — a Hunch may matter more than something Held.

• Hunch — held on one observation, published early because being wrong in public is faster than being right in private.
• Working — reliably true for me, with no evidence yet about anyone else.
• Held — I have made real decisions on it repeatedly and it has held so far. It is still paying for its place.

Bands move both ways, and a band moving down is the most useful thing on this page.

External measurement is noted where it exists, but it does not move a band. The numbers in the background establish that the problem is real; they say nothing about whether any of these twelve answer it.

Your experience is different. If one of these held for you, or broke, that is evidence I don't have and cannot get alone — it is the only thing that moves a principle out of Working, and the fastest thing that moves one down. Tell me here — choose Principles as the subject — and I will publish what moved, why, and who moved it. Someone else's measurement is not my experience, but someone else's experience is, and the bands are the only place in this document where I am the instrument.

The Principles

The work itself has not changed shape. You decide, you specify, you hand off, you check, you iterate. What changed is that most of the middle is now performed by something that cannot be held responsible for it so every step that used to be verified by reading has to be verified some other way. The principles below are those other ways.

Both tables run from most foundational to most dependent, and the builder table comes first because the agent principles assume it. The early ones can be held today, with nothing else in place. The later ones need something already built. The last one in each table will not make sense until you have been at this a while.

Principles for the builder

Principle	One-liner	Band
One codebase	One place the software lives, with every change committed so you can always get back to working.	Held
Shared language	Use words that mean one thing to the builder, the model, and the engineer.	Held
Trust and verify	Own the definition of done, and write the acceptance criteria yourself.	Held
Subtract first	Less is more. Ask what to remove before you add anything.	Working
Own the decisions	Know which decisions are yours, and delegate the rest on purpose.	Held
Write contracts	Define what each piece promises before anything builds it.	Held
Think big, start small	Decompose until the smallest piece still delivers value on its own.	Held

Principles for directing agents

Principle	One-liner	Band
Set and enforce boundaries	Declare what a change may reach, and enforce it where the machine can.	Held
Guidance is no guarantee	Write the rules down, then spot-check the work.	Working
Ground wide, work narrow	Make the agent trace what a change touches, then carry forward only what bears on it.	Held
Classify then route	Match the task to the model that can do it.	Held
Autonomy is earned	Run the same steps every time, and watch less only after the agent has proven it.	Held

All bands were set in September 2026. None has moved yet.

Inherited from twelve-factor

These four are Adam Wiggins' and are restated in decision voice because a builder who cannot read the code still has to make them. No novelty is claimed for any of them.

• Codebase — there is one codebase, and you can say where it is. Adapted from factor I.
• Config — secrets are yours to grant, never the code's to carry. Adapted from factor III.
• Parity — what you approved is what ships. If they differ, you approved nothing. Adapted from factors V and X.
• Logs — decide what you must be able to answer at 2am, and require that it be answerable without reading the code. Adapted from factor XI.

A worked example

Illustrative. The content is invented; the shape is not. One small piece of work, at each of the five stations it passes.

An operations lead notices their team learns about overdue invoices too late. They cannot read code. This is what the same unit of work looks like at each station, and which principle each one is discharging.

1. The decision

Builder — Own the decisions, One codebase.

Overdue invoices surface in the ops dashboard, not by email. Considered and rejected: a daily digest email, which adds a place to look; a Slack alert, which fires when nobody is holding the question. Chosen because: the team is in the dashboard every morning already. Seat: mine. I own how the ops team works and nobody is better grounded on that. Way back: the column is additive and behind a flag. Turn the flag off.

Note what is absent: alternatives. They were spent here, on purpose, so nothing downstream reopens them. And the way back exists before anything is built, not after something breaks.

2. The specification

Builder — Write contracts, Shared language, Think big start small, Subtract first.

Overdue-invoice column Sits under: "The team can see the state of receivables" — the big thing. This is the smallest slice of it worth shipping on its own. The link to the parent is recorded as a field, so the thread is checkable rather than remembered. Vocabulary: Overdue means past its due date and not fully paid. Not "unpaid" — that includes invoices not yet due. This definition lives in the standing instruction file the model reads every session, not in this document. In scope: the receivables list view, and the query that backs it. Explicitly out of scope: the invoice detail page, any change to how due dates are set, notifications of any kind. How anyone will know it worked: the list shows a column marked Overdue; an invoice one day past due appears in it; an invoice due tomorrow does not.

The specification says what, not how. It does not say which query, which component, or where the flag lives. Those are the engineer's, or the agent's, and if the spec chose them for it, the program would have been written twice.

The out-of-scope line is the one that took work. Notifications were the obvious thing to add, and adding them would have made this two features pretending to be one. Every item on that line is something a reasonable person suggested and I removed before anything was built, which is cheaper than removing it after.

3. The assignment

Directing agents — Ground wide work narrow, Classify then route, Set and enforce boundaries.

Type: routine. One view, one query, an established pattern already in the codebase, so the fast model and light supervision. Traced first: before bounding anything I asked what the change would reach. The answer came back as three files, not two: the receivables list view, the query behind it, and a shared date helper both of them call. Boundary: those three files and nothing else — drawn against the trace rather than from memory. Declared here, before the work is claimed, so it can be checked against everything else in flight. Correct when: the three checks in the specification pass. Shippable when: tests written and green, the existing checks still pass, the flag is documented.

The specification said what should change. The trace said what the change reaches, and those are not the same list. The date helper appears in neither the decision nor the specification, and it is exactly where the timezone problem at station 4 lives — a boundary drawn from the specification alone would have left it outside, and the finding would have arrived as a surprise in production instead of as a note on a review.

Correctness and shippability are separate lines because a different party checks each, at a different moment. The boundary is a third thing again: it is not what the work must do, it is the worst it can reach.

4. The gate

Builder — Trust and verify.

Acceptance: PASS. Each of the three checks from the specification, scored against the actual change by something that did not write it. Review findings, which do not block: two. An unhandled empty state, and a date comparison that will drift by a day across timezones. Both recorded.

The gate returns a word I can act on. The findings go on a list I read on a cadence, and when the timezone finding appears a third time, the thing to fix is not the third change. It is whatever keeps producing it.

5. The verification

Builder — Trust and verify.

What I did, myself: opened the dashboard. Screenshot attached. Created an invoice due yesterday and one due tomorrow; the first appeared in the column, the second did not. Turned the flag off and reloaded; the column was gone.

Not "the checks are green." Not "it's deployed." I looked at the result, in a browser, and I made the thing I care about actually happen. The gate verified the change. Only this verified the outcome.

What made this repeatable is not any one station. It is that the next piece of work, and the one after that, passes the same five in the same order whatever their size. That fixed sequence is the first half of Autonomy is earned. That it goes on being the sequence after I stop personally holding it in place is the job itself: the builder producing the system, and the system producing the outcome.

Notice the shape. Two stations are the builder's before anything is handed over, one is the handover, and the last two are the builder's again. The agent is never alone with the decision at the start or the verdict at the end. That bracket is what the two tables describe.

One principle does not appear at all, and a second appears only in half — the honest result rather than an omission. Guidance is no guarantee is missing; Autonomy is earned shows only its fixed-sequence half, because watching less once the agent has proven itself cannot happen inside one unit. Both are about what accumulates across many pieces of work, which is exactly why they are the ones that get skipped.

How far along you are

The principles tell you what to do. This tells you how to know it is working. There are four rungs, and they describe where the human stands rather than what the software does.

• Doing. You are in every step. The agent helps; you carry the work.
• Approving. The work happens without you and stops for your yes. Specifications, gates and checks exist, which is what makes stopping meaningful.
• Informed. It runs unattended and tells you what it did. You read rather than decide.
• Curating. It improves its own operation, and your job becomes choosing what it should become.

Nobody sits at one rung across a whole system. You are Doing on one thing and Informed on another, and the useful question is never "where am I" but "which one thing moves up next, and what evidence buys it."

Related work

I am aware of what it looks like to write this document, having been the guy last time. Adam Wiggins' twelve-factor app is the direct ancestor. Twelve-factor describes properties of a well-built application; this set describes the decisions of the person answerable for one. Where they coincide, the factor is inherited, restated as a decision, and kept separate so you can see which is which. Dex Horthy's 12-Factor Agents covers the agent's architecture — tool calls, control flow, context management — for the person building the agent. This one is for the person who decided what it should do.