AI-Assisted ADRs in Markdown: Generate, Review, and Maintain Architecture Decision Records (MADR Template + Git Workflow)

AI-Assisted ADRs in Markdown: Generate, Review, and Maintain Architecture Decision Records (MADR Template + Git Workflow)

Architecture Decision Records (ADRs) capture the “why” behind architectural choices in a form your team can review, diff, and link to implementation work. When ADRs live in your repo as Markdown, they become part of the same workflow you already trust: pull requests, code review, and Git history.

This article shows how to standardize on the MADR format, keep ADRs maintainable over time, and use AI to draft and critique ADRs without giving up human accountability for evidence, alternatives, and trade-offs.

Why ADRs belong in your repo (and why “AI-assisted” changes the game)

An Architecture Decision Record (ADR) is a short, durable note about one architectural decision. It captures the context, the choice, and the consequences. The goal is simple: help future readers answer “why did we do it this way?” without archaeology. On adr.github.io you’ll see the terminology framed as a simple set: an Architecture Decision (AD) is the choice, an ADR is the written record, and related artifacts (often called ASRs) provide broader architectural context.

ADRs work best when they live where engineering work already happens: in the repo, in Markdown, reviewed like code. Martin Fowler’s guidance is pragmatic: keep ADRs short, store them with the code, number them in a monotonic sequence, and treat them as a log. That “log” framing matters. Once a decision is accepted, you don’t rewrite it to match today’s thinking. If the decision changes, you create a new ADR that supersedes the old one and link them.

Many teams skip ADRs because of friction. Turning meeting notes into a reviewable record takes time, and the blank page is real. AI changes the economics. It can draft a first pass from transcripts, extract decision drivers, and propose comparable options. It can also run consistency checks, like “did we list alternatives?”

AI also adds risk. It can hallucinate context, sound overconfident, or invent plausible options that were never discussed. Treat AI output as a draft and a critique tool. It should not “own” the decision.

Choosing MADR for Markdown ADRs (and what makes it review-friendly)

What MADR is and why teams adopt it

MADR (Markdown Architectural Decision Records) is a standardized ADR format designed for Markdown and repo workflows. It gives you consistent headings and shared expectations. That consistency reduces “where do we put X?” debates during review.

The canonical adr/madr repo ships multiple template variants. Teams can choose the right amount of scaffolding: a full template vs a minimal one. Each is available “with explanations” (useful for onboarding) or “bare” (useful once the team has muscle memory). The MADR quick start suggests a default home (docs/decisions) and a filename pattern (nnnn-title.md) to keep ADRs sortable and linkable.

MADR can feel heavier than a free-form note. That structure is also what makes it easier to review. Reviewers can scan for the same sections every time. AI helps by filling the first draft quickly, so humans can focus on trade-offs instead of formatting.

Because MADR evolves, pin the version you base your template on. That avoids silent drift across years and repos. (As of MADR 4.0.0, the templates and guidance are published in the adr/madr repository and on the MADR site.)

The MADR sections AI should draft (and humans must validate)

Olaf Zimmermann’s MADR primer frames the core as context/problem, decision, and consequences. It also highlights supplemental sections like decision drivers, considered options, metadata, validation, and links. Those sections make reviews sharper. AI is best used to extract and organize. Humans must validate that it did not invent constraints or “launder” options.

Reviewer prompts by section:

• Context and Problem Statement → Is the problem bounded and specific?
• Decision Drivers → Are the drivers explicit and prioritized, or implied?
• Considered Options → Are options comparable at the same abstraction level (not “Kafka” vs “a managed vendor product”)?
• Decision Outcome → Does it explain “why this, not that”?
• Consequences → Are negative and second-order effects stated?

Status and lifecycle fields that make ADRs maintainable

MADR’s optional metadata (notably status, plus date, deciders, consulted, informed per Zimmermann) turns ADRs into an auditable log. It also aligns with Fowler’s rule: once accepted, don’t rewrite history. Supersede with a new ADR and link forward.

proposed → accepted → superseded (by ADR-00NN)

A repo-native ADR workflow that scales (folders, filenames, numbering, index)

Folder conventions and discoverability in docs-as-code repos

