We Cut Our AI Instructions in Half and It Got Better
For a long time, we treated more instructions as more control. Every time an AI agent did something we did not expect, we wrote another rule, and every rule felt like a small gain in predictability. Then we cut the main instruction file in our delivery repository from 463 lines to 199, rewrote our delivery agents as short contracts, and the work got better. This post covers what we learned about AI context window management along the way, and why the lesson was less about saving tokens than about what we had been asking the AI to do.
More Instructions Felt Like More Control
Our delivery system grew the way most AI configurations grow: by accretion. A run went wrong, we added a rule. A corner case appeared, we added a check. Each addition was reasonable on its own. Together, they became about 27,000 lines of Markdown and 58,500 lines of Python governing seven delivery agents.
The main instruction file, the one an AI session loads on every single interaction, grew from 382 lines to 404 to 463 while we built. Token use climbed with it, and when we looked at where the cost went, most of it was mechanism rather than work: limits against stuck situations that never happened, safeguards for other components’ failures, and the same content restated in several places.
A Rule Is Followed Even Where It Should Not Be
The most important thing we learned was not about volume. It was about what a fixed rule does to an AI.
When you tell an AI to always keep a file under 100 lines, it will do exactly that. It will do it in the ordinary case, where the rule makes sense, and it will do it in the corner case, where the rule makes no sense at all. The AI is not wrong to follow it. We told it to.
The natural response is to add an exception: always under 100 lines, except when the content is a register that has to stay in one place. Then you find the next corner case, and the next one. Each “except” invites another, and the list never covers every situation, because nobody can foresee every situation. We spent a surprising amount of effort writing exceptions to our own rules, and the AI followed those just as literally.
State the Goal, Not the Route
What worked better was to stop describing the route and describe the result instead. Rather than a line limit with a list of exceptions, we now tell the AI what we want: the most effective, least token-consuming way to do the work, without compromising quality. Given that goal, the AI tends to find the best way there on its own, including in the cases we would have needed an exception for.
So we rewrote each delivery agent as a contract: its purpose, its inputs, its outputs, and the professional it behaves like. The steps are the model’s. Each agent’s definition now fits in fewer than 200 lines. We still write rules, but they describe what the output must look like and the quality we expect, not how to get there. A step-level rule comes back only when the same mistake repeats, and only for that mistake. I described the contract model and the five steps it runs through in The Five Steps Inside Our AI Delivery Pipeline, so I will not repeat it here.
The part I like best is what happens when the models improve. A scripted route stays exactly as good as the day we wrote it. A goal lets a better model find a better route, and we do not have to touch the definition for that to happen.
Why We Took the Number Away
We learned the same lesson a second time with the instruction file itself. When we reduced it, we also set a cap of 200 lines, so that it could not grow back. I reverted that cap. Our instruction files serve projects with very different remits, and one number applied to all of them would have turned a useful measurement into a gate that blocked work for no good reason.
We had already seen what that kind of gate costs. For a while, a growth check blocked any added line in any size-limited file, even a file far below its limit, unless the file was on an exceptions list. In 25 days, that list grew to 41 of its 48 allowed entries. It was the exceptions loop again, this time in our own tooling. We retired the check. Size limits now stay where they protect something, and when real work needs more room, the limit is raised in a reviewed step, with the reason written next to the new number.
Three Questions for Every Line
An instruction file is the one part of an AI configuration that is loaded on every interaction, so every line in it is a cost paid every time. That is where AI context window management starts for us. We now hold each line to three questions:
- Does this change the AI’s behavior on the next task?
- Does the AI need this on every single interaction?
- Will this still be accurate in two weeks without anyone updating it?
If any answer is no, the line moves somewhere the AI reads only when it needs it: a reference document, a decision record, or the tracker. What stays is identity, concrete rules, prohibitions, naming conventions, workflow gates, and pointers to the detail. Applying that test is how the file went from 463 lines to 199. We checked that nothing was lost mechanically rather than by rereading: every command the old file named and every entry in its document registry was still reachable from the new one.
Waste Goes, Quality Stays
Two principles now sit underneath all of this. An agent loads only what its purpose needs. And waste is traded away, but quality never is. Cutting instructions was never the goal in itself. The goal was an AI that spends its attention on the work, with room to find the best way to do it.
There is one honest limit. One of our instruction files lives in a project workspace outside any repository, so no automated check reaches it. A person applies the same three questions to it by hand.
If your AI configuration has grown past what anyone on the team reads, or your agents follow your rules a little too faithfully, we would be glad to compare notes. Contact us at A-CX.
