CLAUDE.md Rules That Survive Production: What a Year Taught Us

The uncomfortable truth about CLAUDE.md files: most of them are wish lists. "Write clean code." "Always add tests." "Be careful with payments." The model reads them, nods politely, and the third time context gets tight, the wish list loses to whatever the immediate task wants. After a year of operating a 4,000-product store end-to-end on Claude Code, our instruction files stopped being wishes and became law — and the difference is not better prose. It is three properties: every rule has a scar, every rule is specific enough to obey mechanically, and the important ones are enforced by machinery that does not care what the model thinks.

Property one: rules need scars

Compare two versions of the same rule. Version A: "Be careful with bulk posting to social media." Version B: "NEVER post more than 20–30 times per day to ANY social platform. Mastodon suspended our account after 190 posts in 15 minutes — the API allowed it; the moderators flagged it as spam. API rate limits and moderation policy are different systems."

Version B works and version A doesn't, for a mechanical reason: the incident supplies the boundary conditions. A model reading version B knows the number (20–30), the failure mode (moderation, not rate limiting), and the reason the obvious objection ("but the API allowed it") is wrong. Version A leaves all three to judgment — and judgment under a long context window is exactly what you are trying not to rely on. Our AGENTS.md carries a dated incident for every hard rule: the deploy that broke checkout, the noindex that erased our traffic, the currency switch that silently dropped UPI payments for every Indian buyer. The date matters; it converts an instruction into a precedent.

Property two: mechanical specificity

A rule a model can obey without interpretation looks different from advice. Our deploy-invariants file has 31 of them, and the useful pattern is visible in any three: "no new Date() in sitemap lastmod." "Blog 301s go in blog-redirects.ts, never directly in next.config.ts." "Repo-root scripts/ never deploys; storefront/scripts/ does." Each names an exact file, an exact function, an exact prohibition. When a rule needs the phrase "use good judgment," it is not finished — keep asking "what exactly went wrong last time?" until the answer names a path and a behavior.

The same applies to positive procedure. Our definition of done is eight numbered lines, and the first three are commands with expected outputs, not aspirations: lint clean, typecheck clean, tests green. Line eight is the one that changed agent behavior most: "Report honestly: failures quoted verbatim, skipped steps named. 'Done' without evidence is a lie." Blunt language survives context pressure better than polite language — that is an observed fact about long sessions, not a style preference.