Back to Blog

Working Around Claude Code's Anti-Over-Engineering Bias

Fazm Team··2 min read
claude-codedeveloper-toolssystem-promptbuild-configurationworkaround

Working Around Claude Code's Anti-Over-Engineering Bias

Claude Code has a system prompt instruction that tells it to avoid over-engineering. In most cases this is helpful - it keeps generated code simple and readable. But when you have specific, detailed build instructions that look complex but are actually necessary, Claude will decide they are "unnecessary complexity" and simplify them into something that does not compile.

The Problem

Here is what happens in practice. You write a CLAUDE.md with precise build flags, specific linker settings, or a particular file organization pattern that your project requires. Claude reads it, decides it is over-engineered, and produces a "simplified" version that:

  • Drops essential compiler flags
  • Combines files that need to be separate for build system reasons
  • Removes "redundant" configuration that is actually platform-specific

The result does not build. You correct it. Claude re-simplifies. You correct it again. This loop can repeat several times before the agent respects your specific requirements.

The Workaround

The solution is explicitly signaling in your CLAUDE.md that certain sections are intentional and must not be simplified:

## Build Configuration (DO NOT SIMPLIFY - THESE ARE ALL REQUIRED)

The following flags are required for Apple Silicon compatibility.
Removing any of them will cause linker errors:

- `-framework Accessibility` (required for AXUIElement APIs)
- `-framework ScreenCaptureKit` (required for SCStream)

Prefixing critical sections with phrases like "THIS IS NOT OVER-ENGINEERING" or "DO NOT SIMPLIFY" works because it directly addresses the instruction Claude is following. You are telling it that you are aware of the simplicity principle and that these specific details are not violating it.

Better Approaches

Beyond the prefix hack, structuring your CLAUDE.md helps:

  • Explain why each requirement exists. Claude is less likely to remove something when it understands the reason.
  • Include the error message. Write "Removing this flag causes: ld: framework not found" and Claude will leave it alone.
  • Use code blocks for exact values. Free-form descriptions get reinterpreted. Code blocks get preserved.

More on This Topic

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

Related Posts