CLAUDE.md Best Practices, 2026

CLAUDE.md is two years old as a widely-used artifact and the practices around it have shifted significantly in the last twelve months. The 2024 practice was to dump everything into one long file and hope. The 2025 practice was to split by section and hope slightly less. The 2026 practice — emerging from a few hundred public projects, the dispatches from Hashimoto / OpenAI / LangChain on agent harness design, and the operational lessons from teams running Claude Code, Cursor, and Codex side by side — is starting to converge on something more disciplined. This is what those practices look like as of early 2026.

What changed since 2024

Three things changed that reshaped the practice. First, the agents themselves got better at reading less and inferring more, so the volume of "convention documentation" needed in CLAUDE.md dropped. Second, the agents got worse at handling contradictions and stale rules — partly because they trust the file more, so a stale rule corrupts more decisions. Third, multi-agent workflows became common, with the same project being touched by Claude Code, Cursor, and Codex within a single sprint, which means CLAUDE.md / AGENTS.md / .cursor/rules all have to align rather than each be a separate kingdom.

The practical effect is that CLAUDE.md is shorter than it was, more strict than it was, and increasingly authored alongside parallel files (AGENTS.md, .cursor/rules, .codex/instructions) that have to stay consistent.

The current consensus, in eight rules

These are the practices that pass the "more than half of the well-run projects I've seen do this" bar. They are not universal — but if you are picking which practices to adopt, these are the ones with the best return.

Rule one: keep it under 250 lines. Files above this length get skim-read by both humans and agents. The cap is not arbitrary; it 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 two: every rule must be falsifiable. "Write good code" is not falsifiable. "All async functions must have a timeout" is. The 2025 practice of soft directives ("consider doing X") has fallen out of favor — the agents either followed the soft rules as if they were hard, or ignored them entirely, and the indeterminacy was worse than either option. Make every rule a hard rule or delete it.

Rule three: pair every rule with its enforcement. A rule that lives only in CLAUDE.md is a wish. The 2026 practice is to 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 is important: it tells the agent (and contributors) that the rule is a preference rather than a guard, which calibrates how strictly to apply it.

Rule four: capture decisions, not behaviors. "Use TypeScript strict mode" describes a current behavior of the project — and 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 the code. The 2026 file leans toward the latter.

Rule five: align CLAUDE.md with parallel files. If the project has AGENTS.md, the two files must not contradict each other. The same applies to .cursor/rules, .codex/instructions, and any other harness file. The recommended approach is to 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 six: explicit communication style. Specify what language the agent should communicate in, what tone to use, and how verbose to be. "English, terse, no preamble before tool calls" is a fully specified directive. Without this, the agent will pick a default that may not match the team's preference, and the cost compounds session by session.

Rule seven: 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, which may or may not match the project. With them, edge cases get handled the way you'd handle them.

Rule eight: review quarterly. A reminder set on a calendar, not a vague intention. The file drifts even when you are not actively editing it because the project around it changes. Quarterly review catches the drift before it becomes an emergency.

Anti-patterns the field has retired

Some practices that were common in 2024 are now considered actively harmful, and projects that still do them are fighting their own files.

The first is the kitchen-sink section — a "Coding Standards" section that runs 200 lines and tries to cover every conceivable pattern. These never get read in full and contain so many soft rules that the strict ones get diluted. The 2026 replacement is a 20-line "Language & Style" section that names only the rules a linter cannot enforce.

The second is the philosophy section — paragraphs about the team's values, mission, and design philosophy. These are pleasant to write and contribute nothing actionable. The 2026 practice is to omit them or move them to a separate values doc.

The third is the historical archive — sections explaining what the project used to do, what it was migrated from, what was tried and abandoned. This is useful for human onboarding and counter-productive for agents, who will sometimes treat the abandoned approach as a current option.

The fourth is the meta-section — rules about CLAUDE.md itself, like "keep this file under 200 lines" or "every rule should be falsifiable." These belong in your team's documentation about CLAUDE.md, not in the file the agent reads at session start. The agent does not benefit from being told the file's authoring rules.

The fifth is the duplicated rule — the same rule appearing in two sections because two people added it without seeing each other's edit. AgentLint catches these now, and most teams running it have removed the duplicates they had accumulated.

A 2026-shaped CLAUDE.md, in skeleton form

Here is the structure that has become the default for files written in 2026:

## 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.
Naming conventions the linter does not cover.

## Operational Notes (5-15 rules)
Surprising facts about the environment. Symlinks. Flaky CI steps.
Tokens that expire. Services that need warm-up.

## Communication (3-5 rules)
Language. Tone. Verbosity. Markdown vs plain.

## 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. Project-specific rules go inside; the skeleton stays under 100 lines on its own.

Where 2027 might go

Two trends are visible enough to flag. The first is machine-readable CLAUDE.md — projects experimenting with structured frontmatter and YAML-tagged sections so the file can be parsed deterministically by tooling. AgentLint and similar linters benefit from this; agents may benefit from it eventually. The risk is that the file becomes a config file in markdown clothing, which loses the prose readability that made CLAUDE.md valuable in the first place.

The second is CLAUDE.md as a contract. Some projects are pinning their CLAUDE.md as part of the PR contract — every PR has to either pass against the current file or amend the file. This treats the file as a versioned commitment rather than a living document. Still early, mixed evidence on whether it is worth the friction.

For now, in 2026, the disciplined defaults are the ones above. Short. Falsifiable. Enforced. Aligned across tools. Reviewed quarterly. AgentLint as the late-mile sweep. The teams that do these things have CLAUDE.md files that visibly carry weight; the teams that do not have files that drift quietly into the dead-letter pile. Pick the side of the divide you want to be on.

---

Originally posted on agentlint.app/blog/claude-md-best-practices-2026.