Write a CLAUDE.md Claude will follow, not silently skip
3 min read
A CLAUDE.md is not documentation. It is the file Claude reads at the start of every session. Its length decides whether your rules get followed or quietly skipped.
1. Keep it short enough that every line earns its place
The failure mode: Your CLAUDE.md is 500+ lines of rules, conventions, and context, and Claude is ignoring half of them.
Anthropic's own guidance is explicit: if you can remove a line without Claude making mistakes, remove it.
Bloated CLAUDE.md files cause Claude to ignore the rules that matter. Too many instructions at once, and the important ones get missed. Anthropic does not set a hard line, but under 300 lines is the working ceiling. HumanLayer runs their root file under 60.
The failure mode is invisible. A long file loads successfully and the session starts normally, but the rules that were supposed to stop a bad commit, a wrong dependency, or a production push get silently skipped.
Example rules that belong in every CLAUDE.md:
Never push directly to main. Always work in a dedicated branch. Run typecheck before committing. If it fails, fix it. Do not add @ts-ignore or `as any` casts to pass checks.
Three lines. Every line prevents a specific failure.
2. Write security rules as standing orders, not guidance
The failure mode: Your team's security policy sits in a Notion doc that nobody reads, and AI-generated code keeps introducing the same vulnerabilities you already documented.
The CLAUDE.md is read at the start of every session. Your internal wiki is read once.
In the Control Beacon CLAUDE.md, security rules are grouped by domain and written as absolutes:
- Never implement custom auth logic,
- Never store tokens in localStorage,
- Never trust client-side subscription status,
- Never log PII in application logs,
- Every database query must include the organization filter.
Every file handling auth, payments, or personal data gets a comment marker: AUTH-CRITICAL, PAYMENT-CRITICAL, GDPR-CRITICAL. The marker flags the file for manual review before deploy.
The markers matter because context compresses. A rule followed correctly at hour one of a session gets missed at hour three. The comment marker is the second layer that catches what the rule alone will not.