One line in CLAUDE.md that breaks Claude's over-engineering reflex
Dev.to / 6/2/2026
💬 OpinionIdeas & Deep AnalysisTools & Practical Usage
Key Points
- The author describes how Claude repeatedly over-engineered solutions, using complex architectures (e.g., strategy patterns, registries, and multiple integration tests) even when a simpler multi-line function would suffice.
- After clearing the project, the “reframing” guidance did not persist, prompting the author to add a standing convention to CLAUDE.md to prevent the reflex from returning.
- The added rule states: default to the smallest change that fits, and only introduce abstractions after a second occurrence, never the first.
- The author explains why the wording matters—using “Default to” instead of “Avoid,” “that fits” instead of “smallest,” lowering Fowler’s “third time” to “second occurrence,” and using “Never the first” to create deliberate friction for exceptional cases.
- The article frames the convention as a way to keep the agent and the human from converging on unnecessary abstractions under session pressure.
Continue reading this article on the original site.
Read original →
