A new engineer joins, sees the billing service running on its own database, and spends two weeks building a migration plan. The plan is solid. It also re-proposes something the team already debated, rejected, and documented nowhere. "The real cost isn't onboarding time. It's the decisions that get re-litigated because nobody remembers why they were made."
This happens because the decision was made - in a Slack thread, a design review, a 45-minute call - and then lived only in the memory of whoever was in the room. The written record never materialized. Architecture Decision Records are one of those practices every developer knows they should follow, but few actually do consistently. The discipline falls apart not because people don't value it, but because the moment you'd write the record - right after the decision lands - is exactly when you're already moving on to the next thing.
That specific failure mode is now addressable. AI can draft the decision log while the context is still hot.
Why decision logs go unwritten (and what it costs)
The failure is structural, not motivational. Architecture Decision Records can be time-consuming to write well, with lots of context and thoughtful, unbiased consequences. After a decision call wraps, you have maybe 20 minutes of post-meeting energy before the next thing pulls focus. Writing a good ADR - context, options considered, rationale, consequences - takes longer than that, and it feels like admin on a task that already feels done.
Without decision records, teams re-litigate settled issues: the same arguments, the same analysis, the same conclusion - repeated quarterly because nobody remembers it was already decided. The engineering-specific version of this is brutal. Engineering turnover in tech runs 15-20% annually. For a 20-person team, that's 3-4 people leaving every year. Each departure takes institutional memory with it. Each new hire interrogates the same decisions from scratch.
There's a less-discussed cost that compounds this: as context engineering becomes critical for AI assistance, undocumented decisions mean AI can't help with organizational reasoning - it doesn't know what you've decided or why. If you're using an AI coding agent to help you refactor a service, and the decision to keep that service isolated from the billing database was never written down, the agent will cheerfully suggest the consolidation your team already ruled out. Your AI tools are only as good as the context you give them.
How AI-generated ADRs actually work
The basic workflow is simpler than it sounds. With a collection of "kernel of truth" statements ready, you can feed them into a process using AI tooling to quickly generate strong first drafts of ADRs, using metaprompting - designing an LLM prompt that acts as a template for creating a bespoke, decision-specific prompt for each decision.
In practice this means: drop the Slack thread, the PR description, or the meeting transcript into the prompt. The model extracts the context, the options that were weighed, the chosen direction, and the stated or implied consequences. It can be asked for the ticket and pull request descriptions to derive the context, decisions, and consequences. A standard ADR structure - context, decision, consequences, alternatives considered - is well within what current models can produce from messy raw material.
The standard format most teams use is MADR (Markdown Any Decision Records), a lightweight template that lives in your repo as a numbered markdown file. Required sections include a title in ADR-NNNN format, a status (proposed, accepted, deprecated, or superseded), context covering business and technical drivers, the decision and its rationale, and at least three consequences - positive and negative.
What AI adds is the drafting speed. The decision is documented while the context is fresh, and the agent handles the formatting and file creation. The human reviews, edits, and approves - but the blank-page problem is gone.
Beagle in action#architecture, 4:47pmWhere the draft falls short and what you do about it
AI-generated ADRs have a known failure mode worth naming. Under time pressure, it can be difficult to review many documents without falling into the trap where the clear, logical, and convincing LLM output sounds so credible that it discourages proper scrutiny.
The fix is a second pass before human review: a useful tool is to use a different LLM prompt as a "judge" to critique generated ADRs for logical flaws, before final human review. This is a small addition to the workflow and it catches the cases where the model stated the rationale more confidently than the actual conversation warranted.
A few practical constraints to keep in mind:
- Source quality determines output quality. A one-line Slack message ("let's go with Postgres") generates a thin ADR. A thread where someone laid out three alternatives generates a useful one. The AI can only reconstruct what was said.
- Status tracking is manual by default. When a later decision supersedes an old one, you need a convention for updating the status field. AI-generated ADRs should be validated before approval, and ADR status changes should be tracked. Some teams run a CI hook that checks for conflicts between accepted ADRs and new code changes - that's the more durable approach.
- Not every decision warrants a record. ADRs earn their keep for choices with lasting consequences: data storage, service boundaries, auth patterns, API contracts. The decision to name a variable
userIddoes not need a record.
The compounding return: a searchable decision history
Architecture Decision Records provide a structured way to capture and preserve the reasoning behind critical technical decisions. As organizations scale, managing ADRs manually becomes increasingly difficult - but by combining ADR practices with AI capabilities such as automated generation and semantic search, organizations can transform static documentation into an intelligent architecture knowledge platform.
That last phrase is where the long-term value sits. Once you have 30 or 50 ADRs in a repo, you can run semantic search across them. Ask "why did we separate the auth service?" and get a sourced answer in seconds rather than archaeology. A teammate like Beagle can read that ADR repository and answer questions about past decisions in-channel, with a link to the source record.
Building an accurate picture of project decisions and architecture that can be interrogated by both humans and AI coding tools has real value. Without AI tools, this can be infeasible at scale.
The decision log was always a good idea. The reason it didn't happen is that writing it well, from scratch, at the end of a long design call, was genuinely hard. The draft-and-approve model changes that arithmetic. The effort drops from 40 minutes to 5, the blank-page problem disappears, and the record exists before anyone forgets what was decided.
AI decision log: common questions
What is an architecture decision record (ADR)?
An ADR is a short document that captures a significant technical decision, the context that drove it, the options considered, and the consequences. The format was popularized by Michael Nygard and lives as a numbered markdown file in the codebase. Teams typically store them under docs/adrs/ and treat them as part of the repo's history.
How does AI generate a decision log from a Slack thread?
You paste the thread (or transcript) into a prompt alongside a standard ADR template. The model identifies the decision made, reconstructs the context and alternatives from the conversation, and fills in the template sections. A second review prompt can flag logical gaps before a human approves the final record. The whole loop takes under 10 minutes.
Do AI-generated decision logs replace human review?
No. The draft removes the blank-page problem and the formatting overhead, but a human should review every record before it's filed. The risk with AI-drafted documents is that confident-sounding prose can obscure thin rationale - a second reviewer or a critic-prompt catches this before approval.
What decisions are worth logging?
Any choice with lasting architectural consequences: database selection, service boundaries, auth strategy, API contract design, caching layer choices, data ownership. Skip decisions that are trivial to reverse or have no downstream dependencies. A good rule of thumb: if someone new would reasonably question the choice in six months, it needs a record.
Where do ADRs live and who maintains them?
Most teams store ADRs as numbered markdown files in the codebase repository, often at docs/adrs/. Ownership sits with the engineers and architects who made the decision. A CI hook can check that new code doesn't violate accepted ADRs - catching conflicts before merge rather than in a postmortem.