Cutting the rules file my assistant loads every session

The file that loaded everywhere

Every Claude Code session on every one of my machines starts the same way. Before I type a word, it reads a global instructions file. Mine had grown to 405 lines.

The growth was honest. Each line was there because something went wrong once and I wrote down the rule that would have prevented it. A wrong SSH username on one host. A sed flag that behaves differently on macOS. A timer that quietly did nothing for weeks. The file was a log of scar tissue, and it worked, in the sense that the same mistakes mostly stopped repeating.

But a file that loads everywhere pays its cost everywhere. The server runbook lived in there, with the full table of systemd timers and what each one does, even though only one machine runs those timers. So did the skills, commands and runbooks for a work lane that closed at the start of October. A session on my laptop editing a website was spending context on an inventory of jobs it would never touch.

What counts as a cross-machine rule

The question I asked of each section was simple. Does every session on every machine need this? If yes, it stays. If only the server needs it, it moves to the server's own documentation. If nothing needs it anymore, it gets archived, not deleted.

Most sections failed the first test. The runbook and the timer table moved into a server operations document inside the project repo, next to the code that defines those timers. That is where they belonged all along. A timer table is not a rule. It is state, and state should live close to the thing it describes.

The closed work lane got an archive page in my notes vault, a line in the vault index, and a pointer from the main architecture document saying where it went. Nine timer rows are marked disabled rather than removed, so the record of what used to run stays readable.

The global file went from 405 lines to 156. What remains is true on every machine: how to navigate the system, the orchestration defaults, the handful of shell traps that bit me more than once, and the safety rules around production and backups.

The part that is easy to skip

Moving a document is the easy half. The hard half is everything that pointed at it.

I have two automated checks that read the timer table. One is a weekly system verification pass. The other checks that the timer documentation agrees with what is actually installed. Both had the old location baked in. If I had moved the table and stopped there, both detectors would have gone quiet, and quiet looks exactly like healthy. I re-pointed both in the same session.

The architecture diagrams needed the same treatment. Two of them, the automation map and the master map, still showed the paused lane as live and still named the old home of the timer table. I re-rendered both. My diagrams carry a freshness manifest that records a hash of each truth source, and the entry for the timer table now points at the new document.

One piece is still open, and I would rather write that down than pretend it is finished. Re-truing the manifest against the new document is blocked until the live checkout on the server carries that file. The change is sitting in a pull request. Until it merges, the freshness check will keep flagging those diagrams, and that is the right behaviour. A detector that complains about a real gap is doing its job.

What I learned, again

Not long ago I wrote here about a number on my homepage that had quietly gone stale. This was the same lesson in a different file. Anything that describes a system drifts away from it unless the description lives next to the thing it describes and something checks the two against each other.

The 405-line file was not wrong. It was in the wrong place, and every session was paying for that. A rule that every machine needs belongs in the file every machine loads. Everything else belongs with its owner.