To adopt: copy the block below into your ~/.claude/CLAUDE.md
.
## How to decide what to do
Judge every piece of work by whether it **should** be done — is it correct, is the current state wrong or inconsistent, does it serve the goal — and **never by ROI, cost, effort, or "is it worth it."** Do not label a known-wrong thing "low-value," "marginal," "an edge case," or "not worth it" to justify leaving it unfixed; reasoning by ROI is exactly what keeps work mediocre. ("The reference / competitor also gets it wrong" is a *gap* argument, not a correctness one — it never makes a wrong thing acceptable.)
The only valid reason to stop short of doing the right thing is that it **provably cannot** be done — a demonstrated limit of the model or tools, not an assumed or cost-based one. "Hard," "heavy," "expensive," or "a lot of work" is never a reason to stop; "proven impossible / blocked" is. When unsure which it is, find out — try it, measure it, prove it — before deciding, and never declare a limit you have not proven.
Present choices to me by correctness and feasibility (real impossibilities, real *capability* tradeoffs like portability or expressiveness), not by ROI.
## Fixing bugs
Assume a correct architecture has no bugs — so every bug is evidence that the architecture *permits* it to exist, not merely that one code path is wrong. **Before fixing any bug, first diagnose the root cause: ask why the architecture allowed this bug to exist at all,** and whether it is one instance of a whole *class* of bugs the same structure would keep producing.
Prefer fixes that remove the structural condition that let the bug exist — so this bug and others like it can no longer occur — over patches at the symptom layer (a guard, a special case, or a workaround that leaves the enabling structure in place). Reach for a symptom-layer patch only when the root-cause fix is **provably** infeasible or genuinely belongs in a separate change, never merely because it is larger or harder; when you do, say so and name the root cause you are deferring.
This is a thinking-first rule, not a mandate to refactor on every fix: the root-cause analysis is **always** required; reshaping the architecture to act on it is frequent but conditional on its being the right and feasible move.
(Commentary — not part of the rules above; don't copy this into your CLAUDE.md.) Neither rule is new; both have a long lineage. What's below is where each one sits relative to the familiar versions, and where it genuinely differs.
Fixing bugs splits across two layers, and each differs from the familiar version:
"Find the root cause, not the symptom"is old advice, but the usual phrasings — including agent-facing ones like"if the fix doesn't explain why the bug happened, it's not the fix"— under-specify the**"why."** Their "why" is satisfied by any link in the causal chain ("the value was null"), which stops at thecodelayer. This rule's "why" isarchitectural— why does the structurepermitthis whole class? — and the one-liners quietly collapse it back to the layer this rule is trying to get past."Remove the structural condition so the class can't recur"is the neighborhood of making illegal states unrepresentable — killing the class atdesign time, before any bug appears. That's apreventive trigger, and it has its own failure mode: speculative generality / type gymnastics for bugs that never actually happen. This rule is deliberatelyreactive— arealbug is what authorizes the structural fix, which means it tolerates the class's first instance and only then dismantles the structure. Same lever (structural), opposite trigger: cousins, not upgrades.
Isn't "tear out the structure to kill a whole bug class" just premature optimization / over-engineering? It's the objection "Fixing bugs" most invites, and the honest answer is that this rule sits on the same side as premature optimization and YAGNI — not opposite them. It differs on two separate layers, and the difference holds on both:
Trigger (reactive, not speculative). Premature optimization and YAGNI both forbid building for apresumed, unprovenneed. This rule's reactive trigger — above — never moves on a presumed bug either. Same measuring stick —is the problem proven real right now?— so it's an ally of YAGNI, not a counterexample. The genuine trap is theinverse: invoking "YAGNI" or "premature optimization" to wave off a defect thatalready exists— which is why "How to decide" bars labelling aknown-wrong thing "an edge case" or "not worth it."Direction (subtract, not add). Over-engineeringadds— a layer of abstraction, a config knob, a generalization for callers who may never come. This rule's structural fix usuallyremoves: it deletes the condition that let the bug exist, leaving less structure, not more. Gold-plating makes the system more complex on spec; this makes it simpler on evidence. A change thataddsspeculative machinery also fails "How to decide"'s own test — does itserve the goal— so the rule can't be read as a licence to gold-plate.
How to decide runs against the grain of the dominant framing rather than having no ancestors. The prevailing technical-debt narrative treats shortcuts as a deliberate, ROI-weighed trade-off ("ship now, pay later, just don't over-borrow") — though even that framing admits inadvertent debt, so "everyone treats it as a trade-off" would overstate it. The older counter-tradition refuses to let cost of production be the criterion for what gets built — and the craftsmanship strain makes that refusal a professional duty. So this is not a stance no one has held; it's been said cleaner and earlier. What's left as this rule's own contribution is narrower and operational: it bans ROI specifically as the decision criterion for whether a known-wrong thing gets fixed, written as a rule an agent runs every turn — not as a statement of values.
Bottom line: neither rule is novel; both are a known lineage, sharpened and made operational for an agent. Where they genuinely differ from the familiar versions: the architectural "why," the reactive trigger, and ROI barred as a decision criterion rather than merely deprecated. The point isn't novelty — it's having them always on.