adr

To document architectural decisions, create architecture decision records that capture the context, alternatives considered, and the final choice. This ensures your design rationale travels with the codebase for future engineers.

The best way to convert an RFC into a decision record is to extract the problem context and proposed solution, then map them into an ADR format. This backfills undocumented decisions for better historical traceability.

Architecture decision record frontmatter should include id, status, date, related links, tags, and superseded-by fields. The body must capture the context, decision, and consequences of the software design choice.

You should store ADR files in a docs/decisions/ directory within your repository. This creates a living record of architectural decisions that directly accompanies the codebase.

You need to create an architecture decision record after making significant architectural choices. Documenting these design decisions provides historical insight and explains the rationale to future engineers.

Yes, you can backfill undocumented decisions across repositories by summarizing the historical context and final choice. Converting these into ADRs establishes traceability for past architectural decisions.