# Working principles for an AI coding agent (Claude Code CLAUDE.md) — decide by correctness not ROI; fix bugs at the architectural root, not the symptom > Source: > Published: 2026-06-07 21:49:07+00:00 **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 the*code*layer. This rule's "why" is**architectural**— why does the structure*permit*this 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 at**design** time, before any bug appears. That's a**preventive** trigger, and it has its own failure mode: speculative generality / type gymnastics for bugs that never actually happen. This rule is deliberately**reactive**— a*real*bug 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 a*presumed, unproven*need. 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 the*inverse*: invoking "YAGNI" or "premature optimization" to wave off a defect that*already exists*— which is why "How to decide" bars labelling a*known*-wrong thing "an edge case" or "not worth it."**Direction (subtract, not add).** Over-engineering*adds*— a layer of abstraction, a config knob, a generalization for callers who may never come. This rule's structural fix usually*removes*: 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 that*adds*speculative machinery also fails "How to decide"'s own test — does it*serve 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.