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

A developer published a CLAUDE.md configuration file for Claude Code that enforces two working principles: judge work by correctness rather than ROI, and fix bugs at the architectural root rather than the symptom. The rules require proving impossibility before stopping, and mandate root-cause analysis for every bug to eliminate entire bug classes.

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.