I write to my machines in Simplified Technical English

An instruction that can be read two ways will eventually be read the wrong way — by a person under pressure, or by a model doing its best to infer intent. Natural English is gloriously ambiguous: it's full of idioms, implied context, sentences that mean different things depending on emphasis. That's wonderful for a novel and dangerous for a directive. When I write an instruction the machine is going to act on, every place I left room for interpretation is a place it might interpret differently than I meant, at which point the failure is mine, not the machine's.

The controlled-language discipline is a systematic way of closing those gaps. Active voice, so it's always clear who does what. Short sentences, one idea each, so there's no tangled clause where the meaning can hide. The same word for the same concept every time, so the reader never has to wonder whether two different words mean two different things. None of it is elegant. All of it removes places where a misread can start. An agent won't stop and ask me what I meant the way a colleague would; it will act on the most probable reading and hand me the result, so the burden of being unambiguous sits entirely on the words I chose.

Write the instruction so it can only be read one way. The elegance you give up is exactly the ambiguity you were about to be misunderstood by.

The constraints are specific and each one closes a specific hole. Use the simple tenses — present, past, future — because the exotic ones invite confusion about sequence and condition. Keep every sentence to twenty words or fewer, because a long sentence is where a qualifier gets attached to the wrong thing. One idea per sentence, so nothing rides along unnoticed. Keep paragraphs to six sentences or fewer, so a directive never becomes a wall the reader has to hold in their head at once. No idioms or slang, because those are precisely the phrases whose meaning isn't in the words.

The rule I lean on hardest is the boring one: the same word for the same concept, every time. Natural writing rewards variety — you reach for a synonym so the prose doesn't repeat itself. A directive punishes it, because the moment I write 'deploy' in one line and 'ship' in the next, the reader has to decide whether I mean two different operations. Consistency does the work that context would otherwise have to do. It is the same discipline that keeps a naming scheme from rotting the day it stops being obvious to the person reading it.

There's one carve-out that matters more than any of the rules, and it runs the other way: the controlled style governs the prose, never the payload. File paths, function names, column names, numbers, prices — those stay exact and untouched. When I wrote the rule down it even names its own examples: workers/updatePricing.php does not get 'simplified' into something friendlier, and $4,855 does not get rounded to 'about five thousand.' The plain sentence is the wrapper; the exact identifier is the thing being wrapped, and simplifying the wrapper must never dent the contents.

That line matters most where a single character is load-bearing. My Buildkite deploy learned this the expensive way: a literal value in .buildkite/pipeline.yml is not a phrase you can paraphrase, because the pipeline empties $VAR at upload time and a 'clearer' rewrite silently ships nothing. Every command I let near production carries the same split — plain sentences around exact strings, and not one character of the exact string touched. Simplify how you say it; never simplify what you're pointing at.

None of this works as a thing I remember to do. If clear instruction depended on my discipline in the moment, it would fail exactly when I'm tired — the way vigilance always fails right when it's needed. So the rule doesn't live in my head or get retyped into each prompt; it lives in one file, my global operating instructions, and that file is imported into every agent thread I open, in every repo. I wrote the controlled-language discipline down once, as standing doctrine, and every agent that spins up inherits it without my typing it again.

Writing it down once also makes it correctable in one place. When a specific repo needs a local exception, that repo's own instructions override the global rule cleanly, without my having to hold the carve-out in my head mid-task. The discipline stops being a mood I have to be in and becomes part of the substrate the agents read before they act. That is the whole move: take the thing you'd otherwise have to stay careful about, and build it into what the machine reads by default, so the careful part happens whether or not I'm paying attention.

The surprise was the effect on me. When you force yourself to write an instruction in short active sentences with one idea apiece, you can't hide fuzzy thinking behind a nice long sentence anymore. Vague instructions tend to be vaguely thought; the flabby prose is a symptom, not the disease. Stripping the language down exposes the places where I didn't actually know what I wanted, because there's nowhere left for the not-knowing to hide. The constraint made me a better thinker by refusing to let me sound smart while being unclear.

So the discipline pays off twice. The machine gets an instruction it can't misinterpret, which is the point. And I get forced to actually decide what I mean before I write it down, which turns out to be at least as valuable. Clear writing and clear thinking are the same skill, and controlled language is a jig that keeps both of them honest. Deciding what I actually mean before I commit it to words is the same reflex I lean on before I build anything — the plan is just the instruction written plainly enough to argue with.

The failure mode to avoid is confusing plain with padded. Controlled language is not permission to write more; it's a mandate to write less, and more directly. The goal is terse — say the thing, in the fewest short sentences that leave no room for a wrong reading, and stop. A wall of simple sentences that goes on forever isn't clarity, it's a different kind of noise. Plain and short, not plain and long.

Borrowing a discipline from aircraft manuals to talk to software sounds like an affectation until you've watched an ambiguous instruction quietly produce the wrong result at scale. The aerospace people learned this the hard way, in a domain where being misread is catastrophic. Instructing autonomous systems is heading toward the same standard for the same reason: when the reader acts on your words without stopping to check what you really meant, the words had better mean exactly one thing. Writing to be unmisreadable is a safety practice wearing the costume of a style choice. It belongs in the same family as the human gate I leave in front of the irreversible step — a small deliberate friction whose whole job is to stop a fast, confident mistake before it lands.

This piece is part of my series on running a fleet of autonomous agents. Start with One operator, a fleet of agents.