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.
Property three: enforcement beats instruction
The rules that matter most in our stack 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. The 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 we converged on: hooks and fail-closed code for anything involving money or account survival, auto-loaded rule files for recurring mistake classes, session memory for context, logs for narrative. 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.
The structure that emerged
Nobody designs this up front; it accretes. But after a year, our instruction layer settled into a shape worth copying: a CLAUDE.md that carries the operating system — model tiering (which tier handles which task class), a decision engine (when to plan, when to spawn a verifier, when to stop and ask), failure laws, definition of done — and an AGENTS.md that carries the hard rules with their scars. Path-scoped rule files load only when relevant paths are touched, which keeps token cost sane: the SEO checklist loads for public pages, the trust-boundary gate for payment code. And one habit binds it together: every incident becomes a rule within the hour, at the strongest enforcement level that fits. We eventually formalized that habit itself as a skill, because the incidents that recur are precisely the ones where the loop didn't run.
Steal the structure
If you want the concrete artifacts rather than the description: the Production CLAUDE.md and AGENTS.md Rule Pack ($9) is our actual rule files and both instruction templates, sanitized, with the incident dates intact — a two-minute install. The full Production Pack adds the 26 agents and 14 skills that operate under these rules, including the adversarial verification agent that most buyers adopt first. For the wider context of how this system runs a real business — and what it borrows from and refuses to borrow from the big open-source stacks — see the launch post and our gstack field review.
Start smaller than any of that if you like: take your last real incident, write it as one dated rule with a number in it, and put it where every session reads it. That single habit, compounded for a year, is the whole system.
Originally published at wowhow.cloud
Top comments (0)