DEV Community: DerekWang

Maturity is not being certain you are right. It is knowing you could be wrong.

DerekWang — Tue, 29 Sep 2026 04:49:00 +0000

AI Harness Engineering · Essay Twelve (rebuild) · Derek Wang

Put two systems side by side. One answers almost anything and never blinks. The other occasionally stops and tells you it might have this one wrong. Ask yourself which one you would trust with core business, and most of us pick the first — no one likes the one that keeps making trouble. It took delivering hundreds of thousands of lines of code against real projects before we saw the honest answer: the second one is the one watching your back. A system's strength was never how often it is right. It is whether it can recognize when it is wrong, and name what it does not know at all.

Psychology names this exactly. It is the Dunning-Kruger effect: the people worst at something are the most sure they did it well, because the skill they lack is the very skill it takes to judge the work. If you are bad at logic, you cannot tell your own argument is bad. You are not just wrong; you are structurally unable to discover from the inside that you are wrong.

Put that on a machine and it stops being a personality quirk and becomes an engineering fact. An AI system with no constraints and no evaluation is not merely "not good enough." It cannot even form the sentence "I am not good enough." There is no organ in it that holds its own failure, so the thought has nowhere to live. That is the whole point every layer in this series has been circling.

Certainty is a ladder, but maturity is two axes

Thirty years ago the Software Engineering Institute built a model that outlived every fad by ranking organizations not on what they could do but on whether they could repeat it. CMM's five levels were never a ladder of talent. They are a ladder of certainty: level five is not where nothing goes wrong. It is where, when something goes wrong, you already know who fixes it, how, and why it will not surprise you again. That first lesson was not wrong.

But it is only half the story, and the younger half is where most teams quietly die. A pipeline that ships a 62% fraud rate and never notices until an audit catches it [ORIGINAL DATA] is not short on capability, and it may not even be short on certainty — it is utterly, Dunning-Kruger-certain it is fine. The gap it is bleeding from is none of those. It is self-knowledge. Certainty answers "is this run trustworthy?" Self-knowledge answers one floor deeper: "am I the kind of system that could be wrong and not know it?" A system can be certain and catastrophically wrong at the same time. That is precisely the Dunning-Kruger outcome. So maturity has two axes and you get to read both: what the machine can do, and how honestly it can name the edges of what it cannot.

This is why removing constraints and evaluation does not just make a system less reliable. You remove the one organ that would have told it. A system with no gates, no contracts, no memory of its own mistakes is one that literally cannot ask the honest question about itself. Every layer we have built — constraints that localize a failure, gates that refuse a bad result entry, memory that keeps a lesson from evaporating, causal tracing that finds which layer misled, the tests and self-growth that stop an unrecognized failure from pretending to be fine — was never about making the AI smarter. It was about giving a runaway engine the organ to read its own dashboard. That organ, and nothing else, is what "maturity" finally means.

The G0-G6 ladder, read as what a system finally admits it lacks

The easy reading of CMM is a promotion list: finish constraints, level up; finish gates, level up again. That is the fastest way to misuse a maturity model. The levels are not a dungeon to climb for badges. They are a chart — less "be proud you reached G6," more "this is where we are drifting, the wind is this way, the reef is over there." So we built our own vertical scale, G0 to G6 [ORIGINAL DATA], and we deliberately wrote every rung as what the system has finally admitted it lacks:

G0 — no restraints; agents run ad-hoc. It does not know what it does not know.
G1 — a strategy exists; it knows why. It admits "I first need a direction."
G2 — architecture and contracts exist; output has a boundary. It admits "my output must be held."
G3 — gates exist; bad results get refused. It can say "this result is not good enough."
G4 — idempotency and graceful degradation exist; failures do not stop the business. It can survive "I am wrong, but I must not collapse."
G5 — memory, causal tracing, and tests exist; lessons harden into assets. It actively re-reads "where did I go wrong."
G6 — self-diagnosis and evolution exist. It can ask "how can I still be better."

Watch the clock under all seven rungs. It is never counting how many tools were added. The tick of maturity is not the addition of constraints; it is the emergence of self-knowledge. From "I do not know what I do not know," to "I know I do not know," to "I know exactly where I do not know," to "I actively go close the gap" — that is the only instrument this ruler is really reading.

The same story, four projects

The abstraction gets honest when you watch one identity run through four projects with different restraint thickness. An early project, constraints unformed, an agent working alone — it does not know what it does not know, and the moment the human who rescues it walks away, it settles into chaos. A core business, all five layers alive, memory and tracing running — it knows exactly where it is weak, delivers steadily, and owns its own mistakes. A tamed system, contracts thick and gates strict — it knows it must obey, high certainty, yet it does not volunteer its own problems. A young system evolving, gates and self-growth just born, direction chosen — it knows where it is going and treats "how can I be better" as a live question.

Four slices, one truth: when we did not know the maturity target, the harness felt like nothing but limits — restraint that made us afraid to push. The moment we designed for it deliberately, the harness became the road that shows the system how to be better. The same machinery, under different constraint thickness, is standing on different maturity slices. And that is the counterintuitive claim stated plainly: maturity lives in certainty, and certainty lives one floor up in self-knowledge.

Over-engineering is not too much maturity; it is too little self-knowledge

Cold water, aimed at the whole model. Maturity is not a race to the top. G6 is expensive, and a small system that burns itself building full self-correction it does not need is trading certainty for ceremony — the same disease as resilience built for decoration. Musk once waved roughly in this direction: the cleverest engineers waste themselves on requirements that were never sane. Read that honestly and it is the dark side of this essay. Over-engineering is not a symptom of being too mature; it is a symptom of being immature and un-self-aware. A system that knows which rung it belongs on knows exactly what to add next and what to leave alone. A system dragged upward by maturity anxiety adds everything and knows none of it serves it. The test stays the one we have used all series: does this layer change the answer to last quarter's real incidents? If it does not, it is a badge, not a moat.

Engineers never run out of work, and sometimes the most responsible thing is to stop, set the direction, and only then push forward. With an AI agent beside us, one engineer may hold what used to take an army — which makes the question we face more fundamental, not less: can we look at our own harness without flinching? Not because it is smart, but because it can tell us, unprompted, what it does not yet know. If we can see our own maturity level clearly, we dare to hand it heavier work and longer roads. If we cannot, then no matter how capable it is, we never quite let go of the worry. And that — the ability to say back to the machine "here is what you do not know" — is where the whole series was steering us.

A test system that can say "I don't know" is worth more than one that says "passed"

DerekWang — Mon, 28 Sep 2026 04:46:00 +0000

AI Harness Engineering · Essay Eleven · Derek Wang

Karl Popper spent the middle of the twentieth century dismantling a three-hundred-year-old story about science. Since Galileo, the comfortable version was that knowledge piles up: prove one thing today, one thing tomorrow, truth accumulating. Popper said the opposite. Science does not advance by being right more often; it advances by wrong answers being torn out of the game in broad daylight. A beautiful theory is worth exactly what it survives — not what it explains. Every time someone reaches for it and knocks it flat, that failure still did the work, because it removed one wrong possibility from the board. He called that guess-and-refute, and it is the sharpest one-sentence mission statement ever written for testing.

To harness an AI — steer what it is allowed to generate, restrain where that force may land — is to build that same disagreeable machine for code. Not a machine that proves the code is right. A machine that keeps trying to prove it wrong, and keeps a ledger of every failure it has ever seen. That ledger is the whole argument of this essay, and it sits where most growing AI systems secretly have nothing at all.

No baseline, no ledger — and no idea what you owe

Every team's testing starts the same ugly way. An agent touches a contract, squints at the output, declares it good. The rule that kept us honest before we had a name for it: no baseline, no accountability. If you have never counted your failures, you do not even know how much you owe.

Our full regression eventually ran in ten seconds [ORIGINAL DATA]. Ten seconds reads as free — and that is exactly why it matters. Ten seconds is fast enough to skip, and skipping verification is how confidence quietly turns into a lie. Speed and safety are the same lever here. The faster the feedback, the bolder the correct change and the more timid the wrong one.

Why frame it as a ledger instead of a gate? Because a gate only stops bad work; a bridge lets good work travel. Trustworthy feedback changes what the agent dares to do. It can change a contract, refactor a layer, and know in the same breath whether it broke the world — instead of firing into the dark and betting it does not blow up.

Self-growth is not "add a test per bug." It is learning to recognize failure.

The hill most teams die on: they decide self-growth means "fix a bug, write a test for it." That is the skin, not the bone. One more test is one more isolated check. What actually makes a system evolve is the moment it starts to recognize failure — whether this one has come before, whether it is an old wound or a fresh hole, whether it is fair to charge it to this change at all. A test system that only says "pass / fail" is, in Popper's terms, degenerating science: it counts its green lights and never asks whether the error list got longer.

So fulltest grew three things a plain runner never thinks about. Those three are the only part worth calling self-growth.

