Prevent coding agents from inflating code with guesses
Have you experienced confusion caused by AI adding unrequested features or touching code it does not understand? This repository is a single file containing four principles for AI coding tools, based on Andrej Karpathy's observations. Applying this file to your project encourages the AI to ask questions instead of guessing and to write only the minimum necessary code.
Problems with AI coding tools
Karpathy points out that LLMs often misinterpret user intent and proceed without confirmation. He also notes a tendency to make code overly complex or abuse unused abstractions. In some cases, they arbitrarily modify or delete comments or code unrelated to the task. These behaviors clutter the codebase and make maintenance difficult.
Four behavioral principles
This repository proposes four principles to address these issues.
- Think before coding Make assumptions explicit rather than hiding them, and ask questions instead of guessing when parts are ambiguous.
- Prioritize simplicity Exclude additional features or abstractions beyond the requested functionality, avoiding a level of complexity that a senior engineer would deem excessive.
- Precise modifications Do not arbitrarily improve nearby code or comments; only clean up code that becomes unnecessary due to your changes.
- Goal-based execution Set verifiable success criteria instead of imperative instructions, and iterate until tests pass.
Installation and application
Installing it as a Claude Code plugin applies these guidelines to all projects. Add the marketplace with the plugin marketplace add command, then install it with the plugin install command. To apply it to individual projects, download the CLAUDE.md file or add it to an existing file. If you use Cursor, you can apply the same guidelines through its rule file.
Considerations for application
Because these guidelines prioritize caution, they may be excessive for simple typo fixes or one-line changes. The goal is to reduce costly mistakes in important tasks, not to slow down every task. If your project has specific rules, merge these guidelines into your existing CLAUDE.md. It is released under the MIT license, allowing free modification and use.
