Recommended Workflow for Bug Fixes Using Test-First Verification

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, 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 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 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:

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:

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:

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:

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. Install the guidelines to automate the recommended workflow for bug fixes using test-first verification:

/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.

Practical Usage Examples

Testing Before Refactoring

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

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 (guidelines), skills/karpathy-guidelines/SKILL.md (plugin metadata), EXAMPLES.md (illustrative cases including lines 54-95), and 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 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.

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, the CLAUDE.md guidelines and 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 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.

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