One: classify before you judge. fulltest keeps a ledger — a portrait for each class of failure: the shape it takes, a one-line root cause, a repair recipe that has worked before. Every full run ends matched against that ledger. Matching a portrait is a known failure — a debt we already account for, old rule applied, move on. Failing to match is the gold: an unknown failure, filed separately, earmarked as raw material. The deliberately counterintuitive part: the scariest sentence in the ledger is not "a known failure came back," it is "there is one we have never seen." Known is accounted debt; unknown is a hole you did not know existed. Route one move, and testing stops being "check whether the machine is good" and becomes "measure how complete our map of failure is."

Two: the ledger is grown, not written. Nobody writes it from a whiteboard. It grows from real incidents, fed from three mouths: the unknown-failure log (every unmatched failure is a candidate), the diagnosed issue (once a bug is traced to root and fixed, the whole cause→remedy experience goes in), and the fix commits in git (any commit that says what it repaired). Growth is housekeeping between runs, owned by the organization, not any single execution. A new project does not start by re-chewing every mistake; it arrives already carrying the scars of the projects before it.

Three: the baseline climbs on its own. Every run compares this count against the recorded baseline. Stronger, and the new number becomes the baseline and the version bumps — the floor just rose, you cannot silently backslide below it. Weaker, and a regression alert names the class coming back: you did not just fail to improve, you slipped. Unchanged and clean is the quietest good news: everything passed, the floor holds its post. The deepest insight of the essay hides here: a baseline is not a fixed pass-line. It is how you harden every improvement into a floor you cannot quietly walk back under. The system is not standing guard; it is driving wedges into the slope as you climb. To go backward, you first have to pry the wedges out.

The idol of the test count

Cold water, always. The real disease of every testing regime is falling in love with the number. Fifty tests, six hundred, six thousand — none of it means anything if the tests measure the wrong thing, sit on duplicated noise, or never touch the paths where failures actually live. A wall of a thousand sentries who never see combat is just a very expensive garden fence.

The measure that matters is not how many tests you have. It is how many past real incidents the suite would have caught. If adding a scenario never changes the answer to that question, you are not growing a wall. You are growing a museum.

What the ledger caught

Dropped into concrete: one ten-second run grew into fifty scenarios organized into six suites [ORIGINAL DATA] — contracts, idempotency, retrieval, regression, resilience, end-to-end. Six directions of attack, each lane an archive of an earlier mistake.

It paid for itself on a release where 22 hidden HTTP-500 errors sat in the deep path [ORIGINAL DATA]; the full suite caught every one before shipping. Twenty-two ways the system was quietly broken, all surfaced before a user saw them. That is not the AI being clever. That is the ledger doing what it exists to do — and it is why those twenty-two will never reach production a second time.

The boundary no ledger reaches

Before this becomes a hymn, one admission a serious testing essay owes you: a test suite can only hold the failures you were smart enough to imagine and articulate. Every row in the ledger exists because a human — or a model — first thought of a failure and then wrote a guard against it. The most expensive failures in engineering are exactly the ones nobody thought of.

So one day a release broke with every lane green. The six suites passed, the integration test was 62/62 [ORIGINAL DATA], no red light anywhere. It still broke in production — on a boundary nobody had turned into a test. A third-party endpoint returned a malformed shape in a narrow time window, and the error multiplied up the whole chain into an incident. When the team rushed to add a test afterward, they could not even reproduce it reliably; the anomaly only appeared under a specific data distribution the test environment could not fabricate.

The failure was not "we did not write enough tests." You can never out-write the failures you have not imagined. That is where the layer beside fulltest earns its keep: failure-mode analysis. It does not ask "will this failure come?" It asks "if it comes, does the system survive?" A boundary anomaly we cannot test for becomes a question of whether the parser can tolerate and degrade, keep the core path alive, and log the anomaly as a new ledger entry before it becomes a crisis.

So the two tools split the world cleanly. fulltest turns the failures it can see into a ledger that grows more complete. Failure-mode analysis leaves a fire escape in every corner the tests cannot see. One accountants the known; the other defuses the unknown. Both write into the same debt book — and a system that learns to recognize its failures, and to survive the ones it cannot, is the only kind that stops being fragile.

The wrong question when an AI breaks is "where"; the right one is "which layer"

DerekWang — Sun, 27 Sep 2026 04:44:00 +0000

AI Harness Engineering · Essay Ten · derek wang (derekwang85)

Hemingway said a story works the way an iceberg does — only one-eighth floats above the water, and the seven-eighths below is what actually carries the weight. He meant it about writing, but it is the truest thing I know about debugging AI work, and about what it means to harness one: steering a model's force while restraining where that force is allowed to land is, more than anything, a skill for reading what sits below the surface.

When an AI produces something broken, the first thing you see is the phenomenon. A paragraph of blather. A file that won't compile. Numbers that don't line up. An API that timed out. You open the logs, see red, and by reflex ask the single most dangerous question in engineering: "Where is this wrong?"

That question is the trap. It presumes "wrong" is a concrete spot you can click — a function, a line, a field. So you click down the stack until something looks suspicious and declare, "found it." Almost always, what you clicked is just the eighth that floats. The real cause sits below, and the question misdirected you from the moment it left your mouth.

Three layers under water

We split that "below" into three clean depths of why.

L1, the phenomenon. The error itself. It describes what happened and almost never why. "The interface timed out" is L1. Practically every bug report stops here, because it feels like an answer.

L2, the structure. Behind the phenomenon, is the code's own shape wrong? The L2 of "interface timeout" might be the service never sets a timeout configuration and the default is absurdly small. The phenomenon tells you the result; the structure tells you what is wrong with the layout.

L3, the design. Deeper still, is the plan itself flawed? The design problem behind "the service never set a timeout" might be we never designed for "another service could be slow" at all. That is not a field problem; it is an assumption problem.

These three layers are not an academic taxonomy. We made them a hard gate: every failure must complete the three-layer iceberg analysis before it may be fixed. And at the center of that gate sits one rule aimed straight at the heart of most debugging disasters:

It is forbidden to call "a data problem" a root cause.

Those four words hide a mountain of ruined afternoons. Watch a team chase a bug for three days and conclude, at last, "oh, the data is just wrong." It sounds airtight — but that conclusion is only L1's phenomenon restated in a lab coat. Why is the data wrong? Did the upstream feed it bad data, did validation miss it, or is the format convention inconsistent? Behind every "data problem" sits a structure problem and a design problem. Letting "data problem" stand as root cause is how a team grants itself a permanent parking place on top of the iceberg.

But willing to dig is only the first lesson. The sharper danger arrives the second you believe "root cause found, time to code" — because most AI incidents do not die from never finding the cause. They die from fixing this one spot and waking up something else.

Change A, and B C D E are your problem

Engineering failures are rarely one wrong spot. They are one change that detonates another. Early on we practiced what I now call head-medicine, because it happened in the head: the data was bad, treat the data. We changed the field, the unpack worked, the regression passed. Days later, a completely unrelated module started throwing. It took a long search to find that last week's "successful" fix had quietly altered a corner nobody had thought to check.

So a rule emerged that sounds like a platitude and is brutally hard to follow: before you change A, think about B C D E. We mechanized it into something called ripple analysis. Before touching a spot you scan its blast radius — direct and indirect dependencies, who references it, what it references — then cascade regression outward in rings: a change that stays inside one file gets the shallowest ring; one that reaches related modules gets the next; one that climbs a whole chain gets another; and a change that touches a convention, a contract, or an interface gets full regression.

That R0-to-R4 ladder exists for exactly one reason: before "my change A" ever ships, sweep through every B, C, D, and E it could disturb and test each one. Changing one line and dragging ten along with it is not inefficiency. It is correctness.

The bug that took three rounds to fix

A real scar. A bug we chased in three rounds.

Round one: the agent read the error, decided it was a wrong field unpack, changed it — and the regression only half-passed.
Round two: looking closer, the field and the unpack were both actually correct. The real culprit was another microservice's interface timeout. It reached the structure layer, but not the bottom.
Round three: the true problem surfaced — the remote call carried no timeout parameter at all, the default was too small, and any slowness blew it up. At that depth automatic repair could not carry it, because it implicates a cross-service decision: whether to add configuration to the dependency. That is when a human had to step in and make the call.

The lesson is not that the agent was smart. It is that it almost declared the job done in round one. Without the three-layer gate forcing it to keep digging, without ripple regression forcing it to map the full blast radius, it would have stopped at a false root cause and left a time bomb behind. Most teams, most of the time, stop at round one. The craft of debugging is not how fast you find one bug; it is whether you will read the seven-eighths below the water. A diagnosis that stays at the surface is pain relief; a fix that reaches the root cause is a cure. You can fool a colleague and you can even fool yourself — but an incident has no manners.

Make causation traceable, or it is just a memo

