Stop LLMs From Overengineering Your Code

Your AI assistant just rewrote a five-line function into twenty, added a dependency, and wrapped everything in error handling that conflicts with the timeout logic three files over. The code runs. The tests pass. You're staring at a diff that solves a problem you didn't have.

Andrej Karpathy documented this pattern months ago: LLMs generate syntactically perfect code that fails because they miss hidden assumptions, overcomplicate simple fixes, and drift beyond the stated goal. The multica-ai/andrej-karpathy-skills repository turns his observations into configuration—a file that teaches Claude Code and Cursor to pause before generating solutions.

When Confidence Masks Missing Context

Ask an LLM to add retry logic to an API call, and it might introduce exponential backoff that violates an unstated latency requirement. Request a performance optimization, and it refactors three related functions when you needed a change to one bottleneck. The code works in isolation but breaks assumptions you never told the model about because you didn't realize they needed stating.

Karpathy's taxonomy breaks this into patterns: silent wrong assumptions embedded in implementations, solutions that ignore simpler paths in favor of complexity, edits that expand beyond the original scope, and outcomes difficult to verify without context. These aren't random—they're structural failure modes that emerge when a model optimizes for code correctness without surfacing tradeoffs.

Four Rules, Four Failure Modes

The repository implements four behavioral rules mapped to those patterns. Think Before Coding forces the model to surface assumptions before writing—instead of silently deciding how error handling should work, it asks whether the existing timeout strategy constrains that choice. Simplicity First counters over-complication by requiring justification for dependencies or abstractions before adding them. Surgical Changes restricts edits to the minimal scope needed, preventing feature creep when you asked for a bug fix. Goal-Driven Execution ties every change back to a verifiable outcome, so the model can't solve a problem you didn't pose.

Each rule translates philosophy into constraint. Before: the LLM generates a complete solution and you debug the assumptions afterward. After: it surfaces the assumption, proposes the simplest path, confirms the scope, and shows how you'll verify success—then writes code.

Configuration as Guardrail

The mechanism is straightforward. Claude Code reads project-level CLAUDE.md files at session start, loading the rules as constraints for that coding session. Drop the file in your repo root, and every Claude Code interaction in that project runs through the four-rule filter. The repository also ships a CURSOR.md variant for Cursor users, demonstrating the pattern transfers across tools—this isn't specific to Claude Code but a reusable approach to LLM guidance.

The PR #103 discussion shows the maintainers iterating on this: initial skill descriptions triggered too broadly, causing all four rules to load for most requests and defeating the modularity goal. They identified the problem, refined trigger logic, and documented the tradeoff. The kind of responsive maintenance that separates living tools from abandoned experiments.

When to Add Friction

These rules help when you need focused, minimal changes to existing code. They're less useful for greenfield exploration or when you want the model to propose multiple approaches without constraint. Adding steps trades speed for accuracy—sometimes you want the fast, messy first draft. The configuration is project-specific for a reason: apply it where overcomplicated diffs have burned you before, skip it when you're sketching.

The failure modes Karpathy observed aren't going away. A CLAUDE.md file that makes your AI assistant think before typing? That's addressable today.