If your CLAUDE.md still looks like a 2024 brain dump — 500 lines of "write good code" and "consider using async" — it's time for a rewrite. The file is two years old as a widely-used artifact, and the practices have shifted dramatically.
Early 2026 consensus, drawn from hundreds of public projects and operational lessons from teams running Claude Code, Cursor, and Codex side by side, converges on a more disciplined approach. Here's what changed and what you should do about it.
Key Takeaways
- The 2026 consensus on CLAUDE.md: shorter files, falsifiable rules, and explicit enforcement.
- Here's the 8-rule framework to stop your agent from fighting stale configs.
What Changed Since 2024
Three shifts reshaped the practice:
- Agents got better at inferring — they need less convention documentation. The volume of "how to write code" rules dropped.
- Agents got worse at handling contradictions — they trust the file more, so a stale rule corrupts more decisions.
- Multi-agent workflows became common — the same project gets touched by Claude Code, Cursor, and Codex within a single sprint. CLAUDE.md, AGENTS.md, and
.cursor/rulesmust align.
The result: CLAUDE.md is shorter, stricter, and increasingly authored alongside parallel files that must stay consistent.
The 2026 Consensus: 8 Rules
Rule 1: Keep it under 250 lines
Files above this length get skim-read by both humans and agents. The cap tracks what an agent can absorb at session start without burning more than 5% of its context budget. Most projects that started 2026 above the cap have rewritten down.
Rule 2: Every rule must be falsifiable
"Write good code" is not falsifiable. "All async functions must have a timeout" is. Soft directives like "consider doing X" have fallen out of favor — agents either follow them as hard rules or ignore them entirely. Make every rule a hard rule or delete it.
Rule 3: Pair every rule with its enforcement
A rule that lives only in CLAUDE.md is a wish. Have an explicit enforcement layer for every rule — a hook, a CI check, a linter rule, or an explicit "advisory only" tag. The advisory tag calibrates how strictly the agent applies it.
Rule 4: Capture decisions, not behaviors
"Use TypeScript strict mode" describes a current behavior — the agent can read that from tsconfig.json. "We use TypeScript strict because we got burned by an any cascade in Q3 2024" captures a decision and its reasoning, which the agent cannot read from code.
Rule 5: Align CLAUDE.md with parallel files
If your project has AGENTS.md, .cursor/rules, or .codex/instructions, they must not contradict each other. Make CLAUDE.md the canonical source and have the others either symlink, generate from it, or include it. Manual cross-file maintenance is the failure mode that ends every multi-tool project.
Rule 6: Explicit communication style
Specify language, tone, and verbosity. "English, terse, no preamble before tool calls" is fully specified. Without this, the agent picks a default that may not match your team's preference.
Rule 7: Maintain an explicit principles section
Three to seven principles, each with a one-sentence rationale. Principles are the rules that apply when no other rule applies. Without them, the agent's defaults take over on edge cases.
Rule 8: Review quarterly
Set a calendar reminder, not a vague intention. The file drifts even when you aren't editing it because the project around it changes.
Anti-Patterns to Retire
- The kitchen-sink section — 200-line "Coding Standards" sections. Replace with a 20-line "Language & Style" section naming only rules a linter cannot enforce.
- The philosophy section — paragraphs about team values. Move to a separate values doc.
- The historical archive — sections explaining what the project used to do. Agents sometimes treat abandoned approaches as current options.
- The meta-section — rules about CLAUDE.md itself. These belong in your team's documentation, not in the file the agent reads.
- The duplicated rule — the same rule appearing in two sections. AgentLint catches these now.
A 2026-Shaped CLAUDE.md Skeleton
## Project (1 paragraph)
What it is. Stack. Audience.
## Non-negotiables (5-10 rules)
Hard process rules. Each falsifiable. Each enforced.
## Language & Style (5-15 rules)
Things the linter cannot enforce. Type policy. Imports.
## Operational Notes (5-15 rules)
Surprising facts about the environment. Symlinks. Flaky CI steps.
## Communication (3-5 rules)
Language. Tone. Verbosity.
## Principles (3-7 rules with rationale)
The rules that apply when no other rule applies.
## Enforcement (auto-generated or hand-maintained)
Mapping of rule → hook / CI step / "advisory only" tag.
This is the skeleton AgentLint's --init command emits. The skeleton stays under 100 lines on its own.
Where 2027 Might Go
Two trends are visible: machine-readable CLAUDE.md with structured frontmatter and YAML-tagged sections for deterministic parsing, and CLAUDE.md as a contract pinned as part of the PR workflow. Both are early, but worth watching.
For now, the disciplined defaults are the ones above. Short. Falsifiable. Enforced. Aligned across tools. Reviewed quarterly. The teams that do these things have CLAUDE.md files that carry weight; the teams that don't have files that drift into the dead-letter pile.