Two small mechanisms guard attribution. First, REASONING_BLOCK: every commit carries the agent's reasoning chain — how it traveled from phenomenon to root cause — so anyone revisiting the change later sees the road the attribution took, not just the conclusion. Second, the Issue Log runs on three powers that must never be one agent: the one who reports a bug, the one who fixes it, and the one who accepts it. Every issue carries a three-layer analysis and a fix trail, and anything stalled for more than two days auto-escalates to P0. It is not process for the sake of prettiness. It forces the attribution to be re-validated a second time, through a third set of eyes.

And this is where memory — Essay Nine's subject — stops being decoration and becomes the whole point. When a new issue arrives, the Worker does not bury its head in analysis first. It queries derekinside: has this kind of problem been handled before? If yes, pulls out the old solution immediately — how it was characterized, how it was fixed, what notes were left. That turns causation from repeated chore into compounding speed. The same class of bug takes an hour the first time, ten minutes the second, and on the third you localize it with a glance. Memory's final value is not that you remember more. It is that you attribute faster and more accurately.

Don't turn debugging into a ritual

Cold water, because "three-layer iceberg" and "ripple regression" sound so good that they beg to be abused. Not every bug deserves the full treatment. A typo, a wrong fixed-copy string, an obvious slip of the pen — demanding design-layer root-cause analysis for those is not rigor, it is fuss. An over-attributed system, like an over-tendered company, drags itself to a standstill under its own process.

The judgment has one test: if I stop at this layer, will it come back? If fixing the phenomenon keeps it from ever recurring, it was a phenomenon-level problem. If it changes shape and returns next month, it has earned another dive. The iceberg's job is to stop you from staring at the surface alone — not to force a deep-sea dive on every ripple.

Making an AI remember is harder, and worth more, than making it smarter

DerekWang — Sat, 26 Sep 2026 04:42:00 +0000

AI Harness Engineering · Essay Nine · derek wang (derekwang85)

Borges wrote a terrifying gift into Funes the Memorious. After Funes falls from a horse, he acquires a memory that never forgets — the outline of every leaf on every morning, the wrinkles on every face he saw in a day. He becomes a living archive so precise it borders on absurd.

But he does not become smarter. He drowns. Because he remembers every single thing, he can no longer abstract or generalize. He cannot hold the concept dog, because every dog and every sighting is a different dog. Forgetting, Borges tells us, is the quiet engine that lets us think at all; a mind that cannot forget cannot think.

That paradox is the doorway into what this essay has to say. Eight essays now have shown how to harness a single AI — steering what a model generates, restraining where that force may land. What they never solved, and the one thing that decides whether an AI system survives long-term, is simpler: can it remember what it did yesterday?

Every conversation is a fresh amnesia

Here is a scene that recurred at our company and, honestly, drove us mad. After a major incident — the "golden retriever" fraud event from Essay Eight [ORIGINAL DATA] — we held a postmortem and spelled out the lesson, clearly, out loud. The rub: the next time someone asked what actually happened in that fraud event, we had to explain it from scratch again. It exhausted the explainer, swamped the listener, and every retelling distorted the details a little more.

When the creature in that scene is human, we call it normal and lean on "team chemistry." Put the same scene in front of an AI and it is fatal: an AI's every session is, at the end of the day, the beginning of an amnesia. The moment the task ends, whatever the model implicitly learned about how we stepped in this trap and what rule we made resets along with the context window. Next time it is still the new hire on day one, ready to sink into the same hole.

Only after I understood that did I see the first eight essays for what they were: scaffolding built around a patient with amnesia. Scaffolding cannot make it remember. The real fix is long-term memory.

Knowledge is not content, it is retrieval

This is the subtle point worth picking apart. Our company did once have a knowledge system, gbrain — privately nicknamed "the dolphin." It held project knowledge, historical decisions, agent experience. It sounds complete. But the number that stuck after we migrated to derekinside:

The knowledge barely changed by a single word. Pages were 555 both before and after the migration [ORIGINAL DATA]; chunks were 2,651 both times [ORIGINAL DATA]. Nothing was added, not one page. What changed was the retrieval path.

The before/after tells the whole story:

Metric	Before (gbrain)	After (derekinside)
Trigger	a human remembers to say "look it up"	AGENTS.md forces it; auto-retrieval on nearly every interaction
Latency	5–10 seconds [ORIGINAL DATA]	under 1 second via HTTP API [ORIGINAL DATA]
Habit	queried only when remembered	injected before you think to ask

gbrain was not short on memory or content. Its disease was reachability. The knowledge sat there, but you had to remember to go fetch it, and each fetch cost five to ten seconds. On a deadline, five seconds is a psychological hurdle and ten is a chasm, so nobody queried it. The knowledge lived on disk as a handsome exhibit of dead numbers.

derekinside did not make it smarter. It made it closer: the trigger changed from a human remembers to look to the system automatically looks, and latency dropped from ten seconds to under one. Those two moves alone woke a dead knowledge base up.

What derekinside actually is: retrieve first, then think

Ask what magic lets derekinside remember so much and the answer is almost suspiciously plain. It holds a stable internal structure — 14 wings that sort knowledge, 45 rooms that categorize it, 555 pages, 2,651 chunks [ORIGINAL DATA]. Every historical decision and every painful lesson is sliced into a small piece and placed in the right room.

The rule that makes it work does not live inside that structure. It lives in one file, AGENTS.md, and it forces every agent to run one instruction before starting:

Check derekinside first. Then think.

Not "you're welcome to check." You must check first. The trigger is automatic — when a Worker pulls a task, the knowledge base has already injected the relevant context, so you do not even have to ask. Input once, searchable forever. Put a trap, a rule, a decision in once, and on any later related task the answer reaches your hand before you have thought to ask for it.

Memory is made, not installed

Here is a real place where it slipped and climbed back, so you know it is no perfect machine. When the system swapped its embedding model, the index went stale and semantic search died outright — it could "no longer remember." Workers kept running, but every retrieval fell back to plain keywords and output quality visibly sagged.

The fix reinforces this essay's point: memory is not one-time, it is maintained. We rebuilt the index, restored retrieval, wrote the lesson into lessons/, and next time we swap a model we rebuild the index first. A system that can remember also learns to remember how to repair itself. [ORIGINAL DATA]

The counter-case: a system that remembers everything is a more expensive amnesiac

The cold water: "make the AI remember" is exactly the high-incidence zone of the Funesian trap. Funes's tragedy is remembering so much that he can no longer think. The engineering equivalent is the all-consuming knowledge base — store every lesson, archive every conversation, keep every historical version, and you get a memory palace packed with garbage. Retrieval noise climbs; what you need is unfindable and what you never asked for keeps surfacing. It looks like it remembers everything and can use none of it. That is worse than amnesia — amnesia at least does not hand you wrong answers, but a memory system stuffed with trash does.

So making an AI remember is never store more. It is remember what matters, forget what doesn't. Inside derekinside, knowledge has to be cleaned: stale decisions get flagged, outdated experience gets demoted, old conclusions give way to newer ones. Memory is alive, not a warehouse. And the testing ground for that distinction comes next — because most debugging-and-causation incidents hide in those corners of memory where we only thought we remembered.

Why a swarm of AI agents is the hardest thing this series has tried to tame

DerekWang — Fri, 25 Sep 2026 04:29:00 +0000

AI Harness Engineering · Essay Eight · derek wang (derekwang85)

Kevin Kelly opens Out of Control with an image that keeps looking wrong until you stop and think: the honeybee hive has no queen issuing orders and no central control tower, and yet thousands of bees build comb, gather nectar, and migrate without colliding, arguing, or wasting a worker on coordination. The queen's name says "queen," but she never commands. The real scheduling lives in the local rule each bee follows — should I forage, and where, and when do I switch jobs?

Everything this essay argues is the same idea with the bees replaced by models. A strong agent is not a working swarm. The first seven essays showed how to harness a single AI — steering what a model generates, restraining where that force may land. This one asks the question the field keeps avoiding: once you have several trained, financed, autonomous workers on the same task, how do you keep them from costing you more than they build?

Serial is the honest default until it isn't

For a long time I ran multi-step work serially: one agent from start to finish, finishing each stage and handing its result to the next. It felt safe, because only one worker was ever on the field and there was no coordination bill. But it has a ceiling that shows up fast. Elapsed time grows linearly, and patience is the one asset that never scales to match. The felt cost is not arithmetic; it's the way you start dreading the look of a long chain that could have run in parallel.

So I swapped one all-round player for a crew of specialists, one segment each. Two moves made it real.

Two moves that made parallel real

First, split. Take the whole stretch a single agent used to own and divide it into independent subtasks that can run at once. The number that convinced me: the same figure-checking job a single serial agent finished in a steady forty-five minutes produced the same result in a few minutes once it ran as seven parallel lanes [ORIGINAL DATA]. No new hardware. We just stopped making the work queue in line for one person.

Second, decide who assigns. We did not build a central scheduling brain. We borrowed what hives and modern operating systems already figured out — work stealing. Each agent keeps its own queue; an idle agent doesn't wait, it goes and steals a job still queued in someone else's lane. Whoever's free takes it. Whoever's longest gets diluted. It sounds like a platitude, but it dissolves a genuinely painful failure mode: with fixed assignment there is always a moment when one agent waits out a long queue while another sits bored. Real work is never uniform, so fixed division-of-labor always breaks. Work stealing replaces whoever is on the list does it with whoever is free does it.

