Skip to content
Software Architecture Guide

GenAI Support for Architectural Decision Records

Explanation

Section titled “Explanation”

An architectural decision record (ADR) captures why a team chose a design. See Architectural Decision Record for the basics. Generative AI, meaning large language models (LLMs), can help with this work.

Drafting ADRs. The biggest reported win is speed. This is most true for retrospective documentation, where a team writes down decisions it made earlier. The AI produces the draft. People then focus on the core arguments.

Using prior ADRs as context. A study of LLM-generated ADRs found that context-aware prompting substantially improves fidelity. Giving the model the ADRs already in a repository helps it draft the next one.

Exploring options. Practitioners ask the model for two to five viable options, each with pros and cons. They then pick one in a human brainstorming session. The model supplies candidates. It does not make the decision.

Validating the output. The model may add incorrect or exaggerated details to the pros and cons, so a person must check them. Reports show concrete failures:

  • Tools have invented non-existent APIs, web pages, and even product features.
  • A study of LLM-generated design rationale included interviews with six practitioners. It found that 1.59% to 3.24% of the arguments were potentially misleading.

Why wrong ADRs hurt. A wrong ADR becomes noise. It can also mislead future team members who trust the record.

Example

Section titled “Example”

A team never wrote down why it chose a message queue two years ago. It gives an LLM its existing ADRs and a few keywords. The model drafts a record in the team’s usual format within minutes. An architect reads the draft and finds a product feature that does not exist. The architect removes that claim, corrects the pros and cons, and only then commits the record.

Trade-offs

Section titled “Trade-offs”

Benefit: much faster drafting, especially for decisions made in the past, so people can spend their time on the core arguments.

Cost: every draft needs careful human review. Invented references and exaggerated pros and cons are real risks. An unchecked wrong ADR is worse than a missing one, because it misleads later readers.

Checks

Section titled “Checks”
  • AI-generated ADRs show evidence of human review before being accepted.
  • References in AI-drafted ADRs (APIs, web pages, product features) were checked to exist.
  • Pros and cons suggested by an AI were validated for incorrect or exaggerated details.
  • The final choice among AI-suggested options was made by people.
Section titled “Related”

Sources

Section titled “Sources”