How to Adapt Guidelines to Different Programming Languages: Language-Agnostic Principles for LLM-Assisted Development

The Karpathy guidelines adapt to any programming language by focusing on behavioral principles—thinking before coding, minimizing complexity, making surgical edits, and verifying goals—rather than syntax-specific rules.

The multica-ai/andrej-karpathy-skills repository provides a framework for adapting guidelines to different programming languages through four universal principles. Unlike language-specific style guides, these guidelines define how to approach code generation and modification, making them applicable to Python, JavaScript, Go, Rust, or any other language. This language-agnostic approach ensures consistent, high-quality LLM-assisted development across diverse codebases.

The Four Core Principles for Language Adaptation

The guidelines are codified in SKILL.md, CLAUDE.md, and EXAMPLES.md as behavioral rules that translate into any programming language's syntax and tooling.

1. Think Before Coding

Found in SKILL.md, this principle requires explicitly stating assumptions and enumerating interpretations before emitting code. Whether writing Python functions or Rust modules, the LLM must document its reasoning in comments—using # Assumptions: in Python or // Assumptions: in JavaScript and Go.

2. Simplicity First

Defined in CLAUDE.md, this mandates producing the smallest working snippet. Avoid premature abstractions—a single function over a Strategy pattern in Java, or a standalone function rather than a new package in Go.

3. Surgical Changes

Detailed in EXAMPLES.md, this requires touching only necessary lines. In Go, this means preserving gofmt output; in Rust, maintaining existing rustfmt style. Only modify what the bug fix or feature requires.

4. Goal-Driven Execution

Also in EXAMPLES.md, this involves defining concrete success criteria and looping until met. Write failing tests first using pytest for Python, jest for JavaScript, or testing for Go, then implement the minimal code to pass.

Language-Specific Implementation Examples

The repository demonstrates how these principles manifest across different programming languages through concrete code snippets.

Python Implementation

In Python, "Think Before Coding" translates to docstrings and assumption comments:

# Assumptions:

# 1. The caller provides a list of integers.

# 2. The function should return the sum of the even numbers only.

def sum_even(nums: list[int]) -> int:
    """Return the sum of even numbers in `nums`."""
    return sum(n for n in nums if n % 2 == 0)

This example, referenced in SKILL.md, shows the "Simplicity First" principle by using a generator expression rather than a class-based solution.

JavaScript/TypeScript Implementation

For JavaScript, the guidelines emphasize minimal changes and explicit assumptions:

// Assumptions:
// - `items` is an array of objects with a numeric `value` field.
// - We only need to calculate the total of `value`s greater than 10.

function totalAboveTen(items) {
  return items.reduce((acc, cur) => (cur.value > 10 ? acc + cur.value : acc), 0);
}

This illustrates "Simplicity First" (single function export) and "Surgical Changes" (modifying only the calculation logic without refactoring the entire module), as shown in EXAMPLES.md.

Go Implementation

Go demonstrates "Goal-Driven Execution" through test-first development:

// sum_even_test.go
package utils

import "testing"

func TestSumEven(t *testing.T) {
    got := SumEven([]int{1, 2, 3, 4})
    want := 6
    if got != want {
        t.Fatalf("expected %d, got %d", want, got)
    }
}

// sum_even.go – minimal implementation (Simplicity First)
package utils

func SumEven(nums []int) int {
    sum := 0
    for _, n := range nums {
        if n%2 == 0 {
            sum += n
        }
    }
    return sum
}

These files show how the guidelines respect Go's idioms (gofmt compatibility, table-driven tests) while enforcing minimal, verifiable changes.

Rust Implementation

Rust illustrates "Surgical Changes" through precise editing without reformatting:

// Before (buggy)
pub fn divide(a: i32, b: i32) -> i32 {
    a / b // panics on b == 0
}

// After – only the necessary guard added
pub fn divide(a: i32, b: i32) -> i32 {
    if b == 0 {
        panic!("division by zero");
    }
    a / b
}

This example from EXAMPLES.md demonstrates that only the lines required to fix the bug are touched, preserving the existing rustfmt style and surrounding code structure.

Key Files for Language Adaptation

The repository organizes its language-agnostic guidelines into specific files that developers and LLMs should reference:

File	Purpose	Location
SKILL.md	Defines the four core principles in a machine-readable format.	skills/karpathy-guidelines/SKILL.md
CLAUDE.md	Human-friendly elaboration of the guidelines for Claude Code integration.	CLAUDE.md
EXAMPLES.md	Concrete "wrong vs. right" code snippets across Python, JavaScript, Go, and Rust.	EXAMPLES.md
karpathy-guidelines.mdc	Cursor IDE integration that enforces principles during autocomplete and refactoring.	.cursor/rules/karpathy-guidelines.mdc

Summary

• The Karpathy guidelines are behavioral, not syntactic. They adapt to any programming language by focusing on how to reason about code rather than prescribing specific syntax.

• Four universal principles drive adaptation: Think Before Coding, Simplicity First, Surgical Changes, and Goal-Driven Execution.

• Language-specific implementation varies by idioms. Python uses docstrings and type hints; Go uses *_test.go files; Rust preserves rustfmt style; JavaScript maintains ESLint compatibility.

• Repository files provide the source of truth. SKILL.md contains the machine-readable rules, while EXAMPLES.md demonstrates cross-language application.

Frequently Asked Questions

Are the Karpathy guidelines only for Python?

No. While many examples in the repository use Python for clarity, the guidelines are explicitly designed to adapt to different programming languages. The principles of thinking before coding, simplicity, surgical changes, and goal-driven execution apply equally to JavaScript, Go, Rust, Java, or any other language. The EXAMPLES.md file specifically demonstrates implementations across multiple languages.

How do I enforce these guidelines in my IDE?

The repository provides IDE-specific integration files. For Cursor users, the .cursor/rules/karpathy-guidelines.mdc file enforces the principles during autocomplete and refactoring operations. For Claude Code users, referencing CLAUDE.md in the project context ensures the LLM follows the surgical change and simplicity principles. You can also copy the content of SKILL.md into your LLM's system prompt for general enforcement.

Do these guidelines replace language-specific style guides?

No, they complement them. The Karpathy guidelines address behavioral aspects of code generation—how to plan, minimize, and verify changes—while language style guides (like PEP 8 for Python or gofmt for Go) address syntactic formatting. When adapting the guidelines to different programming languages, you should follow both: apply the behavioral principles while respecting the language's established formatting and idiomatic conventions.

Can I use these guidelines with legacy codebases?

Yes. The "Surgical Changes" principle specifically addresses working with existing code. The guidelines instruct LLMs to touch only the lines required to fix bugs or add features, without reformatting unrelated code or changing existing comment styles. This makes them ideal for legacy codebases where large-scale refactoring would be risky. The EXAMPLES.md file includes Rust and Go examples showing how to make minimal edits while preserving existing formatting.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}