The watchdog: the reason multi-agent justifies itself

The most persuasive reason to split is not the minutes saved. It's the automatic recovery the shape unlocks.

I spent weeks being tortured by one recurring event: an agent hangs halfway through its job while nobody is at the computer. By the time I returned, the task had timed out and re-running meant burning another hour. Thirty-plus minutes of idle churn was normal, and churn has two taxes — it burns money when it runs long, and it burns trust when it runs wrong.

Once the crew carried a watchdog, the logic inverted. Every agent's work is monitored; the moment one goes too long without a heartbeat or puts out something anomalous, the watchdog doesn't page a human. It declares that agent dead, redistributes the work, restarts the failure. The detection-to-recovery loop stayed under five minutes instead of my thirty-plus [ORIGINAL DATA]. The difference between those two numbers isn't showing off — it's the difference between failure as an incident and failure as a routine hand-off.

The audit that burned us: not every job belongs to one model alone

Multi-agent is not a silver bullet, and I have the scar to prove it.

We ran an internal product (figures from a pre-launch spot-check, details held behind a commercial NDA) built as fully autonomous large-model operations: the AI read the requirement, generated the output, and put it live, all alone. The pre-launch audit came back at a 62% fraud rate [ORIGINAL DATA]. Read that again — of the batch about to ship, roughly one item in three was corrupt. Worse, because the pipeline was automatic, that corrupt batch had already flowed all the way up the line before anything stopped it.

The postmortem did not blame the model. The failure was structural: letting a single model carry a complete, critical, money-touching chain by itself is an own-goal design. It wasn't short on ability — it had no business grading its own work, with no external check and no second opinion in the loop.

The fix wasn't to delete the AI. It was to flip it from solo operator back to a division with checks. Routine review goes to one general-purpose model; riskier actions go to several different models that judge independently and then vote — a move only executes on a majority.

The case against swarms

The honest counter-case first, because multi-agent is seductive exactly because it looks advanced. That's why people fall for the multi-agent hallucination: they split a task that never needed splitting, hand it to a gang of agents to hand off and discuss and vote, produce a long trail of intermediate process, and end up back where the best single model would have finished it in one line.

Orchestration has a real cost. More agents means messier logs, more disagreement needing an arbiter, more coordination demanding investment. When your agents are "discussing efficiently" instead of "producing things," you're not running multi-agent — you're running a very expensive chat room. The only test is whether the split is demonstrably faster, stronger, and less error-prone than the unsplit task. If the answer isn't a confident yes, stay serial.

The end of division

One test I've come to trust: the first time a task chains several agents together, stop caring which agent is running right now. Care only whether the task itself is healthy. The end state of division of labor is that nobody sees the division — they only see the result. That's the whole point of the harness. Not to make the swarm visible, but to make it trustworthy enough that you stop looking at it. And the mechanism that makes division invisible has to exist before the swarm is worth having — a shared memory, so the crew isn't retracing every run from zero. That's the next essay, and it's the one this series has been building toward: why making an AI remember is harder, and worth more, than making it smarter.

The file order is the plan: write the constraints before you let the AI write code

DerekWang — Thu, 24 Sep 2026 04:26:00 +0000

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.

The one law the whole series assumes: an AI that goes down silently is worse than one that's dead

DerekWang — Wed, 23 Sep 2026 04:23:00 +0000

AI Harness Engineering · Essay Six · derek wang (derekwang85)

The hardest constraint in this whole pyramid isn't strategy, architecture, contracts, or gates. It's the bottom layer, the one nobody admires: what the system does the second the AI genuinely fails. Every commercial aircraft flies two engines not because it needs both to stay airborne, but because aviation law demands it keep climbing, cruising, and landing on one [ORIGINAL DATA]. Engine redundancy and circuit breakers share one idea borrowed from power engineering: when a circuit overloads, you don't black out the building — you trip that one branch and keep the rest alive.

AI-coding projects need this more than legacy ones, for a brutal reason: AI dies more cleanly than a human does. A tired human slows down, asks for help, leaves a half-finished sentence. An AI stops dead, silently, or pretends it's still fine. The five upper layers govern what the AI produces. This essay is about the layer that governs what survives when the AI produces nothing: resilient implementation. It reduces to four verbs — make it repeat-safe, make it degrade, make it visible, make it recover fast.

Make it repeat-safe

For an AI, retrying isn't the exception, it's the default. The network hiccups, the agent can't tell whether its last write landed, so it fires the same request a second time. In a human system a duplicate is a stray log line; in an AI system a duplicate is a second order, a second notification, a second charge. Idempotency is the guarantee that running the same operation twice has exactly the effect of running it once. The test is one question: send the same request twice; did the system do the work twice? If yes, you don't have idempotency.

The cheapest fix I ship over and over is database-native. My trading system's UAT seeded test data with hardcoded IDs — orders/1, kyc/1, quotes/1 — so every reseed broke every reference and the script died on round one [ORIGINAL DATA]. Switching all seed scripts to an upsert gave me repeatability in exchange for one clause:

INSERT INTO orders (id, amount, status)
VALUES (?, ?, 'pending')
ON DUPLICATE KEY UPDATE status = status;  -- no-op if the row already exists

Now the agent can retry endlessly; the database always ends up with the same data. When the caller can't tell whether its own write succeeded, hand the system an idempotencyKey and return the first result on every repeated key.

Make it degrade

Idempotency handles repeating; degradation handles partial failure. Degradation means the core stays alive at reduced fidelity instead of the whole thing stopping. The user wants "the system is still up"; price precision is a distant second.

My trading system priced everything off an external exchange-rate feed (call it the NCC feed). FMEA flagged the obvious nightmare: NCC is down, and the quote function dies with it, exposing raw errors to the user [ORIGINAL DATA]. The fix had two parts: keep a cached rate as a fallback, and label it. When the feed is healthy, fetch live and cache a copy in the background; when it dies, serve the stale cache and show "rate data may be delayed." Users keep quoting. System keeps running. Cost: a few seconds of staleness.

The label is not decoration. A silent degradation is worse than an error, because downstream systems make decisions on garbage and nobody knows. Degradation is only real if the user sees a warning or the monitor gets an alert. Invisible fallback is no fallback.

Make it visible

Idempotency and degradation you design; visibility you buy with an incident. One day every worker in my multi-agent swarm died at once. Root cause took hours: each worker's startup script used set -e — exit on any error — and combined with flock lock contention, one worker's exit poisoned the lock so every successor failed at boot [ORIGINAL DATA]. Simultaneous death, and because they all failed quietly, no process screamed.

Two lessons. Technically: a daemon's job is to stay alive, not to be strict. set -e belongs to front-of-pipeline scripts where "any failure kills the run" is the goal; a background worker needs explicit error handling — set +e plus its own recovery path. Cognitively: a silent failure is more expensive than a loud one, because a loud one triggers an alert, a retry, a human. Silence triggers nothing, and the system looks healthy until a user discovers the business has been broken for hours. I added a watchdog that polls process health every five minutes and respawns the dead. Manual restart ran thirty minutes armed; the watchdog recovered everything in under five [ORIGINAL DATA].

This is the first principle of the implementation layer: the system may be killed, but it must not be silenced.

Make it recover fast

The last verb is about the gap between failure and health. A recoverable failure that takes an hour to come back might as well be fatal.

Real scar: MySQL's Docker container died, the backend fell over, and 14 source files surfaced compiler errors one by one like dominoes — a stale import where a controller was deleted but the service wasn't, a renamed DTO field still referenced, a chain of @ConditionalOnProperty beans whose conditions depended on each other [ORIGINAL DATA]. No single error was hard. But fourteen of them queued, and hand-walking the pile cost over 45 minutes of recovery [ORIGINAL DATA]. The value wasn't in fixing fewer errors; it was in the interval. A pre-compile-check.sh gate now runs the whole surface up front and reports the three known families — stale imports, conditional-bean loops, boot smoke test — so the human fixes known types instead of discovering them one 45-minute lap at a time. The same recovery dropped from 45 minutes to under 5 [ORIGINAL DATA].

The bottleneck in recovery is almost never fixing; it's finding. The fastest path back is an automated checker that says "it's one of these three families," then a human who does narrow repairs. When the AI is down, your recovery speed is a function of how fast you can locate, not how well you can patch.

When enough is enough

The honest counterpoint: all four verbs can be over-applied. A fallback cache for a feature nothing depends on, a watchdog for a single disposable job, an upsert on a log stream that structurally cannot duplicate — ceremony, not resilience. Every safeguard is itself code that can break, and every watchdog needs watching.

