My CLAUDE.md had a rule about it. The generated code broke the rule anyway. And the thing that finally caught it wasn't my config file. It was a rejection from the WordPress.org plugin review team.
I'd been building plugins with a long CLAUDE.md. Over time I'd folded two whole guides into it: the WordPress Japanese translation style rules I follow, and my own plugin design conventions, including the things you're specifically not supposed to do. It got long. And the longer it got, the safer I felt. It's written down, so it'll be followed. That was the assumption, and I never once questioned it.
Then I shipped a plugin with trialware-shaped code around how paid features were gated, the kind of thing the WordPress.org directory guidelines push back on, and the kind of thing my own design guide explicitly told the agent to avoid. The rule was right there in the file. The generated code stepped on it anyway, and I didn't notice until the rejection came back.
That rejection did something useful. It turned my trust in the config file inside out. I had written the rule. I had never checked whether it was in effect. And the thing that finally graded whether my own guide was working wasn't my guide. It was a reviewer on the other side, weeks later.
Written is not the same as in effect
Here's the assumption I think most of us run on: a config file is something you write and then trust. Written equals followed. A long instruction file doesn't actually work that way, though. Its effect starts leaking the moment it gets long. There's good writing on this now: a monolithic CLAUDE.md that runs to a few thousand lines creates two problems at once. The agent processes all of it regardless of the task, and nobody fully owns it, so sections accumulate debt until it becomes the file everyone references and no one really trusts. I'd read exactly that, nodded, and kept adding lines anyway, because adding is easy and nothing ever tells you to delete.
Two ways it stops being followed, neither of them loud
A config rule can go dead in two ways, and both are silent. The first is length. The rule is in there, it gets read, and it still doesn't shape the output, because it's one line competing with a couple thousand others for the model's attention. The second is drift: your conventions move on, but the file keeps steering the agent by the old ones, so it generates yesterday's practice with complete confidence. Both look identical from where you sit. The rule is written. You can point straight at it. And it isn't doing anything.
That's the part I had backwards. I thought a careful enough config file was something I could trust. It can't be, because a config file can't certify its own effect. The proof that a rule is live never comes from the file. It comes from outside it: a test, or a review that catches what slipped through. My CLAUDE.md couldn't tell me the trialware rule had quietly stopped mattering. Only the rejection could.
What I do now instead of trusting it
So I stopped trying to build a config file I could trust, and started trying to measure whether the one I have is still in effect.
In practice that's a few small changes. I keep it shorter than feels comfortable, and I treat adding a line as a cost rather than a free safety net, because every line I add dilutes the ones already fighting for attention. I put a little metadata at the top, an owner and a last-reviewed date, less for the agent than for the version of me six months from now who needs to know whether a section has gone stale. And before I lean on a rule for anything that actually matters, like a directory guideline I can get rejected over, I open a fresh session and ask the agent to tell me which conventions it thinks are currently in effect. Then I read that list for the ones that have gone missing. None of this restores trust in the file. It just gives me a way to keep checking, which turns out to be the only thing that was ever really holding.
A note to my next self
A config file is not as loaded as it looks. The length that makes you feel safe is the same length that dilutes the one rule you're counting on, and you won't feel it happen. Before you add the next line, check whether the last one is still doing anything.
A config file isn't something you write and then trust. It's only as loaded as your last check. Mine was lighter than I thought, and it took a stranger's review to tell me.
Background reading on the monolithic-file problem, context drift, and config-file metadata: Packmind's 2026 context-engineering guides. The experience and the rejection are my own.
