Balancing Matching Existing Code Style vs. Improving It: A Surgical Framework

Prioritize surgical, goal-driven changes that match existing conventions unless a modification directly solves a verified problem, avoiding cosmetic refactors that increase complexity without functional benefit.

The forrestchang/andrej-karpathy-skills repository establishes a disciplined framework for balancing matching existing code style vs. improving it through four actionable principles. These guidelines, codified in skills/karpathy-guidelines/SKILL.md, instruct Large Language Models (LLMs) to resist aesthetic tinkering while remaining vigilant for meaningful, minimal improvements.

The Four Principles of Surgical Code Editing

According to the source code analysis of forrestchang/andrej-karpathy-skills, the decision to deviate from established patterns relies on four hierarchical rules that prioritize functional necessity over stylistic preference.

Think Before Coding

Before modifying any line, the model must surface assumptions, enumerate possible interpretations, and push back if a simpler solution exists. As specified in lines 13-22 of skills/karpathy-guidelines/SKILL.md, this deliberation phase forces a decision about whether a stylistic change is truly needed or merely reflects cosmetic preference. This principle prevents automated "improvements" that don't serve the task's core objective.

Simplicity First

The guidelines mandate writing only the minimal code required to solve the problem (lines 23-32). If an improvement introduces unnecessary abstraction or complexity—such as converting simple functions into class hierarchies—the model must retain the original style rather than optimize prematurely. This minimalist constraint ensures that "improving" doesn't become a euphemism for complicating.

Surgical Changes: The Core Style vs. Improvement Rule

At lines 35-44 of skills/karpathy-guidelines/SKILL.md, the repository defines the critical directive: match the existing style unless a change is directly required by the task. The model must not refactor adjacent code, delete pre-existing dead code, or alter naming conventions without explicit request (lines 45-48). This surgical precision guarantees that any deviation from established patterns is intentional, traceable, and justified by functional requirements rather than personal aesthetic preference.

Goal-Driven Execution

Every modification must map to a clear, verifiable success criterion (lines 51-58). By defining concrete objectives—such as "add missing error handling" rather than "make the code prettier"—the model naturally constrains its scope to necessary changes. This outcome-based filtering prevents scope creep into stylistic territory where existing conventions should prevail.

Practical Implementation Examples

The forrestchang/andrej-karpathy-skills repository provides concrete diff examples demonstrating how to apply these principles when balancing style adherence against functional improvement.

Example 1: Matching Existing Style Without Unnecessary Refactor

When encountering snake_case functions, preserve the convention even if camelCase is personally preferred:

- // Existing function uses snake_case
- def get_user_name(user_id):
+ // Keep the same naming style
+ def get_user_name(user_id):
      # implementation …

Example 2: Justified Improvements That Preserve Style

Add functional value while maintaining the original aesthetic:

- // Original code lacks input validation
- def calculate_total(price, tax):
+ // Add minimal validation, keep snake_case
+ def calculate_total(price, tax):
+     if price < 0 or tax < 0:
+         raise ValueError("price and tax must be non-negative")
      return price * (1 + tax)

Example 3: Rejecting Gratuitous Style Changes

When users request cosmetic renaming without functional justification:

User request: “Rename all functions to camelCase.”

Model response:  
> “Changing naming conventions would affect the entire codebase without a functional benefit. According to the Surgical Changes principle in `skills/karpathy-guidelines/SKILL.md` (lines 35-48), I’ll keep the existing snake_case style unless a concrete problem requires renaming.”

Repository Structure and Key Files

Understanding where these guidelines live in forrestchang/andrej-karpathy-skills helps implement them correctly:

• CLAUDE.md: The single-file entry point outlining the four principles and installation instructions for the skill set.
• skills/karpathy-guidelines/SKILL.md: The machine-readable skill definition containing the full guidelines text, including the specific line references (lines 13-58) governing style decisions.
• README.md: High-level documentation explaining the repository's intent to constrain LLM behavior toward surgical, minimal edits.

Summary

• Match existing conventions unless a change is strictly required by task requirements, as mandated in lines 35-44 of skills/karpathy-guidelines/SKILL.md.
• Validate necessity through the Think Before Coding principle to distinguish functional needs from aesthetic preferences.
• Minimize scope by following Simplicity First—if an improvement adds complexity without proportional value, retain the original style.
• Avoid adjacent refactoring; the guidelines explicitly prohibit touching unrelated code, deleting dead code, or renaming conventions without explicit request (lines 45-48).

Frequently Asked Questions

When should I deviate from existing code style according to the Karpathy guidelines?

Deviation is appropriate only when the change directly solves a verified problem, fixes a bug, or adds necessary functionality. As specified in lines 35-44 of skills/karpathy-guidelines/SKILL.md, the default position is to match the existing style, with deviations requiring explicit task-related justification grounded in lines 51-58's goal-driven criteria.

How does the repository prevent LLMs from making cosmetic refactoring?

The Surgical Changes principle explicitly prohibits refactoring adjacent code, deleting pre-existing dead code, or renaming conventions without request (lines 45-48). This rule prevents models from "cleaning up" code that isn't part of the assigned task, ensuring that style changes are surgical rather than scattershot.

What constitutes a valid improvement versus a stylistic preference under these guidelines?

Valid improvements map to clear, verifiable success criteria such as adding error handling, fixing logic bugs, or removing actual duplication. Stylistic preferences—like renaming variables for "clarity" or converting between snake_case and camelCase—are rejected unless they solve a concrete interoperability or functional issue defined in lines 23-32 and 51-58.

Where are these code style principles documented in the repository?

The complete specification resides in skills/karpathy-guidelines/SKILL.md within the forrestchang/andrej-karpathy-skills repository, with the primary entry point and installation instructions available in CLAUDE.md. The specific line ranges (13-58) contain the actionable constraints governing the balance between matching style and improving functionality.

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