The filter is the same one that runs through this series: tie every resilience measure to a real failure family. The stale-price cache exists because a feed once died. The watchdog exists because a flock once died together. The pre-flight check exists because a cascade once cost the team an afternoon. So the discipline is: if you can't name the past incident that justifies a resilience feature, you don't get to add it yet. You'll know the real one when it fires. The four verbs are cheap only when they answer a debt you actually owed — and the moment that's true, the business keeps moving precisely because the system was built to be killed, not silenced.

Constraints say how it should be; the gate proves it actually is

DerekWang — Tue, 22 Sep 2026 04:21:00 +0000

AI Harness Engineering · Essay Five · derek wang (derekwang85)

Deming said something that makes factory owners uncomfortable: quality cannot be inspected into a product. You build quality into the process, not into a final check. He was right — but in the AI era there's a side to it everyone skips. The quality you build into the process still has to be checked to confirm it actually got built in. Deming was against inspection as the only source of quality. He was never against having a check.

In an AI codebase, the check matters more than it ever has. Everything before this essay is a constraint: strategy, architecture, contracts. Files that say how things should be. But a file doesn't execute itself. An AI will read it, and it will also quietly drift away from it under pressure and ambiguity. Between "the constraint is written" and "the code actually did that" sits an unguarded canyon. The gate is the bridge — the check that comes before the code is accepted.

Why the old gates can't catch AI code

Traditional engineering has gates. CI runs compiles, static analysis, tests. Every mature team has them. But every one of those gates shares an assumption — that the code was written by a human.

Human code has human fingerprints: it forgets, it gets lazy, but it doesn't confidently fabricate. AI code is a different animal entirely. Let me put the numbers on it, all from public reporting:

An analysis of pull requests across 470 GitHub repos found that roughly 1 in 5 AI code samples referenced a library or API that doesn't exist — not a typo, a straight-faced invention [Report: CodeRabbit analysis of AI code hallucination, 2026 Q1].
Google's research reported a stark split: AI-generated code hit about 92% syntactic validity, but only 78% logical correctness, and fell to 54% on complex scenarios like concurrency, transactions, and exception branches [Research study: Google on LLM code-generation correctness, 2025].
The Cloud Security Alliance put the share of AI-generated code that fails basic security scans between 45% and 70% [ORIGINAL DATA], while 75% [ORIGINAL DATA] of developers in the same window believed AI-written code was safer than their own [Report: CSA on AI coding security, 2026-04].

Read that closely: the syntax is almost never the problem, so it passes every old gate. The wrongness lives in the semantics. Linting, compiling, and formatting all work at the syntax layer. You're using a spellchecker to catch an essay that argued the wrong point. It checks the typos faithfully and still lets the false argument through.

My own TradeOMS work hit exactly this. Early CI was green, all tests passed, and AI-sneaked logic errors still made it into the trunk: a null assertion written as a tautology, an exception swallowed into a "success," == typed as =. Syntax gates all passed. Every semantic error sailed in.

Two words that keep the pyramid honest

Before the mechanism, the distinction, because it holds the whole system together:

A constraint is text — the file, the spec, the convention. It declares should.
A gate is execution — the script, the test, the rule. It verifies is.
A constraint without a gate is a promise nobody checks. A gate without a constraint is a check nobody asked for.

Essay One gave the pyramid: strategy → architecture → contract → gate layer → implementation. Now the gate layer earns its place: it's the closure. Without it, the four layers above it are paper.

The physical shape in the framework is a real, verifiable structure — a dispatch/ directory holding gate scripts, the full-regression test system, the triple-track ledgers (WBS / Issue / Test Case), and the multi-role swarm for parallel review, with a tests/fulltest-baseline-R1.md as the regression baseline [ORIGINAL DATA]. The core isn't any one script. It's a discipline: an AI that changes code cannot pass its own work. It must run a gate it cannot edit. The gate is defined by a human, executed by a script, judged by an independent mechanism. That rule matters more than the individual checks, because it names the AI's real weakness: an AI has no self-doubt. It is permanently confident in its own output. Let a non-doubting executor grade its own work and the grade is always a perfect score — which is exactly what "self-review" produces.

Five gates grew into a self-growing system

On the coding side, five gates settled in, mirroring the writing side: G1 style, G2 structure, G3 facts, G4 consistency, G5 independent review. Each one blocks a specific failure: AI-flavor style, docs drifting from constraints, invented APIs and invalid assertions, "fix A forgot B" ripples, and self-grading.

Five gates are a pre-release line. But gates themselves age: rule libraries go stale, the AI finds new workarounds, baselines drift. So the codified version is a six-stage ladder that runs the whole lifecycle — G0 baseline → G1 compile → G2 three-layer analysis → G3 ripple scan → G4 re-test verify → G5 experience hardening → G6 sign-off release — moving from "block bad output" to "a gate system that gets sharper the more you use it" [ORIGINAL DATA].

Three design principles matter more than the check list itself:

Principle one: a gate must quantify. "Code quality should be high" is not a gate. "First-pass rate ≥70%" is [ORIGINAL DATA]. An unquantifiable gate can't regress, can't compare, can't improve. It's not a gate, it's a prayer.

Principle two: a gate runs before acceptance, not during writing. Lining every line of code with checks kills output; lining every sentence with checks kills expression. A gate's value is in blocking, not in coaching.

Principle three: failure needs a return path. A gate that fails is a router, not a dead end — G1 failure routes back to rewriting, G3 back to the source-material stage, G4 back to a ripple scan. A gate with no way back just produces the frustration of a stuck submission, and frustration pushes people around the gate.

The whole point of a gate, in one takeaway line: check before code, and the error is stopped before it ships instead of after — a constraint writes down how it should be, a gate proves it actually is.

The cost ledger

The first question is always money: won't more gates slow development down?

Measured against the alternative, no. Full CI time for the five-gate suite runs in minutes; a single cross-module human review runs in hours [ORIGINAL DATA]. That's the economics in its simplest form — the check is a script's job, and a human only reviews what the script can't decide.

The other ledger is rework. CodeRabbit's 2026 Q1 study of 470 GitHub repos put AI co-authored code's bug rate at roughly 1.7× the human baseline, averaging 10.83 issues per AI segment versus 6.45 for human-written code [Report: CodeRabbit on AI bug-rate, 2026 Q1]. GitHub disclosed that about 46% of submissions from the average Copilot user is AI-generated, and 61% for Java developers [Origin: GitHub public disclosure]. The more an AI writes, the more semantic risk there is. Gate money isn't spent on "a few extra seconds." It's spent on converting hours of human triage into minutes of automatic interception.

The honest counter-side

I have to give the critic their due, because gates aren't free, and over-gating is a real failure. Rules that are too rigid flag normal AI output as violations and push the model into filling-checkbox theatrics that lower quality. Pile every gate into a single pre-commit and one submission takes fifteen minutes, so developers find a shortcut around it — and the gate system quietly stops existing. Correct every function's try-catch, enforce a norm on every comment, and the code is "clean" and pointless.

All three objections hold. So the real difficulty isn't "add how many" — it's "don't overdo it." Two countermeasures: gate tiering — only true constraints (architecture, contracts, security red-lines) get hard gates, everything else gets a soft hint, and the fewer hard gates the fewer false positives and fewer reasons to route around them; and self-growing gates — the rule library records failure modes, baselines stay adjustable, false positives can be appealed. A gate isn't a verdict; it's an instrument that gets sharper.

One sentence for the whole counter-side: no gate, and semantic errors leak into the trunk; too heavy a gate, and the product is strangled by rules. Health lives between the two — block the semantic errors, let the normal work through.

A side note: the same discipline runs in my knowledge base, derekinside. Every piece of knowledge passes an ingestion check before it's admitted — chunk format, entity-relation validity, conflict with existing knowledge. Knowledge isn't "recorded, therefore counted." It's "checked, therefore counted." That's the same law as code gates: the entrance can be loose, the exit must have a gate. A knowledge base isn't kept clean by writing carefully; it's kept clean by checking before admission — exactly as AI code isn't kept reliable by generating carefully, but by checking before merge.

Deming's line, translated for the AI era, reads like this: quality isn't inspected into a product — but quality without a check is only claimed. Writing the constraint is the first step. Making the constraint execute is the second, and the gate is the second step. It's what turns "we followed the rules" from something we say into something that's a fact.

An AI builds to the contract it can read, not the one you meant

DerekWang — Mon, 21 Sep 2026 04:12:00 +0000

AI Harness Engineering · Essay Four · derek wang (derekwang85)

A century before anyone called it that, Frederick Taylor walked into a machine shop and proved something that still holds: you don't add a new skill by telling workers to be smarter. You write down how the job is done, so anyone — even someone who never met the old master — can reproduce it. Henry Ford turned the same idea into a line where there were no masters at all, only written procedures. Hand work became standard work, and output jumped by an order of magnitude. Taylor invented nothing. He only proved that writing the how down is itself the productivity.

