create-adr

An Architecture Decision Record (ADR) is a document that captures a significant technical decision, its context, alternatives considered, and consequences. ADRs standardize how teams document architectural choices, providing future developers with the rationale behind decisions and making it easier to understand why certain technical paths were chosen.

Create a file in docs/adr/ with the naming convention NNNN-descriptive-title.md, where NNNN is a sequential number. Follow the provided ADR template to document the decision context, alternatives evaluated, and expected consequences. Store the file in version control alongside your codebase.

Write an ADR for major architectural decisions, technology selections, significant API designs, and design trade-offs where the rationale and alternatives matter for future maintainers. Comments capture implementation details; ADRs capture the strategic reasoning behind structural choices.

Yes. The ADR workflow includes validation and governance mechanisms to ensure consistent template usage, proper versioning, and standardized naming conventions. This enforces discipline across the team and keeps architectural documentation reliable and discoverable.

Follow a three-step workflow: gather context about the problem and constraints, investigate alternatives and their trade-offs, then create the ADR document using the standard template. This structured approach ensures decisions are thoroughly reasoned before documentation.