write-adr

To document architectural decisions, you generate Architecture Decision Records (ADRs) that capture context, evaluated alternatives, the final choice, and consequences. This ensures technical choices are recorded for future reference and team alignment.

An architecture decision record should include the context of the decision, evaluated alternatives, the chosen solution, and the expected consequences. This standardized format details why a specific technology was chosen over others.

You need to create an ADR for technical debt when making significant architectural choices like adopting a new database technology. Recording these decisions provides historical context and a shared understanding of technical trade-offs.

You generate standardized ADR files by using a documentation tool that creates them within your project's documentation directory. This ensures architectural decisions are consistently formatted and recorded for team alignment.

The best way to capture decision rationale is by documenting the context, evaluated options, chosen solution, and consequences in an ADR. This formalizes significant architectural decisions and ensures clarity across the team.