docs(claude): state the Final-binding and frozen-parameter conventions

This commit is contained in:
mateo-berri 2026-08-04 13:20:59 -07:00
parent 2708620d6a
commit 741aa901cd

View file

@ -75,6 +75,7 @@ Follow these coding conventions for new/updated code (a three-line fix in a lega
- Never-nester: early returns over deep nesting
- Don't throw; model failures as values (One function (e.g., raise_public) maps error union to existing public exception contracts via exhaustive match + assert_never)
- No mutation; don't reassign variables, global or local. Instead of mutable lists and dicts, prefer tuples, frozen dataclasses (with slots=True), etc.
- Annotate every local, nonlocal, and global binding with `: Final` (LIT010). Unpacking and walrus targets cannot carry the annotation, so they are implicitly final; don't rebind them. Never rebind or mutate function parameters (LIT011); `self`/`cls` attribute stores are the exception. If rebinding or in-place mutation is truly unavoidable, suppress with `# rebind-ok: <reason>` explaining why
- Use dependency injection
- Fully typed; no `Any` or coarse types like `dict[str, Any]` or just `dict`. Every function parameter must be strongly typed
- Use tagged unions + match