adr-writing

Write an architecture decision record when making structural choices like adopting new recurring code patterns, adding runtime dependencies, departing from conventions, or making non-obvious database schema decisions. This avoids documenting trivial micro-choices like file naming.

Document software architecture decisions using a standardized 25-line maximum template that captures context and tradeoffs. This structured documentation preserves reasoning for future teams and eliminates repeated debates over past implementation choices.

Create collision-proof filenames for architecture decision records by applying a session and ticket namespace convention. This prevents file conflicts when multiple developers document structural decisions simultaneously in the same codebase.

Link architecture decision records to source code using a paired commit workflow that provides source code reference guidelines and a commit message format. This ensures ADRs are consistently reviewed alongside implementation changes.

The architecture decision record workflow requires no specific dependencies. It provides a standalone template and naming convention designed to integrate directly into your existing development workflow without external tools.

Document an authentication provider switch by creating an architecture decision record that captures the decision context, tradeoffs, and reasoning. This ensures future developers understand the structural change without digging through old commit threads.