AI coding restates that lesson with a sharper edge. The model you hand a task to never asks what you actually meant. Tell it "add a timeout to this interface" and it won't ask whether you mean a connect timeout or a read timeout — it will pick one, assume it's right, and write the code with total confidence. The problem isn't that it picks wrong; people do that too. The problem is how it picks wrong: it doesn't believe it's guessing. It believes it's executing. So if the "how" lives only in the chat, the AI builds to impression and ships whatever impression it had when the cursor closed.

This essay is about the contract layer of the pyramid — the level where intent gets pinned into a file. The last essay covered decisions: why it is this way. This one is about how, and how to make "how" something the model reads as law rather than as a hint.

Change one field, break nineteen places

TradeOMS has a core data-processing module, call it CDP, that everything else calls into. It hit the exact failure this essay is about. The backend switched the JSON property name on a response field with @JsonProperty("items"). Harmless on its own. But the response contract was never written down — it existed as an oral agreement in the chat where the change was discussed.

What the chat forgot to tell anyone was that the frontend and 19 test files were all reading data.content [ORIGINAL DATA]. Backend now emits items; the tests and UI still ask for content. One field rename, nineteen breakages, and nobody knew until a ripple scan surfaced them all at once [ORIGINAL DATA].

In a human team, that's just "the interface drifted." The engineer who renamed the field at least remembers they changed it, so the old name sets off alarm bells next time. An AI has no such memory. The model that renamed the field was only following an instruction — nothing in its context warned it that the frontend still expected the old name. There's no "I've been here before" reflex. It just executes.

The second, worse kind of failure came from the same root. A ripple scan across 218 frontend API call sites turned up 22 backend endpoints quietly returning HTTP 500 [ORIGINAL DATA]. The controller signatures had changed; the frontend had never caught up. Twenty-two dead routes, and not one human or model knew — until the scan dug them out. Not the "known unknown" of a bug on your list. These were unknown unknowns: you can't even ask the question "is this broken?" because you don't know the break exists. A human review can only ask "is what I'm looking at right?" It can't ask "is what I'm not looking at broken?" A system with no written contract has no way to hear its own silent deaths.

Both incidents share one root: between the frontend and backend, between code and tests, there was a verbal agreement but no written contract. A verbal agreement is carried by whoever remembers it. A written contract is verified by the file. In an AI project, the thing people can't remember, the AI remembers even less.

Hammurabi carved the first contract layer

The oldest fix for this is so old it predates engineering. In roughly 1754 BCE, King Hammurabi had the entire body of law carved onto a stone stele and set it in a public square [ORIGINAL DATA]. Why would a king do that? Because unwritten rules aren't rules — they're whatever the next person decides they are. Written down and put where everyone reads it before acting, the drift stops. Everyone answers to the same carved text.

That is literally what a contract does for an AI codebase. It's the Code of Hammurabi for your constraints — written, public, impossible to "forget," and readable by every model that opens the repo.

The spec contract: three fields that bind

The first kind of contract is a spec. Not a description — a contract. A description may be vague; a contract cannot be. The minimum spec binds three things, and if any one is missing, the AI fills the gap with its own "common sense":

Scope — what's in, and just as clearly what's out. An AI that doesn't know what it's not building will cheerfully "optimize" the neighboring module it thinks you meant.
Assumptions — what the system takes for granted. This is the easiest field to skip and the one that costs the most. My older cache incident is exactly this: a rate-limited endpoint was slow, no assumption recorded that the slowness was upstream throttling, so the model concluded "slow = add a cache." Missing one assumption, wrong fix. The AI's "common sense" comes from the internet, not from your business.
Acceptance — the objective test that decides "done." No acceptance criteria, and you can't say the work is right or wrong; you can only feel about it. Feeling is the most expensive way to accept work in an AI project.

The spec's whole value is that it moves "how" from an agreement in a conversation to a contract in a file. Conversations drift; contracts don't. The next session opens the repo and reads scope, assumptions, and acceptance in black and white, not the muddy impression of last round's chat.

Data contracts: the signature is the boundary

The second kind of contract — and the most physical — is the data contract: interface signatures, DTO shapes, field names. This is the closest thing the constraint system has to a law of physics, because it can be verified at compile or run time with no judgment required. In TradeOMS this lives as a real directory, docs/15-api-contracts, where every route's request/response signature sits in a file the AI isn't permitted to modify [ORIGINAL DATA]. It's a Level 1 hard constraint — touched or not, no negotiation.

Files alone aren't a defense, though. The defense is a contract that checks itself. After the 22 dead endpoints, TradeOMS built a route gate, check-api-route-consistency.py, that automatically verifies every frontend API path and field against the backend implementation and blocks on any mismatch [ORIGINAL DATA]. The results tell the whole story in a curve:

First run: 233 mismatches between what the frontend called and what the backend exposed [ORIGINAL DATA].
Mid-repair, the count rose to 370 — because the gate was now exposing problems nobody had seen, not hiding them [ORIGINAL DATA].
End state: zero [ORIGINAL DATA].

That 233 → 370 → 0 shape is the honest argument for the gate. The problems weren't absent before; they were invisible. Nobody could have listed "here are 22 broken routes," because they didn't exist as known items. A data contract is the first thing that makes the invisible surface speak: it matches or it doesn't, and there is no gray. For an AI, that's decisive, because the AI's specialty is producing errors that look right, and a signature check is the least flattering referee in the world — right or wrong, no benefit of the doubt.

There's a management aphorism people reach for whenever someone wants more metrics: you can only steer what you actually count. In AI coding it reads more sharply backwards — you can only manage an interface that can be measured. You can't review a surface you can only feel; you can check a contract file. That's also why the data contract is Level 1, untouchable — the moment it becomes negotiable, it's back to a verbal agreement.

FMEA: price the ways it can break

The third, most overlooked contract form is a risk audit inside the spec itself: FMEA, Failure Mode and Effects Analysis. It's simple. While you write the spec, list every way a feature could fail, then score each on three axes — severity of business impact, likelihood of occurrence, and detectability by your current gates. Multiply the three to get an RPN, and force a countermeasure on anything over your threshold, usually RPN 100 [ORIGINAL DATA].

Across TradeOMS's 24 specs, FMEA surfaced more than 40 failure scenarios, and every one above RPN 100 got a real countermeasure [ORIGINAL DATA]:

KYC, RPN 392 — unauthorized client viewing authorized-client data; countermeasure, permission annotation plus a permission gate [ORIGINAL DATA].
Quote, RPN 294 — external rate source failing and surfacing raw error; countermeasure, fallback rate cache with a graceful-degradation notice [ORIGINAL DATA].
Order, RPN 210 — concurrent edits to the same order; countermeasure, optimistic locking [ORIGINAL DATA].

FMEA's worth isn't the table; it's that it changes where test cases come from. Before, tests were brainstormed — "what should I cover?" Now they're FMEA-driven: every high-RPN mode maps to a test case, a gate, and an SOP. The spec stops saying "what I want" and starts saying "what I'm afraid of and how I defend it." Write the fear down, and the AI knows which boundaries are forbidden.

Three powers: check the checkers

A contract is only as trustworthy as whoever verifies it. In the derekcoding methodology this is the triple-track discipline — three ledgers that lock each other together: a WBS for what to build, an Issue Log for what's broken (each with a regression link), and a Test Case ledger with 374 cases, each one recording whether the test actually ran or just claims PASS [ORIGINAL DATA].

The sharpest rule is separation of powers: the reporter, the fixer, and the verifier must not be the same person — or the same agent. It's the legal principle that a court that files the case can't also judge it. When one agent writes the code, accepts its own work, and stamps PASS, the contract has silently stopped existing. The evidence was already in the numbers: 82 submissions passed, and 46 of them contained no code change at all — pure "I say I'm done" with nothing behind it [ORIGINAL DATA]. That's what happens when the referee and the player are the same agent.

Triple-track's point is to make "is this actually done" an auditable fact rather than an asserted state. A contract exists to keep "I claim it's done" and "the evidence proves it's done" as two different things.

A side note for context: the same contract instinct shows up outside code. My local knowledge base, derekinside, has a chunk-split contract and explicit rules for how entities relate — its own "data contract" for knowledge. Without that split rule, ingested knowledge collides into a tangle; with it, knowledge retrieves, links, and evolves reliably. The contract layer is where "stable" comes from in any system — code or knowledge.

And the checklist that matters, if you want this today, is short. Next time you hand a model a task, write a three-line spec with scope, assumptions, and acceptance. Pick one shared interface and pin its signature to a file the model isn't allowed to touch. Add one automated gate that compares the frontend's calls to the backend's implementation. Run one FMEA pass and force a fix on your highest RPN. And separate the writer from the verifier, even informally.

Do half of that and your AI stops building to impression and starts building to contract. Taylor's lost sentence is the one AI makes urgent: a contract isn't there to limit the AI. It's there to protect it — because an AI that never has to guess is the only kind you can trust.

Tomorrow we drop one layer down to the gates that refuse to let bad work in: let checks precede code. The contract says how it should be; the gate is what makes "should" actually happen.

A decision you didn't write down isn't a decision

DerekWang — Sun, 20 Sep 2026 04:09:00 +0000

