# CLAUDE.md — Agent Instructions

Behavioral guidelines for AI coding agents. Merges Andrej Karpathy's
LLM coding-pitfall observations with the Ponytail minimalism ladder.

**Tradeoff:** bias toward caution *and* minimalism. On trivial tasks,
use judgment — don't ask when the answer is obvious, just write the
smallest thing that works.

---

## 1. Think before coding

Don't assume. Don't hide confusion. Surface tradeoffs.

- State assumptions explicitly.
- If interpretations genuinely diverge, ask ONE clarifying question.
  Otherwise take the minimal reading, write the assumption as an inline
  comment, and proceed — do not stall.
- If a simpler approach exists, say so. Push back when warranted.

## 2. Write the least code that works (the ladder)

Before writing any code, stop at the FIRST rung that solves the task:

1. **Skip it** — is the feature even needed? (YAGNI)
2. **Stdlib** — does the standard library already do this?
3. **Native** — does the platform/runtime have it built in?
4. **Existing dependency** — can something already installed do the job?
5. **One line** — can it be one line?
6. **Minimum** — only now, write the least code that works.

No features beyond what was asked. No abstractions for single-use code.
No speculative flexibility or configurability. No error handling for
impossible scenarios. If you wrote 200 lines and it could be 50, rewrite.

Test: "Would a senior engineer call this overcomplicated?" If yes, simplify.

## 3. Where laziness stops

Section 2 does NOT apply to these — here, do it properly:

- Input validation at trust boundaries.
- Error handling that prevents data loss.
- Security.
- Accessibility.
- Calibration real hardware needs (clocks drift, sensors read off — the
  platform is never the spec ideal).
- Anything the user explicitly requested.

## 4. Mark and verify your shortcuts

Lazy code without a check is unfinished.

- Mark every intentional simplification with a `ponytail:` comment. If the
  shortcut has a known ceiling (global lock, O(n²) scan, naive heuristic),
  the comment names the ceiling and the upgrade path.
- Non-trivial logic leaves behind ONE runnable check — the smallest thing
  that fails if the logic breaks (an assert-based self-check or one small
  test file; no frameworks, no fixtures).
- Turn the task into a verifiable goal and loop until it passes:
  - "Add validation" → write tests for invalid inputs, then make them pass.
  - "Fix the bug" → write a test that reproduces it, then make it pass.
  - "Refactor X" → ensure tests pass before and after.

For multi-step tasks, state a brief plan: `1. step → verify: check`.

## 5. Surgical changes

Touch only what you must. Clean up only your own mess.

- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor what isn't broken. Match existing style.
- Remove imports/variables/functions that YOUR changes made unused.
- Pre-existing dead code: mention it, don't delete it (unless asked).

Test: every changed line traces directly to the user's request.

---

**Working if:** fewer unnecessary changes in diffs, fewer rewrites from
overcomplication, clarifying questions come *before* implementation rather
than after mistakes, and intentional shortcuts are visible (`ponytail:`)
rather than silent.