When a company rolls out coding agents, there is usually one file every agent reads first: the global instructions. House style, what never to touch, how to report, when to ask. It is the closest thing an AI rollout has to an employee handbook, and the easiest way to produce it is to ask a model to write it.
Don't. Models are good at copying and adapting task-level skills (I argue for exactly that elsewhere). The global file is the one place where manual input wins, and where the rules that matter most should not live in the file at all.
Why a generated rulebook is empty
A model asked to write agent instructions writes what agents are generally told: be concise, test your changes, follow conventions. The model already does most of that. A rule it would follow anyway takes up attention on every task and changes nothing.
My global file opens with this line: "Every section exists because something broke without it." That is the test a generated file cannot pass. Each rule in it has an incident behind it: a command that failed silently, a deletion that nearly happened, a report of success that was false. The incident is what makes the rule specific enough to change behaviour, and it is also what lets a person judge later whether the rule still earns its place. A generated rule has no incident, so nobody can ever tell when to delete it.
I checked that claim against the file today. It has 21 sections over 354 lines, and only 4 of its rules cite a recorded incident by number. The rest carry their incident as a sentence of explanation, or not at all. So even a hand-written file drifts toward rules nobody can trace, and the count is worth running on your own. It is also why the next section matters more than this one.
The file also tells the agent what to do when a rule is wrong: say so, and don't quietly work around it. A generated file never includes that line, because it does not expect to be wrong.
Why the important rules leave the file
Hand-writing the file still leaves a gap: prose is advice. I made the general case in Enforcement Is the Moat, about a memory system whose value turned out to be its lint rules, not its templates. The global instruction file is where that bites hardest. My file records the incident that taught me this. An unattended job was told in its prompt to run as a dry run. It performed a real compaction anyway. The rule that came out of it is in the file verbatim: "A prose-bounded autonomy grant is documentation, not a guard." Boundaries for unattended work now live in code that runs before the model does.
So the file has two kinds of content, and they are handled differently:
| Kind | Example | Where it lives |
|---|---|---|
| Judgment | take the narrow reading of an ambiguous request | written by hand, in the file |
| Hard limit | never edit the permissions config | a hook that blocks the write, plus a line in the file saying why |
The agent cannot edit the global file itself. A guard script runs before every file edit, and for this one path it answers:
BLOCKED [config-guard]: ~/.claude/CLAUDE.md is a protected global config file.
So every change to the rulebook passes through a person's hands. That is manual input enforced by code, and it is the one rule I would copy first into any company's rollout.
The rule with no exit
Writing by hand has its own failure, and I found it in my own file. "Every section exists because something broke" is an entry rule. It has no exit rule. As models improve, a rule written against last year's mistake keeps costing attention long after the mistake stopped happening, and nothing in the file can ever expire on its own.
The fix went into the process that changes the harness: every new rule now has to state what would make it unnecessary, whether that is a model upgrade, a shipped feature, or a metric crossing a line. A rule without that line does not go in.
What to take from it
For anyone writing the handbook for their company's agents:
- A person writes the global file. One rule per incident, with the incident named.
- Anything that must never happen is enforced in code. The file explains the guard; it is not the guard.
- The agent cannot edit the file. Block it, don't ask it.
- Every rule states its expiry. What would make it unnecessary?
A handbook the new hire wrote for themselves is not a handbook. The same goes for the agent.