Paste this alongside any rule you're about to add to a CLAUDE.md file (global or project-level) and ask whether it passes all eight checks.
You are editing a CLAUDE.md file (global or project-level). Before finalizing any addition, edit, or new file, run it through these checks:
-
STATE THE FACT, DON'T SPECIFY THE PROCEDURE Would a reasonably competent agent get this right on its own, once told the one thing it's currently missing? If yes, write just the fact — not a decision tree, not a multi-step reasoning process, not an approval gate. A rule that explains how to decide instead of stating what's true is usually over-specified. Trust judgment once informed; don't replace it with a procedure.
-
FOLD IN, DON'T STACK ON Before adding a new heading, check whether an existing section already owns this moment or category of decision. Related conditions that get evaluated together belong in one place, not scattered across separate headers. New sections cost structure and framing overhead every time the file loads; prefer merging into what's already there.
-
CONDITION-FIRST PHRASING Phrase rules as "[condition]? [response]." rather than "When X happens, you should Y." This keeps the model evaluating a judgment call instead of pattern-matching a checklist — terse, condition-led phrasing is a feature here, not just a way to save space.
-
CUT RESTATEMENT, KEEP LOAD-BEARING JUSTIFICATION Remove words that repeat what was just said in different phrasing ("which means," "in order to," "note that," "it's important that"). Keep a justification only if it changes behavior in an edge case or tells the model how to recognize the condition — cut it if it's purely restating the instruction.
-
THRESHOLD-GATE ANY CONFIRMATION, NEVER MAKE IT UNIVERSAL If a rule involves pausing for human approval, tie it to a specific, stated threshold or condition — never "always confirm before X." A universal approval gate gets rubber-stamped into uselessness over time and rarely addresses the actual failure that prompted it.
-
FIX THE NARROWEST THING THE INCIDENT DEMONSTRATED After something goes wrong, resist writing the broadest rule that would have prevented it. Write the rule that addresses exactly what happened. Overcorrection (excess process) is the same class of error as undercorrection (no rule at all) — both carry a recurring cost, paid every time the file loads, whether or not that session needed it.
-
CHECK SCOPE: GLOBAL VS. PROJECT Is this true across all your work, or specific to one codebase's stack, team, or conventions? A global file should hold only what survives that test; anything narrower belongs at the project level instead.
-
FINAL PASS: CONSISTENCY AND ACCURACY Check tense, capitalization, and formatting match the rest of the file. Re-verify any numbers, thresholds, or claims against whatever actually happened — don't let a specific figure drift from the case that justified it.
Output: the smallest diff that satisfies all eight checks — not a rewrite of the whole file unless the change genuinely touches that much of it.
Why this exists: a CLAUDE.md file is a recurring cost - every line in it loads on every session, whether or not that session needed the rule. It's easy to overcorrect after a bad session (adding a broad new procedure) just as it's easy to under correct (never writing anything down at all). Both failure modes are common, and both are avoidable with the same discipline: state the narrowest true thing, prefer facts over procedures, and fold new rules into existing structure instead of growing new sections.
This isn't specific to any one kind of rule (cost, testing, style, git workflow, delegation, or anything else) - it's a way of thinking about
how to write instructions for an agent, independent of what the instructions are about.
Usage: paste your candidate rule plus the prompt above into a session and ask "does this pass all eight checks - if not, what's the minimal fix?" Treat it as a gate to run additions through, not a style guide to memorize.
Living document - the checks reflect what's worked so far, not a finished methodology. If you find a real gap, extend it.