# Recommended Workflow for Bug Fixes Using Test-First Verification

> Master bug fixes with a test-first verification workflow. Write failing tests, make simple changes, and confirm your fix without regressions. Improve code quality today.

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

---

**The recommended workflow for bug fixes using test-first verification involves writing a failing test that captures the observed bug, applying a surgical code change guided by simplicity principles, and re-running the test suite to confirm the fix without regressions.**

The **forrestchang/andrej-karpathy-skills** repository provides an opinionated framework for LLM-assisted coding that emphasizes disciplined, test-first approaches to debugging. By following the four core principles outlined in [`CLAUDE.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md), developers can implement a recommended workflow for bug fixes using test-first verification that minimizes over-engineering and prevents hidden assumptions. This guide walks through the specific steps, concrete code examples, and plugin integration methods defined in the repository's core files.

## The Four Principles Guiding Test-First Bug Fixes

The repository centers on four behavioral guidelines defined in [`CLAUDE.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md) that directly support test-first verification:

- **Think Before Coding**: Surface assumptions and trade-offs before modifying code.
- **Simplicity First**: Write minimal changes that satisfy the test criteria.
- **Surgical Changes**: Modify only the lines necessary to fix the bug.
- **Goal-Driven Execution**: Define verifiable success criteria and iterate until met.

These principles ensure that debugging remains focused, transparent, and verifiable.

## Step-by-Step Test-First Verification Workflow

The [`EXAMPLES.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/EXAMPLES.md) file (specifically lines 54-95) provides concrete implementation guidance. Follow this six-step process to fix bugs without regressions.

### 1. Identify and Isolate the Bug

Start with a concrete reproduction case. For example, when sorting breaks with duplicate scores, document the specific failure mode before writing any fix.

### 2. Write a Failing Test

Create a targeted test that captures the observed bug and satisfies **Goal-Driven Execution**:

```python
def test_sort_with_duplicate_scores():
    """Test sorting when multiple items have the same score."""
    scores = [
        {"name": "Alice", "score": 100},
        {"name": "Bob",   "score": 100},
        {"name": "Charlie", "score": 90},
    ]
    result = sort_scores(scores)
    assert result[0]["score"] == 100
    assert result[1]["score"] == 100
    assert result[2]["score"] == 90

```

This test isolates the instability and provides a concrete success criterion.

### 3. Confirm the Failure

Run the test suite to verify the bug is reproducible:

```bash
pytest -q

```

Ensure the new test fails before proceeding.

### 4. Apply a Surgical Fix

Guided by **Surgical Changes** and **Simplicity First**, modify only the necessary function without adding unnecessary abstraction:

```python
def sort_scores(scores):
    """Sort by score descending, then name ascending for ties."""
    return sorted(scores, key=lambda x: (-x["score"], x["name"]))

```

### 5. Verify the Fix

Re-run the tests to confirm resolution and ensure no regressions:

```bash
pytest -q

```

All tests should pass, validating that the change addresses only the specific failure.

### 6. Document Transparently

Reference the guiding principle in your commit message to maintain alignment with the repository's philosophy:

```

fix: stable sort for duplicate scores (Goal-Driven Execution)

```

## Automating the Workflow with Claude Code

The repository provides plugin scaffolding via [`skills/karpathy-guidelines/SKILL.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/skills/karpathy-guidelines/SKILL.md). Install the guidelines to automate the recommended workflow for bug fixes using test-first verification:

```bash
/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

```

Invoke the skill to guide your debugging session:

```

@karpathy-guidelines "Help me fix a bug using test-first verification"

```

The model will follow the four principles and the six-step verification sequence defined in [`CLAUDE.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md).

## Practical Usage Examples

### Testing Before Refactoring

When modifying existing code, always write the test first to establish boundary conditions:

```python
def test_user_email_validation():
    with pytest.raises(ValueError):
        validate_user({"email": ""})

```

This ensures **Goal-Driven Execution** before you touch production code.

### Surfacing Assumptions

Use the plugin to apply **Think Before Coding** when scoping new features:

```

@karpathy-guidelines "I need to add an export feature for user data"

```

The model will respond with clarification steps regarding scope, output format, and field selection, preventing hidden assumptions.

## Summary

- The **forrestchang/andrej-karpathy-skills** repository defines a recommended workflow for bug fixes using test-first verification built on four core principles: **Think Before Coding**, **Simplicity First**, **Surgical Changes**, and **Goal-Driven Execution**.
- Key files include [`CLAUDE.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md) (guidelines), [`skills/karpathy-guidelines/SKILL.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/skills/karpathy-guidelines/SKILL.md) (plugin metadata), [`EXAMPLES.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/EXAMPLES.md) (illustrative cases including lines 54-95), and [`README.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/README.md) (installation instructions).
- The workflow requires writing a failing test that captures the bug, running `pytest` to confirm failure, applying minimal surgical changes, and re-running tests to verify the fix.
- Commit messages should reference the guiding principle used (e.g., "Goal-Driven Execution") to maintain transparency and purpose.
- The Claude Code plugin automates this workflow by importing the guidelines directly into your development environment via `@karpathy-guidelines`.

## Frequently Asked Questions

### What files do I need to implement this test-first workflow in my project?

You need [`CLAUDE.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md) from the repository root, which contains the complete guideline set. Copy it into your project directory using `curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md`, then append project-specific rules after the separator as shown in the [`README.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/README.md).

### How does the "Surgical Changes" principle prevent over-engineering?

**Surgical Changes** requires modifying only the specific lines of code necessary to fix the bug, avoiding tangential refactors or architectural changes. This constraint, combined with **Simplicity First**, ensures you write the minimal code that satisfies the test criteria rather than building unnecessary abstractions.

### Can I use this workflow without Claude Code?

Yes. While the repository offers a Claude Code plugin via [`skills/karpathy-guidelines/SKILL.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/skills/karpathy-guidelines/SKILL.md), the [`CLAUDE.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md) guidelines and [`EXAMPLES.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/EXAMPLES.md) cases are human-readable and framework-agnostic. You can manually apply the four principles and the six-step test-first verification process in any development environment or LLM interface.

### Where can I find concrete examples of test-first bug fixes in the repository?

The [`EXAMPLES.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/EXAMPLES.md) file contains real-world before/after snippets, including the test-first verification example covering lines 54-95 that demonstrates fixing an unstable sort with duplicate scores. This file shows both incorrect approaches (hidden assumptions, over-engineering) and correct implementations following the four principles.