The diff looked like an improvement.
I asked an AI assistant to tidy up a repository. One method came back shorter. No async machinery, no list allocation, and more flexible for callers. The explanation was good. It would have passed review, and it did.
Then it broke twice, weeks apart, in two different files, and neither of them was the one that had changed. One was an exception in a controller from a line that never mentions a database.
The assistant hadn't made a mistake. It made the right call based on what it could see, which was the code and nothing else. Nowhere in that file did it say we had an incident here.
That's the gap a rules file is meant to close: CLAUDE.md, AGENTS.md, .github/copilot-instructions.md, whatever your tool reads. Most of them are written wrong. They're full of things the model already believes, and the handful of rules that matter get buried under them.
In the post:
- A one-question test for whether a rule belongs in the file. Most of a typical rules file fails it
- What a rule needs besides the instruction, and what a helpful assistant does with a rule that's only the instruction
- Five pieces of load-bearing code that look redundant, and why a tidying assistant reaches for every one of them
- Where a rule has to live for the edit that would break it to ever see it
- A pre-release check of ours that ran green for six weeks. The docs said it exited non-zero on a bad answer. It never could
- Why a stale rule does more damage than a missing one
- The two sentences most rules files leave out, which are worth more than anything else in the file
None of it is prompt tips. It's about what has to outlive the conversation.
Read it → The Rules File: Governing AI Before It Writes a Line
If your assistant has ever cleaned up something that was there for a reason, hit reply. It goes straight to me and I read everything.
— Michael
