andrej-karpathy-skills: a profile to standardize and optimize AI code generation behavior

forrestchang/andrej-karpathy-skills is an open-source developer tools project with immense popularity on GitHub that aims to thoroughly address common behavioral flaws in automatic code generation by Large Language Models (LLMs) and AI code intelligences such as Claude Code. Founded by developer Forrest Chang, the project's core inspiration comes directly from renowned AI expert Andrej Karpathy's viral observations and summaries of AI programming pitfalls.

In AI-assisted programming, coding intelligences are often overconfident, with a habit of making “silent assumptions”, introducing unneeded complexity without authorization (over-engineering), making unfocused formatting changes, and lacking clear criteria for success verification. This project addresses these pain points by distilling them into a minimalist, yet highly controllable, framework. CLAUDE.md Profiles. By introducing four core behaviors - “think before you code,” “simplicity first,” “surgical modification,” and “goal-driven execution” - it instantly transforms AI from a spontaneous “intuitive coder” to a disciplined and logical “goal-driven execution. ”and goal-driven execution, it instantly transforms AI from spontaneous "intuitive coders" into disciplined, logical "advanced software engineers". It instantly transforms AI from a casual "intuitive coder" to a disciplined, logical "advanced software engineer". Developers only need to introduce this file into the code base, you can significantly reduce the cost of AI code review, effectively avoid the error cascade, and greatly improve the overall code quality and development efficiency of the project.

Function List

• Think Before Coding: Force AI intelligences to explicitly declare their thinking assumptions before writing any code. If it is unsure or encounters multiple implementation paths, the AI will proactively present tradeoffs to the developer and ask for them, completely eliminating self-inflicted bad guesses.
• Forced Simplicity First: Minimalist constraints on AI's code output. Over-engineering is eliminated by explicitly prohibiting AI from generating additional functionality not explicitly requested, single-use abstraction layers, or writing redundant error handling logic for unlikely scenarios.
• Surgical ChangesStrictly define the scope of code modification by AI to ensure that it only touches the lines of code necessary to solve the problem. Prohibit AI from refactoring undamaged code modules or changing irrelevant code indentation and formatting, so as to perfectly maintain the existing code style of the project.
• Goal-Driven Execution: Require the AI to translate ambiguous instructions into self-verifiable goals. Before and after modifying the code, the AI is forced to write and run test cases autonomously, and never stops until it reaches the success criteria, forming a complete test-to-fix automated loop.
• Highly compatible and seamlessly integrated: Native compatibility Claude Code CLI tool that utilizes project-level CLAUDE.md file mechanism, without the need for complex environment configuration can be globally effective under the current code base.
• Automated installation supportIn addition to providing basic file downloading and copying, it also supports one-click injection of skill packages into the development environment via modern package management and execution tools such as npm, npx, bunx, and so on.

Using Help

forrestchang/andrej-karpathy-skills The core value of AI Code Assistant lies in its extremely low cost of access and extremely high behavioral constraint benefits. In order to make AI Code Assistant truly your reliable engineering partner, please be sure to read the following detailed installation process and core features operation guide carefully. This guide will help you minimize the uncontrollability of AI.

I. Detailed installation and configuration process

Depending on the development environment and tools you are using, this project offers two extremely easy ways to install it. Either way, the essence is to distribute the underlying rules file of the project down to your workspace.

Way A: Automated installation from the command line (highly recommended for users of the Claude Code CLI)
If you're already using an end-code smartphone that supports the Skills Marketplace, you can introduce these guidelines with a single click directly from the Package Manager:

1. Open your Terminal tool (Terminal).
2. Navigate to the root directory of your target software project.
3. Enter and execute the following command for global installation:
   npx skills add https://github.com/forrestchang/andrej-karpathy-skills --skill karpathy-guidelines
   (Note: If you are using bun or pnpm, you can replace npx with bunx or pnpm dlx.)
4. Once installed, the skill module will automatically take effect in your backend, taking over the flow of all subsequent commands involving code generation and refactoring.

Way B: Pure manual native access (for all IDEs that support project-level system prompt words, such as Cursor, Windsurf, VSCode, etc.)
If you don't need complex command line tools, or want to force these rules to be applied in a specific IDE, manual configuration is the most transparent and reliable approach:

1. Locating the Project Root Directory: Open your code editor and go to the root directory of the project you are currently developing.
2. Creating a Rules File: Create a new blank Markdown file in the root directory, strictly named CLAUDE.md. If you are using the Cursor Tools such as .cursorrulesThe underlying logic is fully interoperable.
3. Get source code: Visit the GitHub project homepage https://github.com/forrestchang/andrej-karpathy-skillsI'm not sure if I can find the warehouse. CLAUDE.md Original Document.
4. Copying and saving: Select the text of the four core principles in the document, copy it, paste it into the file you just created locally, and press save. That's it, your AI has been re-brainwashed and trained.

II. Demonstration of core function operation and daily development flow

Once installed, the real magic is reflected in your daily interactive dialog with the AI. Here are suggestions and expected results for four common development scenarios:

1. Enabling “think before you code”: dealing with ambiguous requirements development

• operating method: When you're developing a new feature, don't give extremely tight, long-winded statements, just type in a natural request. For example, “Please help me add a feature to export user data as an Excel report.”
• AI Behavior ChangeBefore this document, the AI would have introduced third-party libraries, written dozens of lines of complex code, and even taken the liberty of querying the database. Once the rule is introduced, the AI will immediately “put on the brakes” and reply to the terminal with:“In order to realize the export function, I have the following questions and assumptions: 1. Assuming that only the data of the currently active user needs to be exported. 2. May I ask if it is permissible to bring in the xlsx library, or are you asking to use a pure native CSV format instead to minimize dependencies? Please confirm before I start writing.”
• Your operation: A short response based on the options listed by the AI is all that's required. This one-question, one-answer confirmation kills invalid code at the source.

