Writing an ADR With AI — Deciding, Not Just Drafting

TL;DR — Don't ask a model to write the ADR; ask it to pressure-test the decision. You write Context by hand — it's private facts about your team, your build, your crash rate, and it's the only section a model genuinely can't produce. Then have it generate options (including the one you'd reject), project consequences at 3× scale, and finally attack your chosen option as the engineer who'll maintain it in two years. You write the Decision sentence yourself. It reliably invents benchmarks, cites stale library behaviour, and will never tell you an ADR isn't needed.

What an ADR is for, briefly

An Architecture Decision Record is a short document — Context, Options, Decision, Consequences — written at the moment of deciding, not afterwards. Its whole purpose is that in two years someone asks "why is the domain layer a separate Gradle module?" and the answer isn't a shrug.

Almost every team agrees they're valuable. Almost no team writes them consistently. The reason is boring: it takes an hour, and the decision already feels made.

That's the actual thing AI changes here. Not quality — cost. And a decision record that gets written beats a better one that doesn't.

The failure mode: a polished record of nothing

Prompt: "Write an ADR for adopting Kotlin Multiplatform for our domain layer."

You get a well-formatted document with a Context section that says "our team maintains separate Android and iOS applications with duplicated business logic", Options listing KMP, Flutter and "status quo", and Consequences reading:

Increased initial complexity, offset by improved long-term maintainability and reduced duplication.

That sentence is true of every architectural decision ever made. It's a shape, not a consequence. And the Context was generated from the title, which means the document contains no information — it's a decision-shaped artifact recording that you typed a decision into a prompt.

Worse, it's persuasive. It reads like the output of a deliberation that never happened, and six months later it will be cited as though it were one.

Section by section: who writes what

Context — you, by hand, with numbers

This is non-negotiable and it takes ten minutes:

Context (I write this):
- 4 Android engineers, 2 iOS. One Android dev has shipped Swift.
- Domain layer today: 11k lines Kotlin / 9k lines Swift, ~70% conceptually duplicated.
- 3 bugs in the last quarter were "fixed on one platform only".
- CI: Android build 6 min, iOS 14 min. No shared build infra.
- We ship every 2 weeks. Next big release is in 5 weeks.
- Constraint: nobody is available to own build tooling full-time.

Every line is a private fact, and every line changes the answer. "One dev has shipped Swift" and "nobody can own build tooling" between them decide this ADR more than any general argument about KMP will.

A model given this context produces something useful. A model given the title produces a brochure.

Options — the model, deliberately widened

Given the context above, give me four options including doing nothing.
Steelman each in 3 sentences — argue it as its strongest advocate would.
Then, for each, name the single thing most likely to make us regret it.

Two instructions matter here. "Steelman" stops it quietly ranking options by popularity — without it you get one recommended option and three straw men. "Include doing nothing" matters because status quo is the option teams skip writing down, and it wins more often than anyone admits.

The value is the option you hadn't considered. In this example it's usually "share only the networking and serialization layer" — a smaller cut than the one you framed the question around.

The question that does the actual work

Options are easy. Consequences are where decisions are made, and they're the section everyone thins out because writing down a cost feels like arguing against yourself.

For each option, project 18 months out. Assume:
- 3× the current module count
- one fewer senior engineer than today
- a major Kotlin/AGP upgrade in between

What breaks? What becomes someone's unwanted full-time job?

"What becomes someone's unwanted full-time job" is the most productive prompt I've found for architecture. It surfaces the maintenance cost that never appears in an evaluation, because during the evaluation the person excited about the technology is the one doing the work.

Decision — you, one sentence

Decision: We will share the networking + DTO layer only, keeping domain
logic native on both platforms, and revisit in two releases.

Write it yourself. If you can't write the decision in one sentence without hedging, you haven't made it yet — and that's useful information, not a formatting problem.

Consequences — the model, as your critic

The prompt that earns its keep:

You're the engineer who inherits this codebase in two years and has to
add a feature that spans the shared layer. I made the decision above.
Write your complaint. Be specific and unkind.

You'll get things like: the shared module's tests only run in CI on Android, so iOS breakages are found late; every Kotlin upgrade now blocks two apps; debugging a shared crash means reading a stack trace that crosses a boundary your tooling doesn't. Some of it will be wrong. The half that isn't goes straight into Consequences.

An ADR with no negative consequence isn't a decision record, it's marketing. This prompt is the cheapest way to make sure there's at least one honest one in there.

Where it lies, in exactly this task

Every AI post in this series names what the model gets wrong, and ADRs have a specific set:

1. Invented benchmarks. "Approximately 30% faster build times" — from where? Generated numbers look exactly like measured ones and are far more confident. Rule: no number in an ADR that you didn't measure or can't cite by link. Strip every unsourced figure; they're the most dangerous content in the document because the next reader will treat them as evidence.

2. Stale library reality. Fast-moving tooling — AGP, KMP, Compose Multiplatform, Room's KMP support — is where training data ages worst. It will describe limitations that were fixed a year ago and miss ones introduced last quarter. Verify anything load-bearing against the current release notes.

3. "Industry standard" as an argument. It'll tell you an approach is widely adopted. That's a popularity claim, usually unverifiable, and it's not a reason. Ask "why does our context make this right" and it'll drop the appeal.

4. It will never say the decision is too small to record. Ask for an ADR on your logging library choice and you'll get one, complete with four options and a consequences matrix. Bureaucracy generates just as fluently as insight. The filter stays human: does this decision constrain future work in a way someone will need explained? If not, don't write it.

5. It smooths over disagreement. If two engineers genuinely disagreed, that belongs in the ADR — the rejected argument is the most valuable thing in it. A model will synthesise both into a consensus that nobody held.

The whole loop, timed

1. Write Context by hand — 10 min
2. Generate + steelman options — 2 min
3. The 18-month consequences prompt — 2 min
4. Write the Decision sentence — 1 min
5. The "write your complaint" prompt, edit the output down — 5 min

Twenty minutes, and the shape of it is an argument you had rather than a document you produced. The two prompts that changed my decisions most often are the 18-month projection and the complaint — both of them attack, and attacking your own idea is the part humans are worst at doing alone.

One thing to keep human, always

The trigger. Noticing that a conversation in a PR thread was actually an architecture decision, and should be recorded before it evaporates — no tool does that for you. The failure of ADR practice is almost never the writing. It's that the decision was made in a chat, by two people, on a Thursday, and nobody named it as a decision.

The rule

The document isn't the artefact — the argument is. Use the model to widen the options and attack the choice, keep the context and the decision sentence in your own hands, and delete every number it produced that you can't source. What you're left with is short, honest, and worth reading in two years.