Throughliner is a Claude Code plugin that gives no-code developers a structured way to build things with an AI. The hardest part of building it was not the code. It was writing rules the model would actually follow. Two approaches failed before one worked, and the one that worked was borrowed from legislative drafting - a form the legal profession worked out a long time ago and left lying around. I just noticed it applied to machines.
None of this is specific to my plugin, Throughliner, or to Claude. If you are writing instructions a model has to follow — a system prompt, a rules file, an agent's standing orders — the conventions transfer directly, because they were never about AI in the first place.
1. Prose: more words, less obedience
Every rule got its reasoning attached — and not on a hunch. Research on the model I was running at the time, Opus 4.8, showed it followed a rule more reliably when the reason for it travelled alongside. So the reasons went in, and for that model it worked. The models that followed — the 5-series — turned out to want the opposite: less prescription, not more, which is what made it possible to take the reasons back out.
The result was a document nobody could hold in their head, the machine included. Not only that but there was no system maintaining it, so rules contradicted each other and behaviour drifted.
The reasoning attached to every rule was not free. It was the thing crowding out the rules, themselves.
Three things were going wrong at once:
- A rule with its justification attached is longer — three or four times the length of the instruction inside it.
- A model follows fewer of its instructions reliably as they lengthen. Attention is finite. Every sentence competes.
- Near-identical rules degrade one another. Two rules saying almost the same thing in slightly different words are perfect distractors: the model has to decide which one applies, and it can pick wrong.
2. Pseudocode: precise about the wrong things
The opposite approach — rules shaped like code, with conditions and branches — is shorter, and brittle. Pseudocode is good at cases you have already thought of and silent about everything else. Real sessions are made almost entirely of cases you haven't thought of, and a model that meets one has nothing to reason from. Prose degrades gracefully. Pseudocode stops.
There is a subtler problem. An if assumes you can tell whether its condition holds at the moment you check it. That's fine for "is the file there". It is not fine for what these rules actually turn on: whether a change is significant, whether this is a moment to ask a person. Those are judgements, and writing them as branches doesn't remove the judgement. It hides it. The branch form looks mechanical, so the reader stops weighing and starts matching — the wrong move on a condition that was a judgement call all along. Legal drafting keeps the judgement in plain sight: "where the change is significant" sits in the open as a standard the reader knows they have to apply.
3. The form that already existed
Legislative drafting answers the same question: how do you write a rule that a stranger will apply correctly, without you there to explain it, in circumstances you didn't foresee? Its conventions are specific, and each one transferred. One constraint runs through all of them: these documents are read by a machine almost every time, but they still have to be legible to a human.
State the action, not the prohibition
The biggest single change. A rule written as "don't do X" has never stated what to do instead. The model has to infer it, and inference is where behaviour goes strange.
| Before | After |
|---|---|
| Do not open QUEUE.md | Leave QUEUE.md closed |
| never auto-send | every send waits for approval |
| a build never writes product truth | product truth is written at planning time, before any build starts |
The first two are inversions: the action was already sitting inside the negative, and turning it round costs nothing. That is the common case. Most of my rules had the shape "do X, never Y", where X already states the action and the negative tail is decoration.
The third is the kind that changes behaviour. "A build never writes product truth" says where something must not happen and nothing about where it does. The replacement names the moment — planning, before any build starts — a fact the prohibition never contained. So the tell for a rule worth rewriting isn't that it's phrased negatively. It's that the positive version carries information the negative one couldn't.
Models tend to disambiguate by adding a negative, probably because it reads clearer to a human. To the machine, the negative half is a second statement of the same rule, competing for attention with the first.
Main clause first, conditions after
"Where the queue is empty and no work is cleared, ask the user what to do" buries the instruction behind two conditions the reader must hold in mind before learning what they're for. Put the action first. The conditions still bind; they just stop obstructing.
I can't show this one moved model behaviour. It makes the rules easier on the human eye, and that is reason enough.
Carry qualifications in structure, not explanation
Subject to, except that, unless, so long as — short connectives that attach a qualification without arguing for it. Most of my sentences of explanation were doing the job of a two-word connective.
One idea per provision
Put two instructions in one sentence and the model does the first and drops the second — not every time, but often enough to matter.
One rule said to write a research finding to a file and add a line for it to the index. The findings got written. The index lines mostly didn't, leaving a folder of notes no later session could find: a write path with no read path. Split into two provisions, each visibly done or not done, the problem went away.
The reasons go in the notes, not the statute
A statute never explains itself. The operative text says what to do; why it says so lives in a separate document — the explanatory notes, the debate, the committee report — that a reader opens only when they need it. The two are kept apart on purpose, because a reason inside a rule is text the reader has to get past before reaching the instruction, and text a later drafter can mistake for part of the rule.
That is the convention section 1 was breaking. Every rule carried its own explanatory note inline. The fix was to move each one out — into the session record, where the decision that made the rule is already written down — and leave the rule bare. A test for which sentences go: delete the sentence and read what remains. If what remains is still a complete instruction, the sentence was a reason and it moves. If what remains would be applied wrongly, it was part of the rule and it stays, rewritten as an instruction.
4. What the numbers said
The law-prose pass made nothing shorter. The rules file every session reads came out about 400 words longer than it went in. Turning a prohibition into the action it requires costs a few words each time, and so does moving a qualification into structure. A script that counts rule statements agreed: 299 before, 299 after. The pass changed how the rules were written, not how many there were.
The cut came from the principle underneath: reasoning does not live inside the rule. Four days later, across thirteen procedure documents, every piece of decision history — why a rule was worded this way, which alternative lost, what it had been tried as before — moved out of the operative text and into the session record.
| Figure | What it counts |
|---|---|
| 56,700 → 50,600 words | the whole procedure docset, before and after that pass |
| 528 lines | decision history removed |
| 0 | rules lost |
Eleven percent of everything a session might read, gone in an afternoon, with no instruction lost. That is not a style result. It is what happens when a rule is allowed to be only a rule.
The number I'd rather not report: the docset is a third bigger today than it was the week of that cut. The rules are still written to the standard above. There are simply more of them. Length is governed at the door, one rule at a time, and every rule admitted costs the ones already there. The writing standard makes each rule cheaper. It doesn't make there be fewer.
5. The door
Section 3 is how to write a rule the model will follow. It says nothing about whether the rule should exist. That turned out to be the larger half, and I only saw it properly after the numbers above: a corpus a third bigger than the week of the cut, every rule in it written to standard. Something other than the writing has to decide how many rules there are.
Legislation has this too. A bill doesn't reach the statute book because somebody thought of it. It passes through a process that asks whether it is needed, what it amends, and what it repeals. I borrowed four parts of that process, and together they are the discipline the first half of this article was missing.
Admission: name the parent first
Before writing a rule, say which existing rule it amends. An amendment competes with nothing — it sits under its parent, and the reader meets it there. A freestanding rule competes with everything already in the file. Most proposals that arrive as new rules are refinements whose parent was never looked for, so the first question is "what does this amend?", and looking for the answer is where half of them dissolve into a clause on something that already exists.
Then four questions, and a rule that fails the first stops there:
- Has this actually failed, in a way you can point to? A rule written against a failure you imagine costs the same attention as one written against a failure you saw.
- Does the model already do it unprompted? Then the rule taxes attention for behaviour you already have.
- Does it apply to every session, or only some? A rule that fires in one situation and is read in all of them is noise most of the time.
- Could a mechanism do it instead, at no attention cost? A script that refuses a bad write catches every case and is read by nobody. A rule about the same thing catches most cases and is read every time.
Eviction: name what comes out
Adding a rule names which rule it replaces, and repeals it in the same move. This is the one I got wrong most often, and how I got it wrong is the point: I would write a clearer version of a rule and leave the old one standing, because deleting felt riskier than adding. The result is a corpus where everything is said twice, in two wordings — the near-identical-rules problem from section 1, manufactured by the person trying to fix it. A restatement that leaves the original in place has doubled the text, not merged it.
Distribution: always loaded, or fetched
Not every rule has to be in front of the model all the time. The test is whether the model could know to go looking for it. A rule that must shape behaviour unprompted — how to speak to the user, what to do when something is noticed mid-task — cannot be fetched, because a session cannot fetch a rule it has never read. It pays the full attention cost, always. Reference material with a trigger the model can't miss — a word the user says, a step that says "now open this" — can live in a file that is opened when needed and costs nothing the rest of the time. Getting this split right did more for the size of the always-loaded file than any amount of tightening its sentences.
Repeal tracing: search before you reword
Rewording a rule means searching for its distinctive words across the whole corpus first. The old wording is cited in places the edit never touches — a procedure that points at it, a checklist that quotes it, a note that explains it — and a pointer to text that no longer exists fails silently. Statute law handles this with a schedule of consequential amendments. I handle it with a search, and with a rule that the search runs before the rewording rather than after.
What the door doesn't do
It makes the intended outcome more likely. It guarantees nothing. Nothing can tell an honest "I checked, and this rule is needed" from a dishonest one, because the process is the author checking the author's own work. What it buys is a moment where refusal is possible, and a record of what was decided — so a rule that was refused is not proposed again by someone who never saw the refusal. That last part is most of the value. The rejected rule carries why it lost, and settled things stay settled.
6. Negatives that stayed
A mechanical pass would have destroyed these. Three kinds of negative statement survived, because in each the negative is the content:
- Contrast pairs. The right form beside the wrong one teaches faster than either alone.
- Statements of what a mechanism doesn't cover. "The harness never merges a session's branch back" is a fact about a tool, not an instruction to anybody.
- Honest limits. Throughliner screens every session for anything that might expose the user's data, and the rule governing it ends: never a guarantee that every risk present has been found. Rewriting that as a positive would be a lie told for the sake of consistency.
A style rule that can't tell these apart isn't a style rule. It's a find-and-replace. Telling them apart means reading the provision around each sentence, which is why this was a job of work and not a script.
7. What I can't claim
- The rewrite covered the findings I had, the terminology, and what a full read of each file surfaced. It is not a claim that all 299 statements now conform to the standard.
- A flat count cannot detect a rewrite that changed a rule's meaning. It told me the corpus hadn't grown. It could not tell me whether I'd altered what a rule required while tidying it, and nothing else was watching for that.
- Targets were found by searching for known phrasings. A prohibition in wording I didn't think to search for was never seen, so every pass records what it covered rather than implying the corpus is clean.
And the largest caveat: this is one project, measured on its own documents. I have a corpus, before-and-after behaviour, and a strong conviction. I don't have a controlled experiment.
8. Take the method
The drafting rules ship with this article as a plain prompt you can paste into whatever you're using. No install, nothing to sign up for.