Instructions Are Not Architecture

01 · Instructions Grow, Never Shrink

Every agent system accumulates rules the way old companies accumulate meetings.

Something breaks at three in the morning. You understand it, you fix it, and you write a paragraph so it never happens again. The next exception adds a caveat. The one after that adds a warning. None of it is wrong, and all of it lands in the same place: the instruction file the agents read before every task.

Months in, that file is a sediment of every incident the system ever survived. Agents spend a third of their context reading rules, some of which contradict each other, some of which describe an architecture that no longer exists, all of which depend on a worker remembering to apply them at the right moment. The pile only grows, because adding a line feels safe and cutting one feels reckless.

That instinct is the bug. Growth-by-default is how a rulebook becomes something no one can hold and nothing can enforce.

02 · The Question Is Placement, Not Phrasing

The mistake is treating the instruction as the architecture.

When the rulebook gets unwieldy, the reflex is to rewrite it. Clearer wording, better headings, tighter sections. That is editing, and a well-edited pile is still a pile.

The real move is to stop asking how to phrase a rule and start asking where it belongs. For every line, the question is not "how do I say this better," it is "where does this have to live so the system can rely on it." Once that is the question, the instruction file stops being the destination and becomes one option among many, usually not the best one.

03 · Trash Is a Valid Answer

Most of what accumulates was never load-bearing.

Go line by line and the largest category is not "keep." It is "gone." Rules for an architecture that was replaced. Caveats for a bug fixed at the root. Aspirational sentences nobody ever enforced. The same warning copied into six files. A note that made sense the week it was written and has been lying ever since.

Deleting these is not data loss. Git holds anything you genuinely need back, and keeping a stale rule is not free. A wrong instruction is worse than a missing one, because a worker will follow it. Retention-by-default treats every line as sacred. It isn't. Most of it is residue, and the discipline is to cut it without ceremony.

04 · Runtime Is a Valid Answer

The right home for a safety rule is usually not a sentence.

This is the one people resist, because it means admitting the instruction was never the right tool. If a rule matters for safety, prose is the weakest possible place to keep it. Prose doesn't enforce. It hopes the worker reads it, remembers it, and applies it correctly under pressure, every single time. When the docs say a check is required but nothing actually requires it, the broken thing merges anyway, and the rule may as well not exist.

A rule that matters should usually stop being a sentence and become something the system cannot ignore: a gate that refuses the merge, a schema that makes the bad state unrepresentable, a CI check that fails the build, branch protection that won't take the push, a reconciler that corrects the drift, a signature the producer has to emit before the step counts as done. Each of those holds whether or not anyone remembers it. The prose only ever asked nicely.

These are the two registers I named in The Doctrine Bifurcation: compiled doctrine, which the machinery enforces, and interpretive doctrine, which a human or agent has to read and apply. Placement is mostly the question of which register a rule belongs in, and the bias should run toward compiled, because an enforced rule is worth more than a remembered one.

05 · The Placement Ladder

One pass, top to bottom, for every line.

The procedure is a single ordered question. Take the rule and walk down until it stops.

The ordering is the argument. Machinery first, because an enforced rule outranks a remembered one. Prose last, and only the prose that genuinely needs a human to read it: the universal map every agent needs, the local truth one repo owns, the procedure one role runs. Everything that can move down to machinery should, and everything that can't justify a seat gets cut.

06 · The Same Rule Can Live Twice

Teaching and enforcing are different jobs.

Compiling a rule into the runtime doesn't always mean deleting the sentence. The strongest rules live in two places at once, doing two different jobs.

Take a real one: a redeploy is not verified until a real instance phones home and proves the new code is actually running. That belongs in the instruction file as one short sentence, so an agent reading the map understands the invariant and why it exists. And it belongs in the promotion gate as a compiled check that refuses to mark the deploy verified until the phone-home signature lands. The sentence teaches the rule. The gate enforces it. Once the gate exists, the sentence can shrink to a pointer, because it is no longer the only thing standing between the system and the failure.

07 · The Layer You Can't See

A rule you can't review from the workspace isn't doctrine. It's drift.

Everything so far assumes you can see the rule. Placement only works because the line is somewhere you can read it, move it, or cut it. But there is a layer above the workspace that breaks the assumption: the home-folder instruction file, the provider's memory directory, the runtime's auto-injected context, the model's own remembered notes. None of it is in the repo. All of it can change what the agent does.

That is not a kind of doctrine. It is the absence of doctrine wearing doctrine's clothes. When an agent behaves differently because of a file no one committed and no one reviewed, the run is no longer reproducible from the workspace. Same prompt, same repo, different machine, different behavior, for a reason nobody can point to. A hidden rule that changes behavior is corruption even when its content happens to be correct, because correctness you can't audit is indistinguishable from luck. The model's own memory is the same problem with a friendlier name: a mutable store it writes to itself and reads back later is an unversioned input to every future run.

So this layer doesn't get placed as doctrine, but it has one legitimate job, and it isn't carrying rules. It carries environment: where the seat is standing and what it therefore cannot assume. "You are on the dev VM, not the running daemon." "A file you can read is not a system that is running." That is boundary, and it keeps a seat from mistaking its own vantage for the system's truth. What this layer must never carry is hidden doctrine, a rule no one committed and no one can review. Point at the tracked source, tell the seat where it stands, and carry not one rule of its own. Anything more, and you've hidden the constitution somewhere no one can read it.

These are the layers an agent reads before it acts, and the whole discipline is never to let one speak for another:

The environment layer is the strangest of the six, because the layer that warns "a file you can read is not a system that is running" is itself a file you can read. It earns trust only by matching what is observable, never by asserting it: a boundary that claims you are in production while the shell says otherwise is just one more unverified file. Declare the seat first, every task, then hold every other layer to what that seat can actually prove.

The test is one question. Can the system reproduce its behavior from tracked files alone, with hidden memory off? Every gap in that answer is an unversioned input you didn't know you depended on.