Rules that load by path
I've found that a long instruction file fails quietly. The rule that matters is in there somewhere, next to a dozen that don't apply, and it gets no more attention than any of them.
My root CLAUDE.md had grown to about 7KB. It held fourteen numbered gotchas covering the .NET Framework backend, the Vue front end and the UI tests, and every session loaded all of them, whether Claude was changing a stored procedure or a button.
So I split it. The root file is now short on purpose: what the product is, how the repo is laid out, and the few rules that hold everywhere. The rest moved into three files under .claude/rules, each with a list of paths in its header. The backend rules name the backend projects. The Vue rules name the UI source folder. The test rules name the test folders and spec files, wherever they sit. A rule loads when Claude opens a file that matches, and not before.
There are two ways to scope a rule, and I've come to use them for different things. A CLAUDE.md inside a folder suits a convention that lives in that folder. A path pattern suits files that are scattered, like tests, which no single folder contains.
The UI rules show why this matters. A few of our older Pinia stores are written in the Options style, and left to itself Claude copied them, because the nearest example looked like the house style. The rules say what the house style actually is: single-file components with script setup, the Composition API, and Pinia stores that use persisted state. I've found that without them, the nearest example wins.
Then I found the copy I had forgotten. The UI folder had its own CLAUDE.md with an older list of the same gotchas: two rules behind, plus a backend rule that had no business there. Both files loaded whenever Claude worked on the UI. And the folder file is committed to the repo, so it was the only version my teammates would ever see.
The lesson is simple and easy to miss. A rule that lives in two places will drift. Every rule gets one home, and if anyone else needs it, that home has to be in version control. For the UI gotchas, that home is now the committed file, brought up to date. My private copy of them is gone.
One more habit from the same cleanup: write down what you don't know. The context file behind my architecture board marks anything not recorded as UNKNOWN, with a rule at the top to ask rather than assume. Left blank, an agent fills the gap with something plausible. Marked unknown, it asks.
And when a rule seems to be ignored, check what actually loaded before rewording it. The /memory command shows the instruction files a session picked up.
Rules are not a document. They're a lookup, keyed by the file you're editing.
Setting Up Claude, part 3 of 10. Next: Skills versus hooks.