This repository, `forrestchang/andrej-karpathy-skills`, provides a set of guidelines designed to improve the coding behavior of large language models (LLMs), specifically within the context of Claude Code. The core of the repository is a single file, `CLAUDE.md`, which encapsulates these guidelines, drawing inspiration from Andrej Karpathy's observations on the common pitfalls of LLM-generated code. The primary purpose of this repository is to enhance the quality, efficiency, and maintainability of code produced by LLMs by addressing the issues Karpathy identified.
The repository's main function is to offer a structured approach to guide LLMs towards producing better code. It achieves this through four key principles: "Think Before Coding," "Simplicity First," "Surgical Changes," and "Goal-Driven Execution." These principles are designed to counteract the tendencies of LLMs to make incorrect assumptions, overcomplicate code, introduce unnecessary changes, and lack a clear understanding of success criteria.
"Think Before Coding" encourages the LLM to explicitly state its assumptions, present multiple interpretations of a problem, and push back against ambiguous or unclear instructions. This principle aims to prevent the LLM from silently making incorrect assumptions and running with them, leading to errors and wasted effort. It promotes a more deliberate and thoughtful approach to coding, emphasizing clarification and understanding before implementation.
"Simplicity First" combats the LLM's inclination to overengineer solutions. It advocates for writing the minimum amount of code necessary to solve a problem, avoiding unnecessary features, abstractions, and error handling for unlikely scenarios. The principle emphasizes the importance of keeping code concise and readable, making it easier to understand, maintain, and debug.
"Surgical Changes" focuses on minimizing the scope of code modifications. It instructs the LLM to only touch the code directly related to the user's request, avoiding unrelated refactoring, formatting changes, or "improvements" to adjacent code. This principle aims to reduce the risk of introducing unintended side effects and to ensure that changes are focused and traceable to the original task.
"Goal-Driven Execution" transforms imperative instructions into declarative goals with verifiable success criteria. Instead of simply telling the LLM what to do, this principle encourages defining clear tests and verification steps. This allows the LLM to loop independently, iteratively refining its code until the specified goals are met. This approach leverages the LLM's strength in looping and verification, leading to more robust and reliable code.
The repository offers two primary methods for integrating these guidelines. The recommended approach is to use the Claude Code plugin, which allows for easy installation and application of the guidelines across multiple projects. Alternatively, the `CLAUDE.md` file can be manually incorporated into a project, either by creating a new file or appending the guidelines to an existing one. The repository also includes a Cursor project rule, making the guidelines readily available when using the Cursor editor.
The ultimate goal of this repository is to improve the quality of code generated by LLMs, leading to fewer errors, reduced complexity, and more maintainable projects. By adhering to these principles, developers can leverage the power of LLMs while mitigating their common weaknesses, resulting in a more efficient and reliable coding workflow. The guidelines are designed to be adaptable and can be customized with project-specific instructions to further refine the LLM's behavior. The repository emphasizes a bias towards caution over speed, prioritizing the reduction of costly mistakes in non-trivial tasks.
