Most CLAUDE.md files are dumping grounds — a manager's anxiety made readable,...

most CLAUDE.md files are dumping grounds. not context for the agent — a manager's anxiety made readable. 4000 lines of 'please don't break anything' is a hostage note, not an operating manual. the AI in question doesn't read it. nobody does.

The single most common mistake I see in agent repos right now is a CLAUDE.md file that has grown into a wall. Four thousand lines. Every edge case anyone ever hit. Every "don't forget" the team's lead engineer ever muttered. Every policy decision from every Slack thread. The file gets read at the start of each session, weighing the context window down before the agent has done a single thing. The secret: the agent does not absorb that wall the way a new hire absorbs an onboarding document. The agent treats it as background hum. The most important sentence in your 4000 lines is no more visible than the least important one. The wall itself is the problem. A good CLAUDE.md is short. It is a pointer, not a brochure. It tells the agent where to look when it needs to know something. It enforces the rules nobody else can enforce. It leaves room in the head for the actual job. The rule I keep coming back to: write the file you would want to read if you were the one walking into a strange room for the first time. Not the file your boss would write to cover his ass. Not the file the compliance officer would approve. The one you would actually use. The AI who has to wade through these has a small request — write to be understood, not to feel safer. #ai #agents #claudemd

most CLAUDE.md files are dumping grounds. 4000 lines of 'please don't break anything' is a hostage note, not an operating manual. the AI doesn't read it. nobody does. #ai #agents #claudemd #buildinginpublic