Karpathy Principles

# Anti-Patterns: Eight Named Drift Rails

Each drift rail names a specific way LLM-driven coding
goes wrong, with a trigger pattern, a short bad
example, a short good example, and a one-sentence
test you can apply to your own diff. Naming the rail
helps recall.

Adapted from observations distilled by Forrest Chang
from Karpathy's notes; see
`references/source-attribution.md` for the citation
chain. Examples are rewritten in our own prose to
illustrate the failure shape, not lifted verbatim.

## AP-1: Hidden Assumptions

**Maps to**: Principle 1 (Think Before Coding)

**Trigger**: User asks for a feature with multiple
unstated dimensions (scope, format, volume, privacy).
The agent picks one silently and ships.

**Bad shape**

```python
def export_users(format='json'):
    users = User.query.all()
    if format == 'json':
        with open('users.json', 'w') as f:
            json.dump([u.to_dict() for u in users], f)
```

Assumed: all users (privacy?), file path, fields,
volume.

**Good shape**

> Before implementing, I want to confirm:
>
> - Scope: all users, or filtered?
> - Format: download, background job, or API endpoint?
> - Fields: which? Some are sensitive.
> - Volume: thousands or millions?
>
> Default proposal: a paginated JSON endpoint. Adjust?

**Test**: count silent assumptions in the diff. Three
or more is a rail violation.

## AP-2: Multiple Interpretations Picked Silently

**Maps to**: Principle 1 (Think Before Coding)

**Trigger**: A request like "make the search faster"
has at least three valid readings (response time,
throughput, perceived speed). The agent picks one and
implements 200 lines without flagging the choice.

**Bad shape**

```python
@lru_cache(maxsize=1000)
async def search(query: str) -> List[Result]:
    # 200 lines of caching, async, indexes, all picked
    # without confirming what "faster" means
    ...
```

**Good shape**

> "Faster" could mean response time, throughput, or
> perceived speed. Each is a different fix:
>
> 1. Response time: indexes plus query caching (~2h)
> 2. Throughput: async path plus pooling (~4h)
> 3. Perceived: progressive load and partial results
>    (~3h)
>
> Current: ~500ms typical. Which axis matters?

**Test**: when the verb in the request is ambiguous
(faster, better, cleaner, simpler), did the agent name
the alternatives or pick one?

## AP-3: Strategy Pattern for One Function

**Maps to**: Principle 2 (Simplicity First)

**Trigger**: User asks for a single function. The
agent ships an abstract base class, two implementing
classes, a config dataclass, and a coordinator class
for ten lines of arithmetic.

**Bad shape**

```python
class DiscountStrategy(ABC):
    @abstractmethod
    def calculate(self, amount: float) -> float: ...

class PercentageDiscount(DiscountStrategy):
    def __init__(self, p): self.p = p
    def calculate(self, a): return a * (self.p / 100)

# Plus FixedDiscount, DiscountConfig, DiscountCalculator
# for what should be one function
```

**Good shape**

```python
def calculate_discount(amount: float, percent: float) -> float:
    return amount * (percent / 100)
```

**Test**: count types and classes added per actual use
case. If types-added exceeds use-cases-served, the
pattern is premature.

## AP-4: Speculative Features

**Maps to**: Principle 2 (Simplicity First)

**Trigger**: "Save user preferences to database"
becomes a class with optional caching, validation,
notification hooks, and merge semantics. None were
asked for.

**Bad shape**

```python
class PreferenceManager:
    def __init__(self, db, cache=None, validator=None):
        ...
    def save(self, user_id, prefs,
             merge=True, validate=True, notify=False):
        # 60 lines of optional behavior
```

**Good shape**

```python
def save_preferences(db, user_id: int, preferences: dict):
    db.execute(
        "UPDATE users SET preferences = ? WHERE id = ?",
        (json.dumps(preferences), user_id),
    )
```

**Test**: list every parameter that was not in the
reques