Make scope explicit from the first screenful
The strongest CLAUDE.md files answer three questions immediately: what the repository is, what matters most, and what must never be broken. That saves the model from guessing your hierarchy under pressure.
Long philosophy sections are rarely the bottleneck. Missing operational priorities are. If the assistant cannot tell whether stability outranks speed or whether tests outrank cosmetics, the file is underspecified.
Separate global rules from situational ones
Put durable repository norms in CLAUDE.md, then keep volatile workflow details closer to the task. Otherwise every experiment, exception, and temporary caveat bloats the main governance file.
That separation makes the file easier to review and prevents local quirks from masquerading as universal policy.
Write for failure paths as much as happy paths
A useful governance file does not just describe ideal behavior. It tells the model what to do when context is missing, tests fail, commands look risky, or the request conflicts with local reality.