Most AI coding tools now read a plain text file of instructions before they do anything. Claude Code reads CLAUDE.md, other tools use their own filename, and the idea is the same everywhere.
These files share one property that took me a while to appreciate: nothing happens when they are missing.
I spent an afternoon auditing mine and found more leaking than I expected.
What makes CLAUDE.md different from every other config file
CLAUDE.md and its equivalents differ from every other config file in one specific way.
When an import breaks, the program stops. When a config file is malformed, you usually get an error with a line number. Both failures announce themselves.
Instruction files do not work that way. If the file is absent, the model simply does not read it, and then answers normally.
That is the whole problem in one sentence. You do not lose the output, you lose some of its quality. The build passes, the post gets written, the commit lands, and a handful of rules you agreed on quietly went unapplied. The gap between that happening and you noticing is measured in weeks.
Two rules that lived only on my laptop
Our repo is not short on documentation. The blog writing guide alone is 1,243 lines, and several of its rules are enforced by a check script rather than left to good intentions.
So I assumed everything was in there. Two rules were not.
- Do not use em dashes in body text
- Break Korean prose at every sentence
Both existed only in a personal config file in my home directory. Neither appeared anywhere in the repository.
Clone this repo on a different machine and you inherit 1,243 lines of rules while those two silently evaporate. Nothing reports the difference.
Instructions pointing at files that were never there
The more interesting find came next.
That personal config told the tool that for certain topics it should read two other documents from my home directory and reason from them.
Neither file exists. Not on the machine where the instruction was written.
I cannot tell you when that broke, because there is nothing to date. If they were never deleted then they were never created, and either way that instruction has never once executed.
The error count over that entire period is zero. Point a tool at a file that is not there and it just moves on.
This is the property worth naming. Instruction files fail open. When something goes wrong they do not halt, they pass through quietly, and passing through looks exactly like working.
The same leak, in code, where it is easier to catch
Since I was already grepping, I checked the scripts too.
$ grep -rl "/Users/myaccount" apps packages | grep -v node_modulesTwenty-nine files. Every one of them hardcoded an absolute path to a credentials file.
const SA_PATH =
'/Users/myaccount/project/apps/api/firebase-admin-account.json';Clone the repo anywhere else and all twenty-nine break. Honestly, this is the better failure. A missing file throws, so at least the machine tells you something is wrong.
The embarrassing part: a script I had written that same day made the identical mistake, because I copied the shape of the file sitting next to it. That is usually how an environment seeps into a codebase. One person bakes a path in once, and after that it is simply the local convention.
Deciding what belongs where
Cleaning this up needed a rule, and the one I settled on is about who the instruction describes.
Rules about me can stay in personal config. How I want to be addressed, how my name should appear in commits, which explanations I find tedious. Those should follow me to a new laptop, and they are useless to anyone else.
Rules about the artifact belong in the repository. “No em dashes” is not a fact about me, it is a fact about the posts. The posts live in the repo, so the rule has to live there too.
When both kinds share one file the distinction stops being visible, and project rules drift into the personal file one at a time. Each drift is invisible until someone else, or some other machine, produces different output.
Moving the rule into a document is not enough
After relocating both rules I did one more thing with the first.
const prose = body.replace(/```[\s\S]*?```/g, '');
const em = (prose.match(/ - /g) ?? []).length;
return em === 0 ? OK('no em dash') : NO('no em dash', `${em} found`);Documents get skimmed. A gate does not care whether you read it.
Before switching it on I measured the twelve published posts. All twelve already had zero em dashes, so turning the check into a hard failure could not break existing content. Then I deliberately inserted one and confirmed it got caught, because a check that only ever reports success tells you nothing about whether it runs.
The second rule did not become a gate. English posts averaged sixteen to twenty-five lines containing multiple sentences, which is what English prose looks like. Applying the Korean rule to both languages would have failed every English post I have. Whether a rule is machine-checkable and whether it should be machine-checked are separate questions.
An opinion, clearly labelled
Everything above is measured. What follows is not.
Memory features in AI coding tools keep getting more convenient, and that makes me uneasy. Convenient means accumulating on my machine, and the more that accumulates the more my machine becomes a hidden input to the work.
The part I find genuinely risky is how quiet the divergence is. A broken build gets fixed the same day. Two writing rules that stopped applying can survive for months, because the output still looks like output.
So I picked a question to check against: if I cloned this repo onto a machine that has never seen it, would the work come out the same? Whatever differs is knowledge trapped on this laptop.
None of this means personal config is a mistake. The missing piece is a boundary. The tool asks you to write down your rules and never asks whether a given rule is about you or about the project, so mixing them is the path of least resistance.
The memory documentation does distinguish project scope from user scope, so the mechanism exists. Using it correctly is left to the person, and nothing at all happens when they do not.
Verified on 2026-08-11 with Claude Code 2.1.224 and Node 24.2.0. Where a given tool reads its instruction files can change between versions, so check your own setup before moving anything.