create-architectural-decision-record

An Architectural Decision Record (ADR) documents a specific engineering choice with consistent structure and searchable semantics. It captures context, selected decisions, explicit positive and negative consequences, and rejected alternatives with rationale during planning, refactoring, migrations, and ongoing governance.

Creating an ADR with searchable semantics requires capturing context, selected decision details, alternatives, and stakeholders. The output enforces required inputs, validates missing information by prompting the user, and generates a machine-parseable structure prioritizing readability for software governance tracking.

Architecture decision tracking captures explicit consequences and rejected alternatives using coded bullet formats within the ADR. This standardizes how engineering teams document trade-offs, reducing ambiguity and making choices easier to search, review, and reuse across teams.

You do not need to manually name ADR files. The output is automatically saved into the repository documentation area under /docs/adr/ using the required adr-NNNN-[title-slug].md filename convention with the next sequential numbering format.

You can use this process with incomplete information. The generation validates missing information by prompting the user to provide required inputs, ensuring decision completeness by capturing context, stakeholders, alternatives, and rejection rationale before output.

Structured ADRs are unnecessary for trivial implementation choices lacking trade-offs or rejected alternatives. They apply specifically to software architecture decision tracking during planning, refactoring, migrations, technology selection, and ongoing governance of trade-offs across teams.