Your CLAUDE.md Is a Junk Drawer

My CLAUDE.md started small and focused. A few tight paragraphs: here’s how I like commits done, here’s what this project is, don’t do that one annoying thing. Useful. By the time it stopped working it was a sprawl, and I couldn’t always tell you why half the lines were in there.

It sprawls because one file ends up holding four different kinds of thing. There are conventions (how I want work done, which barely change). There’s state (what’s true about the project right now, which changes constantly). There are instructions (do this specific task, good for one job and then stale). And there’s personality (how the thing should talk to me, which is just taste). They all feel like “stuff the assistant should know,” so they all go in the one file.

It works right up until it doesn’t. The conventions that matter get buried next to a stale note about a branch that merged weeks ago. The model weighs a throwaway line the same as a load-bearing rule. You change how the project works, but the file still describes last month’s version, so now it’s confidently wrong. Nothing errors. It just gets worse at the job, and you can’t see why.

The tell that it’s a junk drawer and not a config file is that you’re afraid to delete anything. You don’t remember what half the lines do, so they all stay, just in case. That isn’t a length problem you fix by trimming. It’s four jobs sharing one drawer.

Nobody sets out to write a junk drawer, the same way nobody sets out to write spaghetti code. You sit down to solve today’s problem, fast, and the sprawl is what a hundred of those sessions leave behind.

The way out is boring: stop asking the file to be four things. They don’t even change at the same rate. Conventions barely move, so they can stay put. State changes daily, so it shouldn’t live in hand-edited (or even AI-edited) prose at all. A one-off instruction should turn up when it’s needed and then get out of the way. (Where each piece actually goes is its own post.) But the first move is just noticing the file isn’t too long. It’s holding four jobs that want four homes.