Your instructions file started at forty lines and everybody agreed with all of them. Then it got the testing conventions, and the list of internal libraries, and a section about migrations. It is four hundred lines now, and the assistant keeps doing the thing that is forbidden on line two hundred and twelve.
The usual response is to make the file more emphatic. Bold the rule, move it to the top, add “IMPORTANT”. That works for a week, and then the next rule needs to be at the top too.
The only file with a price
Every other file in a repository is read when somebody opens it. An always-on context file is different: it is prepended to every turn, so a line in it is paid for on the first turn, and the fortieth, and every one after that.
That gives you a test no other document has to pass. For each line, ask whether it is needed on every turn, or whether it could be looked up when it is relevant. Almost everything is lookup-able, and the exceptions are a short list: the shape of the repository, the handful of rules that decide whether a change is acceptable, and where to find everything else.
| what it is | where it belongs |
|---|---|
| the architecture in one table | the context file |
which slice owns Booking
|
a registry, looked up by key |
| “never weaken a test to get green” | the context file |
| the twelve things that have surprised us | a searchable index |
| how to run the checks | the context file, one line |
| what each of the nine scripts does | a registry, one lookup |
What a registry buys that a list does not
The obvious objection is that a list of tools in the context file works fine. It does, and it costs twice.
It costs tokens on every turn, which is the visible half. The other half is that a list has to be re-read and re-reasoned about each session: the assistant sees nine descriptions, decides which one applies, and does that again tomorrow. A registry is looked up once, by key, and the answer is a fact rather than a judgement.
$ toolbox/tool_mapping.py list
arch-map Which slice owns what, and which slice may depend on which
check-readmes Every navigable directory has a README
evals Does each gate say yes and no in the right places
lexicon How a recurring problem was solved here before
mutation-survivors Surviving mutants and where they are, in about 15 lines
...
$ toolbox/arch_map.py get booking
responsibility Who may take which desk on which date. The write side.
may depend on desk, shared
enforced by ArchitectureRulesTest
The context file carries three lines pointing at those commands. It does not carry their output.
The part that stops it decaying
A registry has the same failure mode as the document it replaced: it goes stale, and nothing breaks when it does. The build passes, the tests pass, and the only symptom is somebody rebuilding a script months later because they could not find the first one.
So the registry is checked. In deskspace, which is where these examples come from, the build fails when a script exists without being registered and when the architecture map names a package that is not there. An unregistered tool is an undiscoverable tool, and a map that disagrees with the tree sends the next reader confidently to the wrong place, which is worse than no map at all.
That check has caught its own author more than once. It also, memorably, caught itself: after the scripts moved to a new directory, the checker kept scanning the old path, and globbing a directory that no longer exists returns nothing, so nothing was ever unregistered and it reported success. Forever.
The test to apply on Monday
Open your context file and read it as a bill. For each line, ask what it would cost to look this up instead, and what it costs to carry it on every turn until somebody deletes it.
Most teams find the same thing: about a fifth of the file is genuinely always-on, and the rest is reference material that ended up there because there was nowhere else to put it. Making somewhere else to put it is the work, and it is the same work as making the rule findable at all.
If your team’s instructions file has grown past the point where anybody reads it, that’s the work I do.