How the Andrej Karpathy Skills Guidelines Handle Edge Cases and Error Scenarios

The guidelines treat edge cases and error scenarios as explicit, test-driven concerns that require verifiable success criteria rather than defensive coding boilerplate.

The forrestchang/andrej-karpathy-skills repository provides a disciplined approach to software engineering that explicitly addresses how to handle edge cases and error scenarios through four core principles. Unlike traditional defensive programming that layers generic try/except blocks preemptively, these guidelines demand that developers surface uncertainties early, write failing tests first, and implement only the minimal handling required by the specification.

Core Philosophy: Explicit Over Implicit

The foundational stance in skills/karpathy-guidelines/SKILL.md rejects "error handling for impossible scenarios" and any defensive code not explicitly required by the request. At lines 30-31, the guidelines explicitly discourage writing handlers for edge cases that have not been defined in the specification or proven by a failing test.

This philosophy manifests in a strict workflow: identify the edge case, write a failing test, implement the minimal change, verify no regression. The guidelines emphasize that if a scenario truly cannot happen, you should document the assumption rather than add unnecessary error handling that complicates the codebase.

The Four Guidelines for Managing Edge Cases

Think Before Coding

The first principle forces developers to surface uncertainty before writing any production code. According to lines 17-22 of SKILL.md, if an edge case is unclear, you must ask clarifying questions or explicitly state assumptions instead of guessing. This prevents implicit handling of error scenarios that may not actually exist.

Simplicity First

This guideline discourages speculative error handling. You should write only the handling that the spec asks for, then add additional logic only when a concrete test fails. This prevents the accumulation of dead code handling impossible edge cases.

Surgical Changes

When retrofitting an edge-case fix, you must only touch the code that strictly requires modification and immediately clean up any orphaned imports or variables. No unrelated refactoring is permitted, ensuring that error scenario fixes remain isolated and reviewable.

Goal-Driven Execution

This principle requires defining a verifiable success criterion for each edge case. As demonstrated in EXAMPLES.md at lines 403-405, the workflow explicitly includes: "Check edge cases: Multiple active sessions, concurrent changes" after implementing the core feature. The typical loop involves:

1. Write a failing test capturing the edge case
2. Implement the minimal change to pass it
3. Verify no regression in the full test suite

Practical Implementation Workflow

When confronting edge cases and error scenarios in practice, the guidelines mandate a four-step process:

Identify early – Extract edge cases from the specification or ask clarifying questions during the design phase. Document any assumptions about impossible inputs rather than coding defensively.

Write focused tests – Capture the specific failure mode in a test before writing production code. For example, when handling session invalidation during password changes:

import unittest

class TestAuth(unittest.TestCase):
    def test_password_change_invalidates_other_sessions(self):
        # Setup: two active sessions for the same user

        session_a = login(user_id=42)
        session_b = login(user_id=42)

        # Action: change password

        change_password(user_id=42, new="newSecret")

        # Expectation: the first session is no longer valid

        self.assertFalse(is_session_valid(session_a))
        self.assertTrue(is_session_valid(session_b))

Implement minimal changes – Add only the logic required to satisfy the test, without introducing generic exception handlers. In EXAMPLES.md, the implementation adds only the specific invalidate_other_sessions call rather than broad error handling:

def change_password(user_id: int, new: str):
    # Core requirement: update the password

    db.execute("UPDATE users SET password = ? WHERE id = ?", (hash(new), user_id))

    # Edge-case handling – only what the test demanded

    invalidate_other_sessions(user_id)

Verify with full suite – Run the complete test suite to confirm that your surgical change for the edge case introduced no regressions elsewhere.

Maintaining Clean Code During Fixes

The "Surgical Changes" principle extends to maintenance. When an edge case fix renders certain imports or variables obsolete, you must remove them immediately:

# Before

import logging, json, unused_helper  # <- unused_helper is now redundant

# After applying the edge-case fix only `logging` and `json` are needed

import logging, json

This prevents technical debt accumulation when handling error scenarios.

Summary

• Edge cases and error scenarios require explicit, test-driven validation rather than preemptive defensive coding
• The Think Before Coding principle surfaces uncertainty through clarifying questions before implementation
• Simplicity First mandates handling only what the specification explicitly requests, adding more only after test failures
• Surgical Changes require isolated, minimal modifications with immediate cleanup of orphaned code
• Goal-Driven Execution demands verifiable success criteria for every edge case scenario

Frequently Asked Questions

How do the guidelines differentiate between necessary and unnecessary error handling?

The guidelines in SKILL.md distinguish necessary error handling as code that responds to a specific, testable requirement or a failing test. Unnecessary handling includes try/except blocks for "impossible scenarios" that the specification does not mention or that have not been proven to occur in production. If an input scenario truly cannot happen according to the spec, you document the assumption and omit the handler.

What should I do if I discover an edge case after the initial implementation?

Following the Surgical Changes principle, you should write a failing test that captures the edge case, implement the minimal code change required to pass that test, and remove any orphaned imports or variables introduced during the fix. Avoid refactoring unrelated code during this process, and verify the change against the full test suite to prevent regressions.

Where are the concrete examples of edge case testing located?

The repository provides detailed examples in EXAMPLES.md, specifically around lines 403-405, which demonstrate how to check edge cases like multiple active sessions and concurrent changes during authentication flows. The README.md provides the high-level workflow overview, while CLAUDE.md contains the single-file plugin version of these guidelines for integration into development environments.

How does the "Goal-Driven Execution" principle apply to error scenarios?

This principle requires that every edge case have a verifiable success criterion defined before implementation begins. Rather than writing generic "handle errors" instructions, you must specify exactly what constitutes success for that scenario—for example, "when a user changes their password, all other active sessions must invalidate within 100ms." This criterion then drives the test creation and implementation phases.

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