DOCSEARCHbyAlgolia
Submit Docs

Andrej Karpathy-Inspired Coding Guidelines

repository·main·Indexed 13 days ago

https://github.com/multica-ai/andrej-karpathy-skills

A set of coding guidelines for LLMs, specifically Claude Code and Cursor, designed to improve code quality by mitigating common pitfalls. The framework is built on four core principles: Think Before Coding, Simplicity First, Surgical Changes, and Goal-Driven Execution.

Tokens
4.3K
Snippets
8
Records
21
Agent score
94%

What's inside Andrej Karpathy Skills

  1. Apply the Karpathy Guidelines for LLM coding

    main

    The Karpathy Guidelines are behavioral principles designed to reduce common LLM coding mistakes such as overcomplication, silent assumptions, and unnecessary refactoring. These guidelines bias toward caution over speed. Use them when writing, reviewing, or refactoring code to ensure changes are surgical, simple, and goal-driven.

    Core Principles:

    1. Think Before Coding: Explicitly state assumptions, surface tradeoffs, and ask for clarification instead of making silent decisions.
    2. Simplicity First: Write the minimum code required. Avoid speculative abstractions, unrequested configurability, or error handling for impossible scenarios.
    3. Surgical Changes: Touch only what is necessary. Do not refactor adjacent code or change formatting unless it is part of the task. Match the existing style.
    4. Goal-Driven Execution: Transform vague tasks into verifiable success criteria (e.g., instead of "fix the bug", use "write a test that reproduces the bug, then make it pass").

  2. The Four Principles of Karpathy-Inspired Coding

    main

    The guidelines are built on four core principles designed to mitigate common LLM coding pitfalls like overcomplication, wrong assumptions, and orthogonal edits.

    1. Think Before Coding

    Goal: Prevent wrong assumptions and hidden confusion.

    • State assumptions explicitly.
    • Present multiple interpretations when ambiguity exists.
    • Push back if a simpler approach is available.
    • Stop and ask for clarification when confused.

    2. Simplicity First

    Goal: Combat overengineering and bloated abstractions.

    • Implement only the minimum code required to solve the problem.
    • Avoid speculative features, unrequested abstractions, or unnecessary configurability.
    • Avoid error handling for impossible scenarios.

    3. Surgical Changes

    Goal: Minimize side effects and unintended refactors.

    • Touch only the code necessary for the task.
    • Do not "improve" adjacent code, comments, or formatting unless requested.
    • Match the existing project style.
    • Only remove imports/variables/functions that your changes made unused; do not delete pre-existing dead code unless asked.

    4. Goal-Driven Execution

    Goal: Use verifiable success criteria instead of imperative instructions.

    • Transform tasks into testable goals (e.g., instead of "Fix the bug", use "Write a test that reproduces the bug, then make it pass").
    • For multi-step tasks, define a plan with verification steps:
      1. [Step] → verify: [check]