Once you commit to ADRs as docs-as-code, make one unglamorous decision early: pick a single home for ADRs. Keep it boringly consistent. MADR’s quick start suggests copying templates into docs/decisions. That works well because it sits alongside other engineering documentation and participates in PR review.

Other common patterns are docs/adr and doc/adr. The exact path matters less than stability. Stable paths make links, scripts, and onboarding docs reliable.

repo/
  docs/
    decisions/
      0001-use-postgresql.md
      0002-adopt-event-driven-integration.md
      README.md

Numbering and naming conventions (and how to avoid PR collisions)

Use a monotonic sequence number plus a short slug: nnnn-short-slug.md. Fowler recommends monotonic numbering because it sorts cleanly and stays stable as titles evolve. It also gives you a compact handle for cross-references (“ADR-0007”) in PRs and commit messages. MADR’s own guidance aligns: copy the template to nnnn-title.md and adapt.

Parallel work is where this breaks down. Two PRs can both add 0007-.... This is a real pain point discussed in the MADR repo. Three mitigations that keep process light are:

• Reserve numbers during ADR kickoff (often a quick comment in a tracking issue).
• Generate “next available” via a tiny script.
• Use a temporary xxxx- prefix and renumber on merge (only if your team accepts link churn).

Collision story: Team A opens PR with 0007-cache-auth-tokens.md. Team B opens PR with 0007-use-redis-streams.md. The maintainer merges A, then asks B to rebase and rename to 0008-use-redis-streams.md. B updates the index in the same PR so references stay coherent.

The ADR index: making decisions searchable and reviewable

An index turns a folder of files into a decision log you can scan and de-duplicate against. Keep it as a table of contents. Include number, title, status, date, and links (issue/PR plus superseding relationships). Avoid copying the ADR narrative into the index.

| ADR | Title | Status | Date | Links |
|---:|---|---|---|---|
| 0001 | Use PostgreSQL | accepted | 2026-05-14 | Issue #231, PR #245 |
| 0002 | Adopt event-driven integration | proposed | 2026-06-02 | PR #268 |
| 0003 | Replace queue with Kafka | superseded | 2026-06-20 | Superseded by [0009](0009-managed-kafka.md) |

The MADR template (copy/paste) with an AI-first drafting strategy

Provide a practical MADR template teams can standardize on

Once the workflow is repo-native, standardization becomes the lever. Use one pinned template that every ADR can be reviewed against. The canonical MADR repo ships multiple variants. The “bare minimal” template is a good default because it stays lightweight while preserving comparability across decisions (from adr/madr, template/adr-template-bare-minimal.md, based on MADR 4.0.0).

---
status:
date:
deciders:
consulted:
informed:
---

#

## Context and Problem Statement

## Decision Drivers

*

## Considered Options

*

## Decision Outcome

Chosen option: "", because

### Consequences

* Good, because
* Bad, because

Treat the headings as a contract. Tailor by adding optional sections consistently (e.g., Confirmation, Pros/Cons, More Information). Avoid per-ADR formatting experiments that make reviews slower. Add a one-line note near the top like: “Template: MADR 4.0.0 (adr/madr)” so future edits don’t drift.

Prompting AI to draft MADR sections from meeting notes (without losing nuance)

AI drafting works best when you provide raw inputs and constrain the model to stay evidence-based. Prompts that demand traceability and uncertainty markers are easier to audit in review.

You are drafting a MADR ADR. Use ONLY the notes below as evidence.
1) Extract 5–8 decision drivers as bullets. After each driver, cite the note line(s).
2) List 3–5 considered options at the same abstraction level. For each: pros/cons/risks.
3) Draft consequences across ops, security, cost, DX, and migration.
If information is missing, add an "Assumptions" bullet with "UNCONFIRMED:".

Mini-example input:

[1] Current cron ETL misses late events; on-call pages weekly.
[2] Need near-real-time (<2 min) for fraud alerts.
[3] Team knows Postgres; limited Kafka experience.
[4] Budget prefers managed services.
[5] Compliance: data must stay in-region.
[6] Peak 5k events/sec; expect 3x in 12 months.

Expected draft shape: Decision Drivers cite [1]–[6]. Options stay comparable (e.g., “Managed Kafka”, “Managed Kinesis/PubSub”, “Postgres LISTEN/NOTIFY + workers”), not “Kafka vs Vendor X”. Illustrative guardrails card (no source data provided): contrasts required behaviors vs anti-patterns when prompting an AI to draft MADR sections from meeting notes, plus a mini-example emphasizing traceability ([1]–[6]) and comparable options. Interactive spec.

