karpathy-guidelines: Four Principles That Make AI Write More Reliable Code

目录

“The biggest enemy of an LLM writing code isn’t that it can’t write, but that it writes too much, thinks too little, and changes things too messily.” — This is Andrej Karpathy’s summary after observing a large number of cases of AI-assisted programming.

Recently, while organizing my own AI development toolchain, I found a very interesting project on GitHub: andrej-karpathy-skills. It distills Karpathy’s observations about LLM coding pitfalls into a set of behavioral guidelines that can be directly injected into an AI Agent. After installing it, I realized this isn’t just a “prompt template,” but a systematic methodology about “how to make AI write code more reliably.”

In this article today, let’s talk about what this project actually does, and what problems it can help us solve in our daily development.

Project Background: What Problem Did Karpathy Discover?

Who Andrej Karpathy is needs no introduction—former Director of AI at Tesla, founding member of OpenAI, and now one of the most influential people in AI education. He often shares his observations about AI programming on X (Twitter).

Earlier this year, he posted a tweet to the effect that: for LLMs assisting with programming today, there are several recurring error patterns:

• Over-engineering: the user wants a script, but the AI delivers a whole framework
• Silent assumptions: when faced with ambiguous requirements, it doesn’t ask—it just writes according to its own understanding
• Indiscriminate changes: while modifying, it “optimizes” unrelated code in passing
• Unclear goals: it runs once it’s done, without verifying whether it actually solved the problem

Each of these problems isn’t fatal on its own, but stacked together, they can turn AI-assisted programming from an “efficiency booster” into a “technical-debt factory.”

The karpathy-guidelines project distills these observations into four actionable behavioral principles, packaged as a Skill, so that the AI Agent automatically follows them while coding.

What Does This Skill Do?

Put simply, karpathy-guidelines is a behavioral-guidelines package for AI. After installation, when you have the AI handle a coding task, it automatically follows these four principles:

1. Think Before Coding
2. Simplicity First
3. Surgical Changes
4. Goal-Driven Execution

It isn’t a tutorial teaching you to write code, nor a specification for any particular language—it’s a set of meta-rules about “how to use AI to write code correctly.”

Detailed Look at the Four Core Principles

1. Think Before Coding: Don’t Assume, Don’t Hide Confusion

The core of this principle is: before starting to write code, stop and think it through first.

The specific requirements include:

• Make assumptions explicit: if requirements are ambiguous, don’t guess—raise it
• Present choices: if there are multiple ways to implement something, list the pros and cons for the user to choose; don’t silently decide
• Favor simplicity: if there’s a simpler approach, proactively say so, and push back when necessary
• Dare to ask: when you hit something unclear, stop, name the confusion, and then ask

I have a particularly deep feeling about this one. In the past, when using AI to write code, I often found it “too considerate”—faced with ambiguous requirements, it would automatically fill in an assumption and then write a pile of code based on it. The result was often: the code was written well, but it wasn’t what I wanted.

This principle is installing a “pause button” on the AI: when unsure, ask first, then write.

2. Simplicity First: Minimal Code to Solve the Problem

This principle may be the most counterintuitive of the four, because its requirement is: if 50 lines can solve the problem, don’t write 200.

The specific constraints:

• Add no unrequested features: if the user asks for A, give only A; don’t hand over B, C, and D in passing
• Don’t abstract one-off code: something used only once doesn’t need to be wrapped into a general-purpose module
• Add no unrequested “flexibility”: don’t introduce config options for “possible future needs”
• Don’t handle errors that can’t happen: over-defensive programming is also over-engineering

Karpathy’s own words: “If you write 200 lines and it could be 50, rewrite it.”

This principle directly targets a core problem with LLMs: because the training data is full of “production-grade code,” the AI tends to complicate simple things. For a simple data-conversion script, it may add logging, configuration, exception handling, unit tests… when really you just wanted to run a one-off task.

3. Surgical Changes: Only Touch What Must Be Touched

This principle is about how to modify existing code:

