Key Takeaways
- Most CLAUDE.md files are wish lists.
- After a year running a 4000-product store on Claude Code, production rules share three properties: scars, mechanical specificity, and enforcement.
- Stop writing advice; start writing law.
The Uncomfortable Truth About Your CLAUDE.md
Your CLAUDE.md is probably a wish list. "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, one developer's instruction files stopped being wishes and became law. The difference isn't better prose. It's three properties.
Property 1: Every Rule Has a Scar
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. Version A doesn't. The incident supplies the boundary conditions. A model reading Version B knows the number (20–30), the failure mode (moderation, not rate limiting), and why 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're trying not to rely on.
Your move: Take your last real incident. Write it as one dated rule with a number in it. Put it where every session reads it. The date matters — it converts an instruction into a precedent.
Property 2: Mechanical Specificity
A rule a model can obey without interpretation looks different from advice. Compare:
- "No
new Date()in sitemap lastmod." - "Blog 301s go in
blog-redirects.ts, never directly innext.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's not finished — keep asking "what exactly went wrong last time?" until the answer names a path and a behavior.
This applies to positive procedure too. One team's definition of done is eight numbered lines. The first three are commands with expected outputs: lint clean, typecheck clean, tests green. Line eight changed 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's an observed fact about long sessions, not a style preference.
Your move: Audit your CLAUDE.md. Find every instance of "be careful," "use good judgment," or "prefer." Replace each with a number, a file path, or a specific prohibition.
Property 3: Enforcement Beats Instruction
The rules that matter most are not really in the Markdown at all — the Markdown documents them, but machinery enforces them. Any commit touching payment, auth, or webhook paths is blocked by a commit-msg hook unless the message carries an explicit acknowledgment that the security checklist was run. The pre-push hook runs a full production build; it cannot be argued with. Marketplace automation has its drip cap and halt-file circuit breaker in the code, so a confused agent cannot spam a platform even if it wants to.
The hierarchy: hooks and fail-closed code > auto-loaded rule files > session memory > logs. Prefer the strongest level that fits. A rule a hook enforces cannot be forgotten, and cannot be rationalized around at 2 a.m. by an agent that is very sure this one time is different.
Your move: Identify your three most critical rules. Add a git hook or CI check that enforces each one. The Markdown documents the rule; the hook enforces it.
The Structure That Emerged
Nobody designs this up front; it accretes. But after a year, a repeatable shape emerged:
- CLAUDE.md — the operating system: model tiering, decision engine (when to plan, when to spawn a verifier, when to stop and ask), failure laws, definition of done.
- AGENTS.md — the hard rules with their scars.
- Path-scoped rule files — load only when relevant paths are touched, keeping token cost sane. The SEO checklist loads for public pages, the trust-boundary gate for payment code.
One habit binds it together: every incident becomes a rule within the hour, at the strongest enforcement level that fits. The incidents that recur are precisely the ones where this loop didn't run.
Try It Now
Start smaller than any of that. Take your last real incident — the deploy that broke checkout, the noindex that erased your traffic, the currency switch that silently dropped payments. Write it as one dated rule with a number in it. Put it in your CLAUDE.md where every session reads it.
That single habit, compounded for a year, is the whole system.
Source: dev.to
