Every serious coding-agent user's CLAUDE.md walks the same road. It starts empty. Every incident adds a line. One day you look up and it's 500 lines long.
Then something strange happens. The more rules you add, the fewer rules the agent follows. You wrote it down, clearly, and it gets ignored. So you write the same rule again, louder. Bold it, add an exclamation mark, prefix it with "ALWAYS". It still gets ignored.
This guide is about what to take out of your CLAUDE.md, not what to put in. The short version: a good CLAUDE.md is a short constitution, not a long rulebook. If your tool reads AGENTS.md instead, the same principles apply.
Why the file gets heavy
The path is always the same. The agent makes a mistake. You add a rule. It makes a different mistake. You add another.
