Most CLAUDE.md files I see fail the same way: they try to be documentation. Three hundred lines of architecture overview, API conventions, folder structure, philosophy. The model reads none of it when it counts.
Your context file is not a wiki. It is a preload. Every token in it competes with your actual request for attention, and the model will happily trade away your testing conventions for a confident answer to whatever you just asked.
The mistakes that matter
1. Writing for a human new hire. Humans skim, bookmark, and come back later. Models get one pass, every session, whether they need it or not. If a line would help a new hire but doesn't change what the AI writes today, cut it.
2. Stating what instead of enforcing how. "We use pytest" is trivia. "Every new module ships with tests in tests/ and CI fails without them" is a rule the agent can act on. If a sentence can't change a decision, it's decoration.
3. No negative rules. The most valuable lines in my context file are the "never" list: never mock the database in integration tests, never add a dependency without asking, never silence a type error with any. Agents default to the path of least resistance. Negative rules are the rails.
4. Burying the load-bearing rule at line 180. Models weight the beginning and end of context. Your three non-negotiables belong in the first ten lines, not in a subsection between "Project history" and "Team rituals."
The shape that works
Mine is under 80 lines. Roughly: a one-paragraph project summary, the stack, five non-negotiable rules, the test command, the "never" list, and a pointer to deeper docs the agent can read when a task actually needs them. Everything else got deleted or moved to files the agent loads on demand.
The test is simple: after editing, ask the agent to do a task that used to go wrong. If it still goes wrong, the rule isn't in the file or isn't enforceable. Rewrite it until the failure disappears.
Where this is going
Context files are the first layer. The next layers are subagents with narrow jobs, hooks that block bad commits before they exist, and slash commands that encode whole workflows. A short, sharp context file is what makes those layers reliable instead of decorative.
I packaged my own setup - the context presets for five stacks, the subagents, the hooks, the commands - into The Agentic Coding Kit. 34 files, drop them into a repo, done. But the lesson works without it: shorter file, enforceable rules, non-negotiables first.
Top comments (0)