Document decisions

Record durable decisions where future maintainers will find them. First inspect the repository's existing documentation structure and decision records; update the established location rather than introducing a competing convention.

Decide what needs a record

Write a decision record when a future contributor could reasonably ask why one approach was chosen over another. This usually includes cross-cutting or costly to reverse choices, architectural boundaries, integrations, data flows, and changes to build, test, deployment, security, or public contracts.

Do not create decision records for routine implementation details, trivial bug fixes, mechanical dependency updates, or cosmetic changes unless they expose a real trade-off.

Choose the right document