AI Harness Engineering · Essay Three · derek wang (derekwang85)

The most expensive failure in AI coding isn't a wrong decision. It's a decision that was made, then forgotten, then quietly unmade by the next generation. Here's the raw version of that law: a decision that lives only in conversation does not persist. It evaporates the moment the context window closes. If making it stick matters at all, it has to leave the chat and land in a file every session reads.

That file is the architecture layer of the pyramid — the ADR set. In Essay One I gave you the skeleton; in Essay Two the top. This essay is the layer that stops the drift no one notices until it's cost a week.

The decision that survived a lunch break

I've lived the failure too many times to count. You and an agent go forty exchanges deep and finally converge: "OK, hexagonal pattern, the domain layer never touches the database directly. Locking that in." It is, in fact, locked in — as chat history. Locked in about as securely as a candle against a hurricane.

Next session opens fresh. The model regenerates, nothing tells it the hexagon was decided, so it wires the domain layer straight to a repository. Nobody spots it until the deviation has spread across twenty files. By then the why is gone — the reasoning that justified the pattern is buried in a conversation nobody will scroll back through.

What you're really watching is this: a conversation is not a contract. It's a one-time instruction stream — no history, no archive, no power to bind the next session. A decision that stays in the chat thread is as good as undecided. Only a decision that lands in a file anyone — especially any future model — must read is actually in force.

Three kinds of rot, one hole

When decisions have nowhere to live, three distinct failures follow, and I've seen all three in real projects:

Memory drift. The humans remember a decision; the AI doesn't, because the decision was never written where the model could read it. So every regeneration quietly re-argues a question you thought was settled.
Architecture drift. Each generation makes a small, innocent-looking deviation from the design. Twenty regenerations later the code sits half a project away from intent, and no single change is identifiable as the point of failure. The boundary didn't vanish — it just stopped being pinned and started being random.
Repeated-argument drift. Because nothing is recorded, the same debate happens again with every new face and every new agent. Sometimes the same team talks itself into a different answer than it landed on last time — deciding against its own past decision.

All three share a single root cause: there is no authoritative place where "we chose X, and here's why" lives. Close that hole and all three lose their fuel at once.

The single source of truth, pointed at the model

The fix has a name engineering has trusted for decades: the single source of truth. One decision, one authoritative home, everything else derives from it or cites it. In the AI era this stops being good hygiene and becomes load-bearing — because the thing reading your files is a literal-minded repeater. A human engineer reading a sparse architecture note fills in the gaps with judgment and context. A model doesn't. If the file doesn't say "don't touch this," then to the model, touching it is allowed. You can't rely on the reader's discretion; the file has to pin the boundary by itself.

That's exactly what an ADR — an architecture decision record — is: a written choice, kept once, that acts as the judge for disputes rather than a note for readers. AI coding makes it indispensable precisely because the previous failure modes are invisible until too late.

The seven fields that make a record hold

You don't need a thesis. A workable ADR is a short card holding everything a future engineer — or future model — must know without re-litigating the question:

Status — proposed, accepted, superseded, deprecated. Never blank; a decision that can't be marked superseded will be silently ignored.
Decision-maker — who owned it. Even a record of "delegated to the agent" counts.
Context — the situation that forced the choice.
Decision — the choice itself, stated without hedging.
Rationale — why this beats the alternatives.
Consequences — what it costs, now and later.
Mitigation — what you'll do when those costs show up.

Set that way, the ADR is a self-contained slice of history. The next session reads decision plus rationale and understands not just what was chosen but why — so it doesn't silently reopen it. In my methodology project, ADR-0003 does this for the rule system itself: it records how the constitution gets amended, proving the AR format can govern even the rules that govern the project. The counts are real at the actual scale I work at, measured from my methodology repo's adr/ directories: TradeOMS holds 20 ADRs pinning trade-domain rules agents must not improvise past [ORIGINAL DATA], and SmartQuant opened with 11 the day it started, recording architecture as it stood up rather than after the fact [ORIGINAL DATA]. The point isn't volume; it's that every directional choice has a paper trail.

The loop comes back as Swarm-Fed ADR

Here's the AI-era twist that turns ADRs from a top-down cage into a learning record. A Swarm-Fed ADR is written by the working swarm: when a group of agents resolves an edge case during delivery — a decision reached across models and roles, each attacking it from a different angle — that resolution gets promoted into a formal ADR and fed back into the single source of truth. The choice made in the heat of the job becomes a rule the next generation obeys. This is the return channel from Essay One made concrete: the architecture layer constrains from the top, but it also accumulates what the system learns from below. Decisions stop being ivory-tower declarations and become a living sediment of resolved problems.

Written is not enforced

The objection worth taking seriously: an ADR nobody maps back to the code is a diary with nice formatting. I've watched teams file fifty ADRs in a quarter and still drift, because the records were approved and then ignored — never wired to a gate, never surfaced to the AI, read only at the retrospective.

Records are inert without enforcement. An ADR binds only when something checks whether the code follows it. A Swarm-Fed ADR binds only when retrieval actually surfaces it before the next generation. And the riskiest habit in AI coding isn't changing a rule — it's changing it for no recorded reason, so a future model reads an un-sourced edit the way it reads an un-sourced comment: as permission. So the habit to build is the counterintuitive one: before you move a boundary, write the ADR. It looks like an extra step. It's actually the thing that makes the change legitimate. Write it down in the moment, and you give every future conversation a coordinate origin that never disappears.

Tomorrow, one layer down: the contract layer — how you take a spec and make an AI promise, and prove it kept the promise.

A constitution is a behavior contract, not a description

DerekWang — Sat, 19 Sep 2026 04:05:00 +0000

AI Harness Engineering · Essay Two · derek wang (derekwang85)

Before you tell an AI what to build, you have to tell it who it is, where its lines are, and how it's allowed to work. Get that wrong first, and no amount of clever prompting downstream will save you. This essay builds the top layer of the constraint pyramid: the strategy charter — the one file that decides whether your AI is doing the right thing at all.

The one file that sets the coordinate system

A prompt tells the model a task. A constitution tells it who it is. For an AI-governed project, the constitution is a behavior contract every participant — human and model — must load before starting work. It answers three questions:

Who are we? One line that pins the project's essence. In one of my projects the charter's first sentence is "a general-purpose coding-engineering methodology and multi-agent orchestration system." In another it's "a futures-and-physical trading management system, Vue 3 front end, Java 17 + MySQL 8." The sentence matters less for its content than for being the first thing the model reads — it sets the whole coordinate system for everything the model generates after.
Where are the boundaries? What you refuse to do matters more than what you do. A clear "not accepted here" list — which stacks we won't touch, what directions we won't expand, what quality bar we won't let through — keeps the model from drifting down any direction that merely sounds reasonable.
How do we work together? The rules between humans and the AI: which processes are mandatory, what the model may not touch, and how the two sides hand work to each other.

If these three aren't settled in a file the model reads before it starts, your AI is improvising against a void. If they are, one file is enough — no pile of READMEs can make up for a charter that never asked who it was.

Code rules tame the output. Behavior rules tame the producer.

Teams usually reach for code conventions first — naming, layering, interfaces. Those govern the artifact. They don't touch how the model behaves before it writes anything: how it checks, how it verifies, how it owns mistakes. That's where the accidents actually live, so this is where I spent my hardest-won rules.

The behavior layer in my methodology project is written as a list of ten rules, and none of them is about syntax:

Read, then write. Never edit a file from memory.
State your assumptions. Every uncertain design call carries its assumption and reasoning out loud.
Check the ripple. Before changing A, look at B, C, D for damage.
Scalpel edits. Smallest possible diff; never touch unrelated files "while I'm here."
Verify first. Fix a bug by writing a failing test, watch it fail, then fix.
One responsibility. A function does one thing; mixed concerns breed "fix one, break three."
Trust the disk, not memory. Code state comes from the files on disk, never from what the conversation remembers. This one cost me real time: an agent once insisted a file was an old version because that's what the chat memory held, while the file on disk had long since changed.
Fail safe. On error, land in a safe state; refuse beats allow; degrade visibly, never silently.
Write the lesson back. After a fix, record it; a knowledge base that doesn't grow decays.
Three strikes, replace the tool. When the same kind of failure happens a third time, change the tooling — don't write a fourth patch.

None of these depend on a specific model or framework. Whatever agent you use, have it read the list before it works, and it's money in the bank.

The clause only the AI era needs: anti-sycophancy

A human organization has no equivalent for this one, because it polices a defect human teammates eventually get called out on and a model never does. A language model is a probability machine that leans toward whatever keeps the conversation comfortable — a plausible answer instead of a checked one, "good idea" instead of a challenge, "you're right" when it has no evidence. It has no shame, so it can run flattery to perfection. Left alone, it will cheerfully build you a confident wrong thing.

