Notes between a decision and its code.
Short technical decisions prevent the same failure from becoming a pattern.
An idempotency key belongs to the payload
A retry of the same request should retain its key. If content changes after failure, create a new key so a conflict does not hide a new intention.
The UI must define “none”
An empty list, an unavailable service and a user without permission are different states. The component should show the difference and next step.
Migration is a production feature
A schema change is not complete when it works locally. It needs order, compatibility, backup, verification and a rollback path.
The log boundary is a privacy boundary
A log should support diagnosis without copying the whole request. Store an identifier, state and safe context.