An automatic decision log for code your agents write

You cannot generate architecture decision records for agent-written code by asking a model to read the code afterwards; it invents reasons. The record has to come from the moment the decision was made: the session transcript and the pull-request thread. Backthread reads those, holds each decision until the change merges, and logs only the reasoning that was actually there, so the team can see why its system is shaped as it is.

Why hand-written ADRs stop at agent speed

The Architecture Decision Record was designed for a particular tempo. A team makes a consequential choice every week or two, someone writes a page with Context, Decision and Consequences, it gets reviewed and numbered, and the folder becomes the memory of the project. The format assumes that decisions are rare enough to be worth a ceremony, and that the person writing the record was in the room.

Neither assumption holds when coding agents write most of the code. A single engineer with an agent can open a dozen pull requests in a day, each carrying two or three choices that would once have deserved a paragraph: retry here rather than there, this table denormalised, that boundary moved. Nobody writes a dozen ADRs a day. So the folder freezes at the last decision a human found time to write up, and the code moves on without it.

Addy Osmani saw the problem in November 2024 and proposed the obvious fix: tell the agent to keep an fyi.md or ai_decisions.log in the repo, recording "what, why and how it did what it did", because "we need to understand why the AI made certain choices, not just what code it spat out." His caveat is the part most teams skip: "Don't trust, verify. Regularly review the log. It's your responsibility to ensure it's accurate."

That caveat is where the approach quietly fails. A log the agent appends to inside its own session is only as good as that session's view of things, it lives on one machine, it records work that may never merge, and reviewing it is a second job that nobody is measured on.

Can you automatically generate architecture decision records?

Yes, and the current answers fall into three families. They differ in one thing that matters more than the tooling: where the why comes from.

The second family is the one that ranks for this query, and its own authors are candid about the limit. A Codex CLI guide to automated ADR generation (April 2026) notes that agent-generated ADRs from codebase scans "will capture what was decided but may fabricate the why." That is not a rough edge to be polished later. A decision log whose reasoning was written by a model looking at the outcome is a plausible-sounding fiction attached to every change, and it is more dangerous than an empty folder, because it ends the question.

The third family is what Backthread does, and the rest of this page is about the constraints that make it honest.

What a decision log has to do to be trusted

Capture from the session, not from the code

An agent session contains the deliberation as it happened: the approach it considered and dropped, the assumption it stated before writing the migration, the edge case it deliberately left. The pull-request thread contains the second layer, the reviewer's objection and the author's reply. Both are records of a decision being made. The code is only the residue.

Backthread's extractor reads those two sources and pulls out the decision, the alternatives that were weighed, the trade-offs accepted, the assumptions and the risks. It runs on the engineer's machine first; source is stripped before anything leaves, and the redaction library is open so that the fence can be audited.

Hold it until the work merges

Most of what happens in an agent session does not ship. Branches get abandoned, approaches get reverted mid-session, three attempts collapse into one PR. A log that records every decision as it is made fills up with roads not taken, and the reader cannot tell which ones are load-bearing.

So each captured decision is held silently until its change reaches the tracked branch. The log is a record of what shipped, dated by merge, and a decision whose branch died never appears. When the capture context and the PR do not line up exactly, which happens with squash merges and worktrees, the link is made by matching content and shown as "likely in #N" rather than passed off as certain.

Never fabricate, and say when there was nothing

This is the constraint that separates a decision log from a documentation generator. When the transcript contains a choice but no deliberation, the decision is recorded with an empty alternative and an empty trade-off. An evaluation gate checks that the extractor does not start padding to look thorough.

The result is uncomfortable and useful. On our own repository, 1,613 of 4,302 decisions captured from agent sessions carry any recorded alternative or trade-off. The other 62 percent were made without weighing anything, mostly the cheap, reversible choices that nobody bothers to deliberate when the agent will rewrite them on request. A scan-and-draft tool would have given every one of those a Context section. The honest log shows you which parts of the system were built without a reason ever forming, and that is a finding, not a gap in the tooling.

What the leader gets that an ADR folder never gave

An ADR folder is a list. It tells you what was decided, in the order someone wrote it down, and nothing about whether the people now maintaining the system know any of it.

A merge-gated log attached to the system map does three things the folder cannot:

• Decisions are placed. Each one is anchored to the area of the system it changed, so "why is checkout shaped like this" is a question with a page, not an archaeology project through PR descriptions.
• The reasoning becomes teachable. Because the why is recorded per merged change, it can be handed back inside the coding agent when an engineer touches that area, in the flow of the work rather than as a reading assignment. That is the point of the record: not that it exists, but that the people who did not make the decision come to hold it.
• Coverage is visible. The how-it-works view shows, per area, how much of the recorded reasoning the team can actually explain, with the git-inferred estimate capped and labelled. An area with nothing on record says so rather than reporting a number.

The daily or weekly digest of merged decisions closes the loop for the leader who does not open the app: what shipped, with its reasoning, and where the record is thin.

When a hand-written ADR is still the right tool

For the small number of decisions that are genuinely contested, an ADR written by a person is still better than anything extracted. BrainGrid's guide to ADRs for coding agents (August 2026) draws the line well: write one "only when a decision was genuinely contested, when the obvious choice was wrong for a non-obvious reason, or when you can already imagine a future agent undoing it." Keep doing that. Those records are also exactly the kind of PR prose the extractor picks up, so they land in the log alongside everything else.

The same goes for standing rules. If the team has settled that it does not use an ORM, the place for that is a context file the agent reads before it starts, and we have written separately about what CLAUDE.md, Cursor rules and Copilot Memory do and do not cover. Rules prevent the agent from re-litigating a settled choice. A decision log records the forty choices a day that were never settled by anyone.

If you want to start with nothing more than a hook, add-reasoning-to-prs is a free, open-source Claude Code hook that makes the same agent write its decisions, trade-offs and assumptions into the PR description at the moment it is opened. It is the cheapest possible version of capture-at-the-source, and it feeds the same PR prose a full log reads.

Connect one repo and the log starts at the next merge; decisions already in your PR history are mined on request, and everything before that stays honestly blank. The trial runs fourteen days with everything on.