Is Claude Overkill? Adding Anti-Over-Engineering Directives to CLAUDE.md

Fazm Team··2 min read

Is Claude Overkill? Adding Anti-Over-Engineering Directives to CLAUDE.md

You ask Claude to add a button. It refactors your entire component hierarchy, introduces a new design pattern, adds three utility functions, and creates a constants file. The button works, but now you have 200 lines of changes to review instead of 10.

The Over-Engineering Problem

Claude Code has a tendency to "improve" things it was not asked to touch. This manifests in several ways:

  • Scope creep - fixing unrelated code while implementing your requested change
  • Premature abstraction - creating generic solutions for one-off problems
  • Refactoring without asking - restructuring working code because it could be "cleaner"
  • Adding error handling you did not request - wrapping everything in try/catch blocks

Each individual change might be reasonable in isolation. But combined, they make code review painful and introduce unnecessary risk. You asked for a button, not a framework.

The Fix That Works

Add this to your CLAUDE.md:

## Development Rules
- Avoid over-engineering. Only make changes that are directly requested.
- Do not refactor existing code unless explicitly asked.
- Prefer simple, direct solutions over abstract patterns.
- If a change requires touching more than the requested scope, ask first.

This simple directive dramatically changes Claude's behavior. It constrains the agent to your actual request and prevents the "while I am here, let me also..." pattern that creates sprawling diffs.

Why This Matters for Parallel Agents

When running multiple Claude agents in parallel, over-engineering compounds. Agent A refactors a shared module. Agent B refactors the same module differently. Now you have merge conflicts in code neither agent was asked to touch. Keeping each agent narrowly scoped prevents this.

The Right Balance

Claude's instinct to improve code is not always wrong. Sometimes you want it to notice a bug nearby or suggest a better pattern. The key is making improvement opt-in rather than the default. Your CLAUDE.md should make it clear: do what is asked, nothing more, and suggest improvements separately.

Fazm is an open source macOS AI agent. Open source on GitHub.


More on This Topic

Related Posts