Why Your AI Keeps Going Off‑Track: The 4 Essential CLAUDE.md Directives

In 2026 the AI programming landscape entered a rapid iteration phase, with Anthropic releasing Claude Opus 4.7 and OpenAI enhancing Codex Agent. Despite the surge, many developers notice AI‑generated code frequently "runs off track" by making unchecked assumptions and modifying code without clarification.

The author cites Andrej Karpathy’s insight that the biggest problem of large language models (LLMs) is not their inability to write code, but their inability to manage their own uncertainty. Models tend to continue execution based on erroneous assumptions, never asking for clarification, exposing trade‑offs, or admitting uncertainty.

To address this, a popular GitHub repository introduced a CLAUDE.md file containing only four behavioral rules:

Don’t assume. Don’t hide confusion. Surface trade‑offs.

Write the minimum code that solves the problem. No speculation.

Touch only what you must. Clean up only your own mess.

Define success criteria. Loop until verified.

These rules are translated into plain language as: (1) avoid hallucinating requirements and expose uncertainty; (2) produce only the code needed for the current task; (3) modify only the necessary parts; (4) set clear success criteria and verify repeatedly.

Examples illustrate the failure mode. When asked to “export user data”, an AI agent immediately generates code that assumes JSON format, exports all users, writes to disk, and ignores pagination or sensitive data, without asking any clarifying questions. The correct approach, as shown, is to first ask a series of concrete questions about scope, format, sensitivity, and delivery method before writing any code.

The article also demonstrates over‑design: a simple discount calculation request leads an AI to generate an entire enterprise‑level architecture with strategy patterns, factories, and wrappers, resulting in hundreds of lines of code when a few lines would suffice. This over‑design inflates code complexity, slows reviews, introduces bugs, and raises maintenance costs.

Rule three (minimal touch) prevents unnecessary diff size. The author shows a buggy PR where the AI fixes a bug but also reformats quotes, reorders imports, and adds unrelated validations, expanding a three‑line fix into a 40‑line diff, dramatically increasing review effort.

Rule four (verifiable success) emphasizes that an advanced agent should write failing tests, reproduce the bug, fix the issue, and verify that all tests pass, rather than simply “view‑code → fix → test → done”. This looped verification aligns the model’s autonomous capabilities with engineering rigor.

The article warns against adding too many rules, which can dilute context and cause rule conflicts. It advocates a concise CLAUDE.md structure that combines behavioral rules, project commands, conventions, and watch‑outs, keeping the file short enough to fit within token limits.

Finally, the author distinguishes between technical constraints (e.g., "must use Java 21") that tell the AI *what* to do, and behavioral constraints that tell the AI *how* to think. Properly crafted behavioral rules give AI the missing engineering judgment, improving code quality and reducing post‑generation review costs.