2. Practicing “simplicity first”: avoiding a rapidly expanding code base

• operating method: Daily Question “Help me write a time formatting function that converts timestamps to YYYY-MM-DD.”
• AI Behavior ChangeAIs often write time zone conversion, multi-language support, and even a whole set of time processing classes to demonstrate their capabilities. Under the “simplicity-first” rule, the AI will output only a few lines of native Date Streamlined functions for object handling logic without any nonsense and interface extensions beyond what is expected.
• Tips: If you feel that AI is still complicated to write, simply reply with the phrase: “Review guideline #2 (Simplicity First) and reduce your 100 lines of code to less than 20 lines.”

3. Experience “surgical modification”: fixing bugs very quickly without triggering merge conflicts

• operating method: When an error is reported, you type: “fix auth.js Program crash on line 45 due to null pointer.”
• AI Behavior Change: AI will act like an experienced surgeon, pinpointing and only using ? (optional chain operator) or if It will not change the target line because it doesn't look good to you. It will never adjust the indentation of line 10 because it doesn't look good to you, nor will it refactor the structure of the code around it because of so-called “best practices”.
• Earnings assessment: This allows you to perform git diff When reviewing the code, the change history seen is extremely clean and contains only the core logic that solves the problem.

4. Driving the “closed loop of target validation”: automated reliability assurance

• operating method: Enter the higher-order directive: “Refactor the current cache loading logic to require a goal-driven principle.”
• AI Behavior Change: AI will automatically take your fuzzy commands apart. It will first go find or write a test script against the old cache logic and execute it once to make sure the test passes; then it will start replacing the underlying code; and when it's done it will automatically re-run the test. Only when you see the green PASS flag before it reports back to you, “Refactoring complete, tests not degraded.” This closure of the loop reduces the probability of a system crash to a very low level.

III. Advanced customization techniques

该 CLAUDE.md The document is an excellent base template that you can flexibly expand twice according to team specifications. It is recommended that at the bottom of the document you add ### 5. 团队定制规范 (Team Customs) Module.
For example, you could include it at the bottom of the document:
“All components must use the React Functional components with accompanying TypeScript interface definitions.”
or “It is strictly forbidden to introduce absolute paths directly in the project, please use uniformly the @/components/ the alias configuration.”
With this overlay configuration, you not only lock down the AI's behavioral bottom line, but also empower it with an awareness of the team's business norms, making the AI truly an indispensable super-assistant for your development team.

application scenario

1. Minimalist development of daily business functions
   When developing brand new business modules, prevent AI from over-designing the system architecture in order to demonstrate capabilities. Mandate that AI address current business claims with the least and most straightforward code to avoid incurring unnecessary maintenance liabilities.
2. Secure Refactoring of Large Legacy Codebases
   Utilize “surgical modification” scenarios when faced with large and uncommented libraries of legacy code. Ensure that the AI intelligences only fix the specified logic flaws, without destroying the fragile ecosystem of old code and specialized formats around them, preventing the entire system from being affected.
3. Troubleshooting and accurate fixing of complex bugs
   When encountering problems that are difficult to reproduce, apply the “eliminate silent assumptions” scenario. Let the AI put all the possible causes of failure and default assumptions of the system environment on the table, and through the confirmation of alignment with the developer, find the lesions at once.
4. High quality code review and quality control
   As a reference line for AI-assisted review within the team. Before the AI agent is ready to commit the code, it triggers the “target validation closure”, requiring it to be accompanied by automated test cases that can be passed in order to be regarded as completing the task, and guaranteeing the high quality of the main branch code.

QA

1. Question: What is forrestchang/andrej-karpathy-skills? How is it fundamentally different from normal AI system prompt words?
   Answer: This is an open source behavior control profile that distills the experience of leading AI experts. While normal prompts tend to focus on what the AI “knows” (e.g., tech stack requirements), this file focuses on constraining the AI “how it behaves” (e.g., don't hide doubts, don't show off, don't make extensive changes). It reshapes the working habits of AI intelligences from a behavioral psychology perspective.
2. Question: Does this profile only work with the Claude Code command line tool? Will it work for me with Cursor or GitHub Copilot?
   Answer: although its named CLAUDE.mdThe Cursor is designed primarily for Claude Code, but the core Markdown principles are completely universal. You can copy these principles directly into the Cursor's .cursorrules file, or as a GitHub Copilot / ChatGPT Item-level system cue words to use are just as effective.
3. Question: If the AI still makes the wrong silent assumption after introducing the file, how do I adjust it?
   Answer: since there is some probabilistic output from LLM, if a violation occurs, you can simply correct it harshly in the dialog box, “You have violated the first principle in CLAUDE.md, please back out of your code and list your assumptions to me first.” This kind of criticism, based on a pre-existing rules file, allows the larger model to quickly correct its subsequent attention weights.
4. QUESTION: Will forcing AI to think and ask before writing code dramatically reduce the speed of generating code?
   Answer: In the short term, it looks like an extra step in communication, but that's what Karpathy emphasizes when he says, “Sharpening the knife is not the only way to get the job done.” It's far less efficient for an AI to instantly generate hundreds of lines of buggy code and have you spend two hours troubleshooting them than it is for it to stop and spend 10 seconds asking you a critical question. Overall, it dramatically reduces the amount of time spent reworking and debugging code, thereby substantially improving development efficiency.