An Architecture Decision Record (ADR) captures context, decision, alternatives, consequences, and status. It prevents teams from repeatedly revisiting decisions without understanding why they were made. Keep ADRs concise and update their status when the design changes.

Migration plans should include compatibility, backfill, validation, cutover, rollback limits, and cleanup. For a large dataset, run idempotent batches with checkpoints and rate limits so migration work does not starve production traffic. Compare counts, checksums, and sampled records before switching reads.

Some migrations are not safely reversible after new writes or external side effects. Define a forward-fix plan and preserve enough audit data to recover. Feature flags and shadow reads can reduce risk when comparing old and new implementations.