• Don’t change adjacent code: don’t “conveniently” optimize the code, comments, or formatting next to it
• Don’t refactor what isn’t broken: if it works, leave it alone unless the user explicitly asks
• Match the existing style: even if your style differs, stay consistent
• When you find dead code, mention it but don’t delete it: unless it resulted from your own change

There’s also a very fine point: if your change causes some import/variable/function to no longer be used, you’re responsible for cleaning up these “orphans”; but pre-existing dead code, leave it alone.

The test standard for this principle is very clear: every line of change should be traceable to the user’s request. If you changed a line the user didn’t ask for, it’s a violation.

This solves the LLM’s “neat-freak problem”—many AIs can’t resist refactoring when they see code that’s a bit messy, resulting in PRs laced with lots of irrelevant changes, making code review exceptionally painful.

4. Goal-Driven Execution: Define Success Criteria, Loop to Verify

This principle turns vague task descriptions into verifiable goals:

• “Add validation” → “Write tests for invalid input, then make them pass”
• “Fix the bug” → “Write a test that reproduces the bug, then make it pass”
• “Refactor X” → “Make sure tests pass both before and after the refactor”

For multi-step tasks, it requires listing a simple plan:

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

Karpathy’s own words: “Strong success criteria let you loop independently. Weak criteria (‘make it work’) require constant clarification.”

This principle solves the back-and-forth communication caused by vague goals. When the success criteria are clear, the AI can complete the entire task chain autonomously; when the criteria are vague, it has to ask “is this okay?” after every step.

What Can It Do? Applicable Scenarios

This Skill isn’t a cure-all, but it’s especially valuable in the following scenarios:

1. Code Review

When you’re reviewing AI-generated code or someone else’s code, these four principles make a great checklist:

• Is there over-engineering?
• Did it change things it shouldn’t have?
• Are the success criteria clear?

2. Incremental Development of Large Projects

When adding features to an existing codebase, the “Surgical Changes” principle is especially important. It prevents the AI from “conveniently” breaking existing code while adding new features.

3. Distinguishing Rapid Prototypes from Production Code

The “Simplicity First” principle helps the AI understand: when to write prototype code (rapid validation) and when to write production code (robust and reliable).

4. Teaching and Collaboration

When you’re using AI to teach others to program, or pair-programming with AI, these principles make the interaction more organized and reduce the “finished it only to realize the understanding was wrong” situations.

Why Do I Recommend You Try It?

Honestly, the first time I saw this Skill, my reaction was: “Isn’t this just common sense?”

But after using it for a while, I realized the gap between “common sense” and “systematized behavioral guidelines” is enormous. Just as many people know that “eat less and move more” can help with weight loss, but without a concrete diet plan and exercise schedule, there’s still a huge distance between knowing and doing.

The value of this Skill lies in:

1. It encodes “good programming habits” into executable rules, so the AI doesn’t need to “understand”—it only needs to “follow”
2. It sets the right tone at the very start of every interaction, rather than waiting until the code is ruined to fix it
3. It comes from real-world observation—behind every rule is a real case of stepping in a pit

More importantly, Karpathy himself also mentioned a tradeoff in his tweet: these guidelines lean toward caution rather than speed. For simple tasks, human judgment may be needed on whether to enable them. This means it isn’t meant to replace your judgment, but to give you a safe default option.

Conclusion

AI-assisted programming is spreading rapidly, but there’s still a long way between “usable” and “used well.” The karpathy-guidelines project offers a line of thinking: rather than constantly tuning the model itself, it’s better to define the behavioral norms first.

After all, the best AI tool isn’t the one that can write the most complex code, but the one that can consistently produce correct, concise, maintainable code.

If you also use AI programming tools like Kimi, Claude, and Cursor, why not install this Skill and give it a try. At least for me, it noticeably lowered the “rework rate” of AI-written code.

---

Reference links:

• GitHub project: andrej-karpathy-skills
• Karpathy’s original tweet: LLM Coding Pitfalls

中英对照

文章作者：阿文

文章链接： https://www.awen.me/post/3fbfa3f.html

版权声明：本博客所有文章除特别声明外，均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来自 阿文的博客！