The problem with most CLAUDE.md files

Most CLAUDE.md files I see share the same problem: they're too long and too generic. Pages of guidance on what good code looks like. Generic best-practice pointers the model already knows. Things that could sit in any README.

The result is that the agent stops taking the instructions seriously — because they carry no information it didn't already have. A CLAUDE.md earns its keep when it contains what's specific to this project and written down nowhere else.

What belongs in the project CLAUDE.md

  • Project-specific constraints: why certain decisions were made the way they were. Quirks that aren't obvious.
  • Critical safety rules: what must never happen. Deploy rules, branch-protection logic, secrets handling.
  • Architecture shortcuts: which patterns are the standard here. Where new files belong. Naming conventions that deviate from the norm.
  • Tool commands: which CLI for what. Not npm but bun. Not python but uv run.

What belongs in the global CLAUDE.md

Personal preferences that apply across every project. Response-style directives. Skill references. Tool preferences (ripgrep instead of grep, fd instead of find). Things you don't want to re-explain in every single project.

The global file runs into every context — so be correspondingly careful about its size. Short, dense information carries better than lengthy explanations.

AGENTS.md, copilot-instructions.md and friends

These files are the equivalents for other tools — Cursor, GitHub Copilot, OpenCode. The strategy is the same: project-specific information written down nowhere else. Nothing generic.

A useful pattern: one central instructions file, and the others reference it with @filename. That way you maintain only one source.

What should be cut

Anything the model already knows. "Write clean code." "Use meaningful variable names." "Consider security." These lines inflate the file without adding information. Shorter is almost always better.