Using mdedit.ai effectively in an offline-first docs-as-code workflow

In mdedit.ai, generate the MADR skeleton inside docs/decisions/. Then use contextual AI chat against the open ADR plus nearby docs (runbooks, RFCs, constraints) to catch contradictions before PR review.

When a diagram clarifies context, keep it small and reviewable using Mermaid.

Review and bias checks: turning an AI draft into an ADR you can trust

A human-first review checklist for MADR completeness

Once AI produces a structured draft, the job shifts from writing to validation. Treat the draft as a hypothesis. It becomes useful only after you confirm it captured the real constraints, alternatives, and trade-offs.

A tight checklist mapped to MADR sections catches common failure modes:

• Context and Problem Statement: bounded, specific, and explicit about what’s out of scope.
• Decision Drivers: stated as drivers (not solutions), and implicitly prioritized.
• Considered Options: comparable at the same abstraction level (a Zimmermann pitfall is mixing “a technology” with “a managed product”).
• Decision Outcome: explains “why this, not that,” referencing drivers.
• Consequences: includes negative and second-order effects (operational load, migration risk, security/compliance, cost).

Bad vs better (context):

• Bad: “We need a better messaging system.”
• Better: “We need sub-2-minute event delivery for fraud alerts, in-region only, at 5k events/sec peak, without adding 24/7 ops burden.”

Bad vs better (consequences):

• Bad: “This will improve reliability.”
• Better: “Improves replay and backpressure handling, but adds on-call surface area (consumer lag, partition hot-spotting) and requires a migration window for dual-write.”

PR review checklist (copy/paste):

• Problem statement is specific; in-scope/out-of-scope is explicit
• Drivers are drivers (not solutions) and reflect real constraints
• ≥2 alternatives listed; options are comparable at the same abstraction level
• Outcome explains “why this, not that” (ties back to drivers)
• Consequences include at least one negative / second-order effect + mitigation idea
• Status/date/deciders filled in; links to issue/PR included

AI-assisted review prompts that reduce bias and improve trade-off clarity

AI is most valuable in review when it generates pressure, not praise. Use it as a critic that produces questions, counterarguments, and explicit uncertainty. That helps humans resolve the hard parts in PR discussion.

Act as a skeptical reviewer. Argue against the chosen option.
1) Identify at least 2 viable missing options at the same abstraction level.
2) List failure modes + operational risks; propose mitigations.
3) What constraints could invalidate this decision in 6–12 months?
Return: questions to ask + assumptions to validate (mark UNCONFIRMED).

Example output you want to see: “Missing option: managed Pub/Sub equivalent”; “Missing risk: cross-region failover behavior”; “Assumption to validate: vendor SLA meets compliance audit needs.”

Review mechanics in Git: PR-based readout and comment resolution

Run ADR reviews like code reviews. Keep the unit of work small: one decision per ADR, one ADR per PR. A “readout” style review works well. Start with written comments, then hold a time-boxed discussion with a lean attendee list. This approach also matches guidance from large-scale ADR usage writeups, such as the AWS Architecture Blog.

Keep ADRs short by linking to longer design docs instead of embedding them.

PR description template:

ADR: 0012 - <title>
Decision deadline: YYYY-MM-DD
Summary: <1–2 sentences>
Stakeholders: Deciders: @... | Consulted: @... | Informed: @...
Links: Issue #... | Design doc: <url> | Related ADRs: 0007, 0009
Review focus: drivers, options comparability, consequences completeness

Keeping ADRs alive: linking to PRs/issues, superseding decisions, and automating consistency

Linking ADRs to issues, PRs, and commits (traceability patterns)

Once an ADR is merged, its value compounds when it’s easy to traverse from “why” to “where it changed.” Put links where reviewers expect them. Mirror the ADR number in Git metadata so search works across tools.

In the ADR, keep a small link hub (often a “More Information” section in MADR) that points to discussion and implementation:

## More Information