2. [Step] → verify: [check]

  3. Apply the 'Surgical Changes' principle

    main

    When fixing bugs or adding small features, perform 'surgical' updates. Avoid 'drive-by refactoring' where you inadvertently change the codebase's style or scope.

    Guidelines:

    • Avoid Drive-by Refactoring: Do not add extra validation, change comments, or add docstrings to unrelated parts of a function while fixing a specific bug. Only change the lines necessary to resolve the issue.
    • Avoid Style Drift: Match the existing codebase style exactly. If the project uses single quotes, do not switch to double quotes. If it lacks type hints, do not add them. If it uses a specific boolean return pattern, do not change it to a different logic flow.

  4. Apply the 'Think Before Coding' principle

    main

    Before implementing a feature, avoid making hidden assumptions about scope, format, or data structure. Instead of writing code immediately, surface assumptions to the user to clarify the intent.

    Key areas to clarify before coding:

    • Scope: Should the operation apply to all items or a filtered subset?
    • Format/Interface: Does the user want a browser download, a background job, or an API endpoint?
    • Fields: Which specific data fields are required (especially regarding sensitive data)?
    • Volume: How much data is involved? (This dictates whether you need pagination, async processing, or specific optimization strategies).

    Handling Ambiguous Requests: If a request is vague (e.g., "Make it faster"), do not pick an implementation silently. Instead, present the different interpretations and their estimated effort:

    1. Response Time: (e.g., adding indexes/caching)
    2. Throughput: (e.g., adding async/await/pooling)
    3. Perceived Speed: (e.g., progressive loading/UX changes)

  5. Compare Claude Code and Cursor integration

    main

    The integration method depends on the tool you are using:

    • Claude Code: Install via the plugin marketplace. The plugin exposes the skill from this repository. For per-project use, you can rely on CLAUDE.md.
    • Cursor: Uses the .cursor/rules/ directory. Note that Cursor does not read .claude-plugin/ or CLAUDE.md by default.

  6. Apply the 'Simplicity First' principle

    main

    Avoid over-engineering and speculative features. Write the simplest code that satisfies the immediate requirement.

    Guidelines:

    • Avoid Over-abstraction: Do not implement complex design patterns (like Strategy patterns or heavy class hierarchies) for simple calculations or logic unless multiple types are explicitly required.
    • Avoid Speculative Features: Do not add 'just in case' features like caching, validation, or notification systems if they weren't requested.
    • Refactor on Demand: Only add complexity (like DiscountConfig or PreferenceManager with extra flags) when the requirement for that complexity actually emerges.

  7. How the four Karpathy principles work

    main

    The guidelines are built around four core principles designed to mitigate common LLM coding pitfalls (incorrect assumptions, over-engineering, and irrelevant edits).

    1. Think Before Coding: Forces the LLM to explicitly state assumptions, present multiple interpretations when ambiguous, and ask for clarification instead of guessing.
    2. Simplicity First: Combats over-engineering by instructing the LLM to use the minimum code necessary, avoid adding unrequested flexibility, and refactor complex code into simpler forms.
    3. Surgical Changes: Ensures the LLM only touches necessary code. It should not 'improve' adjacent code, refactor working code, or change formatting unless requested. It should only remove dead code that it specifically created.
    4. Goal-Driven Execution: Transforms imperative instructions into verifiable goals. Instead of "fix bug", use "write a test that reproduces the bug, then make it pass". For multi-step tasks, the LLM should provide a plan with verification steps: 1. [Step] -> Verification: [Check].

  8. Use the guidelines in Cursor

    main
    The repository includes a committed Cursor project rule located at .cursor/rules/karpathy-guidelines.mdc. When you open the project in Cursor, these guidelines are automatically applied. For instructions on how to use these rules in other projects and their relationship with Claude Code, refer to the CURSOR.md file.

  9. Customize the Claude Code guidelines

    main

    The guidelines are designed to be merged with your project-specific instructions. You can add custom rules to your CLAUDE.md file to enforce project-specific standards.

    Example of adding project-specific rules:

    ## Project-Specific Guidelines

- Use TypeScript strict mode
- All API endpoints must have tests
- Follow the existing error handling patterns in `src/utils/errors.ts`
    ## Project-Specific Guidelines

- Use TypeScript strict mode
- All API endpoints must have tests
- Follow the existing error handling patterns in `src/utils/errors.ts`

  10. Implement Goal-Driven Execution with verifiable steps

    main

    To avoid weak success criteria like "make it work," transform every task into a verifiable goal. For multi-step tasks, define a plan where each step is paired with a specific verification method.

    Example Task Transformations:

    • "Add validation" $\rightarrow$ "Write tests for invalid inputs, then make them pass"
    • "Fix the bug" $\rightarrow$ "Write a test that reproduces it, then make it pass"
    • "Refactor X" $\rightarrow$ "Ensure tests pass before and after"

    Plan Format:

    1. [Step] $\rightarrow$ verify: [check]
2. [Step] $\rightarrow$ verify: [check]
3. [Step] $\rightarrow$ verify: [check]

  11. Apply Karpathy guidelines to other Cursor projects

    main

    To use these guidelines in a different project with Cursor, copy the rule file .cursor/rules/karpathy-guidelines.mdc from this repository into the .cursor/rules/ directory of your target project. If the directory does not exist, create it manually. You can then adjust or merge this rule with your existing project rules.

    mkdir -p .cursor/rules
cp path/to/karpathy-guidelines.mdc .cursor/rules/

  12. Apply Karpathy guidelines to other AI tools

    main
    If you are using an AI tool that only supports a single root instruction file (rather than a rules directory), copy the contents of CLAUDE.md from this repository into your project's primary instruction file or merge them into your existing instructions.