Add a CLAUDE.md file

CLAUDE.md

@@ -0,0 +1,57 @@
+# CLAUDE.md
+
+Guidance for working in this repo. **`SPEC.md` is the source of truth for engine
+behavior and the level format** — read it before changing mechanics, and update
+it (and `README.md`) when behavior changes. This file only covers workflow and
+conventions not found there.
+
+## Commands
+
+The working virtualenv is `.venv` (Python 3.13). Prefix commands with
+`.venv/bin/` or activate it first.
+
+```bash
+.venv/bin/python main.py                    # play every level in ./levels
+.venv/bin/python main.py levels/foo.yaml    # play specific level(s), in order
+.venv/bin/python main.py --debug            # force the debug view (see SPEC §14)
+.venv/bin/python -m pytest                  # run the test suite
+.venv/bin/black main.py game tests tools    # format (do this before committing)
+```
+
+The test suite runs headless — `conftest.py` sets the SDL dummy video/audio
+drivers, so no window opens and nothing needs a display.
+
+## Conventions
+
+- **Formatting: `black`** (default 88-col line length, no config file). Run it on
+  any Python you touch. It's in `requirements-dev.txt`.
+- The game must stay **fully playable with zero art assets**: every sprite falls
+  back to a labeled colored rectangle (see `game/assets.py`). Don't add a hard
+  dependency on any PNG.
+- **Physics/collision live in true coordinates.** `Level.render_offset` is a
+  draw-only translation for the debug overscan — never fold it into gameplay
+  math.
+- All tunables (physics, timing, colors, the placeholder table) belong in
+  `game/settings.py`, not scattered as literals.
+
+## Adding a trap type
+
+Subclass `Trap` in `game/traps.py`, implement only the hooks it needs
+(`solid_rects`, `hazard_rects`, `carriers`, `update`, `draw`, `reset`, …), and
+register the class in the `TRAP_TYPES` factory map. Nothing else in the engine
+needs to change. See SPEC §11–13 for the hook contract and the trap catalog.
+
+## Tests
+
+`tests/` mirrors the behavior described in `SPEC.md` (physics, every trap and
+trigger, mounting, crush/shove, game-flow states). When you change behavior, add
+or update the matching test — several existing tests are regression guards for
+specific bugs (corner-warp, fits-under-no-crush, ride-into-wall-no-crush), so
+read the test's comment before altering its expectations.
+
+## Module map
+
+See SPEC §15 for the full layout. In short: `game/game.py` (loop/states/HUD),
+`game/level.py` (YAML → geometry + traps), `game/player.py` (physics &
+collision), `game/traps.py` (triggers + all trap types), `game/settings.py`
+(tunables), `game/assets.py` (sprites + placeholders).