{"slug": "working-principles-for-an-ai-coding-agent-claude-code-claude-md-decide-by-not-at", "title": "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", "summary": "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.", "body_md": "**To adopt:** copy the block below into your `~/.claude/CLAUDE.md`\n\n.\n\n```\n## How to decide what to do\n\nJudge 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.)\n\nThe 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.\n\nPresent choices to me by correctness and feasibility (real impossibilities, real *capability* tradeoffs like portability or expressiveness), not by ROI.\n\n## Fixing bugs\n\nAssume 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.\n\nPrefer 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.\n\nThis 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.\n```\n\n*(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.*\n\n**Fixing bugs** splits across two layers, and each differs from the familiar version:\n\n*\"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.\n\n**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:\n\n**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.\n\n**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.\n\n**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.", "url": "https://wpnews.pro/news/working-principles-for-an-ai-coding-agent-claude-code-claude-md-decide-by-not-at", "canonical_source": "https://gist.github.com/johnsoncodehk/6f6b9892936f335e491e92b65646fbea", "published_at": "2026-06-07 21:49:07+00:00", "updated_at": "2026-06-13 15:45:06.656796+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "large-language-models"], "entities": ["Claude Code", "CLAUDE.md"], "alternates": {"html": "https://wpnews.pro/news/working-principles-for-an-ai-coding-agent-claude-code-claude-md-decide-by-not-at", "markdown": "https://wpnews.pro/news/working-principles-for-an-ai-coding-agent-claude-code-claude-md-decide-by-not-at.md", "text": "https://wpnews.pro/news/working-principles-for-an-ai-coding-agent-claude-code-claude-md-decide-by-not-at.txt", "jsonld": "https://wpnews.pro/news/working-principles-for-an-ai-coding-agent-claude-code-claude-md-decide-by-not-at.jsonld"}}