State Machines — What Claude Gets Wrong

You model states as a status: String field and transitions as status = "next_status" assignments scattered across the codebase. In production: invalid transitions happen silently, states carry data that doesn't apply to them, boolean flag combinations create impossible states, and nobody can reconstruct how an entity reached its current state.

The Five Rules

1. States are enums, not strings — the compiler enforces valid states
2. Transitions are validated — not every state can reach every other state
3. Per-state data — each state carries only the data relevant to it
4. Audit trail — record every transition with timestamp and reason
5. No boolean flag clusters — (is_paid, is_shipped, is_cancelled) is a state machine in denial

Anti-Patterns You Default To