- Related: #231 (problem statement), https://github.com/acme/repo/pull/245 (ADR review PR)
- Implemented by: https://github.com/acme/repo/pull/260, https://github.com/acme/repo/pull/277
- Supersedes: [0007](0007-cache-auth-tokens.md)
- Superseded by: [0012](0012-rotate-tokens-with-oidc.md)

In Git, repeat the handle in human-scannable places:

PR title: ADR-0012: Rotate tokens with OIDC
Merge commit: Merge PR #277: implement OIDC rotation (ADR-0012)

If you want stronger “link/supersede” semantics, tools like git-adr (which stores ADRs in git notes rather than Markdown files) are a useful inspiration. File-based Markdown ADRs still keep reviews and diffs straightforward for most teams.

Superseding an ADR without losing history

Supersede when reality changes. Common triggers include new constraints, scale, compliance, or failed assumptions. Fowler’s rule is the guardrail: don’t rewrite accepted ADRs. Create a new one and link them so the log stays honest.

---
status: superseded
---

Superseded by: [0012](0012-rotate-tokens-with-oidc.md)

In the new ADR, add a clear back-link (“Supersedes: 0007”). Explain what changed and why. Avoid rewriting the old rationale.

Lightweight automation: consistency checks that don’t annoy teams

Automation should protect conventions without trying to grade writing. Keep CI fast and actionable. Enforce filenames, required headings, allowed statuses, and that the index changed when a new ADR is added.

import re
import sys
import pathlib

ADR_DIR = pathlib.Path("docs/decisions")
NAME_RE = re.compile(r"^\d{4}-[a-z0-9-]+\.md$")
REQUIRED = [
    "## Context and Problem Statement",
    "## Decision Outcome",
    "### Consequences",
]
ALLOWED_STATUS = {"proposed", "accepted", "superseded"}

for p in ADR_DIR.glob("*.md"):
    if p.name == "README.md":
        continue

    if not NAME_RE.match(p.name):
        sys.exit(f"Bad ADR filename: {p}")

    txt = p.read_text(encoding="utf-8")

    for h in REQUIRED:
        if h not in txt:
            sys.exit(f"Missing heading {h} in {p}")

    # Very lightweight front matter check: only validate if a status key exists.
    m = re.search(r"(?m)^\s*status:\s*([a-z-]+)\s*$", txt)
    if m and m.group(1) not in ALLOWED_STATUS:
        sys.exit(f"Bad status '{m.group(1)}' in {p}")

Closing: a practical adoption plan for teams starting from zero ADRs

Adopt MADR with AI the same way you adopt any engineering practice: start small, make it repeatable, then add guardrails once the team feels the value.

Start with 3–5 high-leverage decisions that will otherwise get re-litigated: database choice, API style (REST vs gRPC), deployment model (containers vs serverless), auth approach, and eventing/messaging. Pick decisions that already have an issue, a deadline, and stakeholders. Avoid hypothetical debates. Write ADRs only when you’re about to commit to work.

Roll out in a sequence that stays lightweight. First, standardize the boring parts: one folder, one filename convention, one pinned template, and an index. Next, add AI drafting prompts to reduce the blank-page tax, and keep humans responsible for correctness and trade-offs. After you’ve written a handful of ADRs, add CI checks so the conventions stick.

Define a clear “definition of done” for an accepted ADR so reviews don’t stall:

1. File is in docs/decisions/ and named NNNN-slug.md.
2. Status is accepted, date is set, and deciders are listed.
3. Context is bounded; at least 2 alternatives are recorded.
4. Consequences include at least one negative/second-order effect.
5. Linked to the driving issue and the ADR PR; implementation PRs reference ADR-NNNN.
6. Index (docs/decisions/README.md) updated in the same PR.

A first-month snapshot that’s realistic for a team starting from zero:

Week 1: Add template + index; write ADR-0001 (database) and ADR-0002 (deployment).
Week 2: Use AI to draft ADR-0003 (API style) from meeting notes; run first “readout” PR review.
Week 3: Add lightweight CI checks for filenames/status/headings; write ADR-0004 (auth).
Week 4: Supersede ADR-0002 due to compliance constraint → ADR-0005; mark ADR-0002 as superseded; index shows both.

If you do only three things, do these: standardize on MADR, use AI to draft and challenge the record (not to decide), and use Git links plus superseding to keep the decision log honest as the system evolves.