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

> Learn how to balance matching existing code style with improving it. Apply a surgical framework for effective, problem-driven refactors that enhance functionality without unnecessary complexity.

- Repository: [Jiayuan Zhang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills)
- Tags: best-practices
- Published: 2026-04-08

---

**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`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/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`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/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`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/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:

```diff
- // 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:

```diff
- // 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:

```markdown
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`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md)**: The single-file entry point outlining the four principles and installation instructions for the skill set.
- **[`skills/karpathy-guidelines/SKILL.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/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`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/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`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/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`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/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`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/skills/karpathy-guidelines/SKILL.md) within the `forrestchang/andrej-karpathy-skills` repository, with the primary entry point and installation instructions available in [`CLAUDE.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md). The specific line ranges (13-58) contain the actionable constraints governing the balance between matching style and improving functionality.