Keep the file under 250 lines.
A CLAUDE.md that takes minutes to scan becomes background noise. Put durable rules in the main file and move long examples, history, and generated inventories into linked docs.
A strong CLAUDE.md is not a brand book for the model. It is a compact operating contract for the repo: what must be true, how to verify it, and where the agent should stop.
A CLAUDE.md that takes minutes to scan becomes background noise. Put durable rules in the main file and move long examples, history, and generated inventories into linked docs.
A good rule lets a reviewer say whether the agent followed it. Replace advice like "be careful" with a concrete action, boundary, command, or output requirement.
If a rule protects security, data, releases, or money, it should not live only in prose. Back it with CI, hooks, permissions, or a required verification command.
Agents do better with branching rules than personality traits. Say when to ask, when to proceed, when to stop, and what evidence changes the decision.
CLAUDE.md, AGENTS.md, Cursor rules, and Copilot instructions often drift. If the same policy appears in more than one file, name the source of truth or keep the copies mechanically synchronized.
Tell the agent how to report work, failures, uncertainty, and user-facing changes. This belongs in the harness because it shapes every handoff, not just one task.
Principles help when they explain tradeoffs the repo actually makes. Keep them short and connect each principle to concrete rules elsewhere in the file.
Agent rules age when tools, tests, ownership, or release flows change. Review the file at least quarterly and after major framework, CI, or agent upgrades.
A giant "important notes" block usually hides unrelated constraints, old caveats, and one-off preferences. Split it into rules that have owners, scope, and enforcement.
A long essay about how to think rarely changes behavior. Convert it into a short principle plus the exact decision rules that make the principle actionable.
Do not preserve migration notes, incident history, or past commands in the main instruction file unless agents still need them. Link to the archive instead.
The same rule repeated in multiple files becomes dangerous once one copy changes. Pick one canonical location and point the other layers to it.
AgentLint audits CLAUDE.md, AGENTS.md, CI, hooks, and adjacent harness files with 33 evidence-backed checks.
Run AgentLint against your CLAUDE.md