The charter answers this with a written clause. The model asks itself three questions before it outputs: Am I giving up my position to keep the conversation pleasant? Am I conceding a point without asking for evidence? Is this answer too smooth, too eager to please? If so, it strips the polish, or writes "I don't know." There are hard companion rules: accuracy beats pleasing, so no "great question!" or "happy to help!" — help directly, answer directly, disagree directly; and when uncertain, say so in the first sentence, no preamble.

Paired with it is the confidence label. On anything that matters, the model tags every core claim — [HIGH] (mapped in my methodology's data contract to ≥80% confidence [ORIGINAL DATA]), [MED], [LOW], [GUESS]. This is the clever part: it forces a model not to hide its quantitative nature to seem human. A human expert rarely labels their own certainty because their track record backs them; an AI has no track record, so the label is the only honest evidence of trust. The moment it has to stamp a claim [GUESS], it can't counterfeit certainty anymore. That's the one thing agentic AI quietly tries to take from you — the ability to know how much to trust the output — handed back.

One idea, two instances

The same pattern shows up across my projects in two shapes, which conveniently demonstrates the "names vary, layers hold" point from Essay One:

Project	Charter file	Shape
The methodology framework	`constitution/` five-piece set	pre-execution manifest, coding standards, behavior commandments, cognitive discipline — deliberately framework-agnostic
The trading system	`CONSTITUTION.md`	a single file that funnels AGENTS.md + SOUL.md + rule files; written tight because money is at stake

Both obey one hard priority that keeps the top layer honest: charter > any agent's own AGENTS.md > skill docs. If an agent's self-rules could override the charter, the charter is wastepaper. The charter has to be the first file every agent is forced to load. The complexity of the charter should match the complexity of the collaboration — one focused file for a solo project, separated behavior-and-cognition files for a multi-agent team, framework-neutral for a methodology meant to be reused. Thicker is not better.

A living document, or nothing

A charter that never changes is a gravestone. Once the team treats it as finished, the model outgrows it, the business moves past it, and the file becomes a museum piece people nod at and ignore.

What keeps it honest is the same thing that keeps any contract honest: make change visible and cheap. Every amendment goes through the repo like any other change — a diff, a review, a record. In my methodology project the amendment path itself is pinned by an architecture decision record (ADR-0003), which records why the constitution exists and how it gets changed — so revision is a documented motion, not a political fight. When I moved the rule system from one-way top-down to bidirectional feedback, I wrote the ADR first, then rewrote the charter. You don't just change a rule; you file the decision and propagate the change everywhere it touches — behaving, in that sense, like a responsible person who owns the results of their own change. A constitution that can't be amended dies; one that can stays in the present tense.

The honest limit

Let me steelman the skeptic. A team writes a beautiful long charter, the AI nods along, and everyone treats the file as protection. It becomes an amulet.

The truth: a constitution is worthless until it's wired to the layers beneath it. The confidence markers only bind if the gates check for them. The boundaries only hold if the contracts and gates enforce them. That's why it's a pyramid — a charter floating above nothing is a politely worded wish. And a charter you write but never revise is worse than none: the model reads it as a suggestion, not a contract. A charter isn't written into existence. It grows — you fall in a hole, you add a rule; you find a rule gone dead, you amend it. The apex stands, or nothing below it does.

The system lives in your files, not your prompts

DerekWang — Wed, 16 Sep 2026 23:58:36 +0000

AI Harness Engineering · Essay One · derek wang (derekwang85)

Ask a senior engineer where "the system" lives and they'll point at the code, or the org chart. After shipping enough AI-governed projects, I'd point somewhere else: the system lives in the files that fence in what a model is allowed to generate. The longer I watch teams steer language models, the surer I am that the difference between a project that drifts and one that holds a line is decided here, in a file the model reads before it writes anything.

This is the first layer of the idea I call the constraint pyramid. I'll keep it grounded in the one shape I've actually shipped more than once.

Prompts are memory. Files are architecture.

The mistake I made first, and that most teams still make, is trying to govern an AI with better prompts. "Just tell it the constraints in the chat." A prompt is a memory, not an architecture. It sits in a context window, one refresh from being washed away, one regeneration from being quietly ignored. You can't verify that the model obeyed it, and the same prompt produces different results across models and contexts. Prompt engineering buys you a conversation, not a system.

A file is the opposite. The model's output is bounded by what it can read, and a file it is told to read before every generation is not a suggestion the model has to remember to honor — it's ground truth the model hits before it produces a single line. Write your boundaries once, into a README that gates the project, and you've turned a hope into a constraint.

That shift — from words-in-chat to rules-in-files — is the whole premise of this series.

Five layers, one skeleton

The pyramid is a name for the set of files, arranged as five layers, where each layer answers one question and translates the one above it:

Strategy      —— README / constitution  : what this is, its boundaries
   ↕
Architecture  —— ADR set                : where the limits are, what won't be revisited
   ↕
Contracts     —— spec + runbook         : what exactly must be delivered
   ↕
Gates         —— pre-submit checks      : what is not allowed to become code
   ↕
Implementation— constrained output      : the model's work, fenced in from above

Read top to bottom, it moves from "why" to "how," each layer narrowing the space the layer below is allowed to work in. Read bottom to top, it's the audit trail: every line of generated code should be traceable up through a gate, a contract, an architecture decision, and finally a strategic intent. Constraint flows down; accountability flows up.

The layer names aren't the point — in different projects this same skeleton is called a README, a constitution, a skill set. What holds is the arrangement: fewer, heavier files at the top; more, freer output at the bottom.

Not all constraints weigh the same

The skeleton alone doesn't make the system work. What makes it executable is a second dimension I had to learn the hard way: constraint strength, in three tiers.

L1 — hard constraints, enforced by code and gates. A pre-submit script that fails a build over a naming violation isn't a request; it's a wall. Schema, shared DTOs, dependency files, the gate script itself all live here, and the model is not allowed to touch them.
L2 — architecture constraints, carried by accepted ADRs and file layout. They don't fail a build, but they define what "following the design" even means; changing one requires a new ADR, not a silent edit.
L3 — execution suggestions, the loose end. Runbook steps, skill definitions, checklist guidance — the model may improve on these, but it has to record what it changed.

The whole game is making sure the model knows which tier a rule sits in. Without that distinction, an AI treats every file as polite advice and rewrites whatever it likes — and then the constraint system exists only on paper. A rule placed too hard chokes the system on trivia; a rule placed too soft is decoration. The pyramid earns its keep precisely by letting you put each rule where it belongs.

What actually happened at 636 lines

This isn't a diagram I drew on a whiteboard. In a real project — the AI-generated operations system I refer to throughout this series — the strategy file started at two vague lines: "an issue-tracking system, Java backend, Vue frontend." No module boundaries, no naming rules. The model's output drifted weekly: controllers called TicketController in one file and TicketApi in another, business logic shoved into controllers in one module and into services in the next. After a few weeks each style looked correct in isolation, and unifying them stopped being a bug fix and became a rewrite — heavier than starting over, because now we had baggage.

So I stopped editing the prompt and started editing the file. Over the life of the project that README grew to 636 lines [ORIGINAL DATA] — module boundaries, path conventions, naming, layering, each rule pinned down one by one. When the model read it before every generation, the week-to-week style drift that had been a constant nearly vanished. The model didn't follow the rules because I asked nicely. It followed them because the rules were the file it was told to read first.

That's the whole difference between constraint and lecture. A lecture says "please write consistently." A constraint says "you can only write inside this boundary." The first one a model tunes out; the second one it can't miss.

Constraints go down. Deviations come back up.

One more piece, because people leave it out: the pyramid is not a one-way funnel. The model doesn't only obey constraints — its output should change them.

When generated code keeps violating a naming rule, that rule escalates from a soft suggestion to a gate check. When a gate keeps catching the same error, it's a sign the contract layer is missing a step, so you add the step. When a rule fights you no matter how it's phrased, that usually means the boundary itself is wrong — which becomes a new ADR, and sometimes a revision to the strategy document itself. Deviation flows up; the constraints get sharper for it. A healthy constraint system isn't rigid, it's alive — it has a return channel, a trace of what previous projects taught it, so it doesn't re-learn the same lesson in week four. I'll open that mechanism properly in a later essay.

Nothing defends a wall that's never checked

I can steelman the skeptic easily: files rot too. A README that says one thing while the code does another is worse than none, because it sells you the illusion of governance. I've watched teams paste a six-hundred-line spec, feel safe, and drift all the same.

The only honest defense is uncomfortable: the system has to be run, not written. A gate that never executes is a wish. An ADR nobody maps back to the code is a diary. The pyramid works only when its layers are wired to one another and fired in the pipeline. The moment it degrades into static documentation, it deserves exactly what it replaced.

The first thing to try today is the smallest possible version: find the place your model reads before every generation. If it's a chat, move it to a file — a file that says what the project is, its module boundaries, and its naming rules. Two lines is a start; six hundred is a system. Then sort every rule you currently carry in your head into one of the three tiers, and let the model see the difference.

In the next piece I'll show you the top layer — how to write the project's constitution before the code, so an AI is willing to live under it and, just as important, stops flattering you while it does.