Architecture Decision Records Written by Your Coding Agent

An architecture decision record captures one decision and why it was made, and a project’s collection of them is its decision log. When you build with Claude Code or Codex, decisions get made inside sessions faster than anyone writes ADRs, so the log falls behind within a week. We have the coding agent write the record instead: at the end of a session it marks each decision in the wiki page it affects, with who decided, when, what was rejected, and a quote from the session.

This post covers what a good ADR holds, why ADRs stall once agents do the work, how the Nimbalyst Wiki records decisions, and a decision log template you can use with or without it.

What an architecture decision record is

The ADR GitHub organization defines it this way: “An Architectural Decision Record (ADR) captures a single AD and its rationale,” and “the collection of ADRs created and maintained in a project constitute its decision log.” The idea was popularized by Michael Nygard’s 2011 post, Documenting Architecture Decisions, which gave each record five parts:

Part	What it holds
Title	A short noun phrase, such as “ADR 9: LDAP for Multitenant Integration”
Context	The forces at play when the decision was made
Decision	What was chosen
Status	Proposed, accepted, deprecated or superseded
Consequences	What follows from the decision, good and bad

Nygard numbered records and never reused a number. A reversed decision stays in the log, marked superseded, because “it’s still relevant to know that it was the decision, but is no longer the decision.”

Why the decision log falls behind once agents do the work

ADRs work when a person sits down after a design discussion and writes one. Coding agents change where decisions happen. You and Claude Code settle on the event queue for payment retries in the middle of a session, you reject the simpler option because of a provider limit, and the session ends with a merged change and no record. Codex settles three more things that afternoon in another repo.

The records stop for a plain reason: decisions now arrive at the speed of the sessions, scattered across transcripts nobody reopens, and the person directing the agents is the one who loses track first. We wrote more about being overwhelmed by several coding agents. A month later someone asks “why did we do it this way?” and the only answer is in a chat log, if it is anywhere.

Decisions in the page they affect

The Nimbalyst Wiki keeps a decision as a marked sentence in the wiki page it affects, instead of a separate numbered file:

[We retry failed charges through the event queue.]{decided by="Dana Lee" [email protected] on=2026-10-14 over="retrying inside the payment provider client"}

The mark carries the parts of an ADR that matter most later: the decision itself, who made it, the date, and what was passed over. The sentences around it hold the context and the reason. Open questions use the same form with an owner, [Do we need a mobile SDK for launch?]{open by="Dana Lee"}, and when one is answered the agent changes it to a decided mark with the date and the option that lost.

A decision that touches several areas is marked once, on the most specific page, and linked from the others. An index page lists every decision and every open question across the wiki, which gives you the decision log view without anyone maintaining it by hand. The full mark syntax is in the docs on marking decisions and open questions.

How the agent writes them

The Nimbalyst Wiki plugin for Claude Code and Codex is free, and it also works in Cursor, VS Code, Cowork and any MCP agent. At the end of a session you run /nimbalyst-wiki:capture (or ask Codex to “record what we decided in the wiki”), and the agent:

1. Looks at what the session changed, and finds the wiki pages that cover those files.
2. Lists the decisions people made, with who, what was not chosen and why, plus the questions answered or left open.
3. Drops routine progress and anything the code or git log already says.
4. Writes each decision into the page it affects, and updates or flags pages the change made stale.
5. Ends with a link to every page it touched, or says “nothing to record.”

The capture docs describe each step in detail.

When your own words in the session support a decision, the agent adds a citation copied from the session transcript, so the record shows what you said instead of a paraphrase. It never invents a decision, a reason or a quote. On a local wiki, the name and email come from your git config. In Claude Code, the plugin reminds the agent once to capture after a session with a commit, a plan or several file edits, so the habit does not depend on you remembering.

The pages are plain markdown in your repo, in nimbalyst-local/wiki by default or a checked-in folder such as docs/wiki if you want decisions reviewed and versioned like code. You read and edit them in your browser view.

A decision log template

If you want a decision log page your agent fills in, or you keep one by hand, this template carries Nygard’s parts plus the fields that make a record useful a year later. Each entry is a few lines, newest first:

# Decision log

## 2026-10-14: Retry failed charges through the event queue

- **Status:** Decided (supersedes 2026-08-02 "Retry inside the provider client")
- **Decided by:** Dana Lee
- **Rejected:** Retrying inside the payment provider client; a nightly batch job
- **Context:** The provider rate-limits retries per merchant, and inline retries blocked checkout for up to 30 seconds.
- **Decision:** Failed charges go to the event queue and retry with backoff, outside the request path.
- **Consequences:** Checkout no longer waits on retries. Retry state now lives in the queue, so support needs a view of it.
- **Affects:** [Payment retries](Payment%20retries.md)
- **Source:** Session of 2026-10-14, Dana: "Move retries off the request path; the provider limit is per merchant."

## Open questions

- Do we need a mobile SDK for launch? Owner: Dana Lee

Two fields do most of the work. Rejected answers the question people ask most often (“did we consider X?”), and Source keeps the reason tied to what someone actually said. If you track decisions as rows instead of prose, ask your agent to create a type for them (“track decisions in the wiki: status, decided by, date, rejected, page”), and the wiki keeps a table of every decision with a page or a row each.

A folder of ADRs, or decisions in the wiki

The two approaches suit different jobs, and a team can use both.

	Numbered ADR files	Decisions marked in the wiki
Where a decision lives	Its own file in docs/adr/	The page about the thing it decides
Who writes it	A person, after the discussion	Your coding agent, at the end of the session
What triggers it	Someone deciding it is significant enough	Any decision made in a session
Reason and source	Written from memory	Quoted from the session when your words support it
Open questions	Usually not tracked	Marked with an owner, listed with the decisions
Best for	Formal review of large, cross-team decisions	The many day-to-day decisions agents help you make

If your team reviews major architecture changes through ADR pull requests, keep doing that. The wiki covers the long tail of decisions that never got an ADR, and links to the formal one when it exists. If you are also weighing a memory tool for your agent, Nimbalyst Wiki vs Basic Memory explains how a notes graph for the AI differs from decision records for people.

Asking “why did we” later

Months later, ask your agent “why did we put retries in the event queue?” and it answers from the wiki with /nimbalyst-wiki:recall: each decision with who made it, when and what it was chosen over, each open question with its owner, and the pages it read. It says when a page is stale and keeps what the wiki says apart from what it infers. Pages can name the code they cover, so before an agent changes those files it can read the decisions behind them. See how recall answers from the wiki.

Put the rule in the instruction file

A decision usually produces a rule every agent should follow, such as “never call the payment provider from the request path.” Put that one line in AGENTS.md or CLAUDE.md, where agents read it on every task, and leave the decision with its context and rejected options in the wiki. Our post on AGENTS.md vs CLAUDE.md covers what belongs in each instruction file, and how Claude Code memory differs from a wiki covers where auto memory fits.

FAQ

What is an architecture decision record? A record of one architectural decision and its rationale. Nygard’s format has a title, context, decision, status and consequences, and a project’s ADRs together are its decision log.

Can a coding agent write ADRs? Yes. With the Nimbalyst Wiki, Claude Code or Codex records each decision in the page it affects at the end of a session, with who, when, what was rejected and a quote from the session, and never invents any of them.

What should a decision log template include? The decision, who made it, the date, what was rejected, the reason, the status, the page or code it affects, and a source for the reason.

Where should the rule go? In AGENTS.md or CLAUDE.md, in one line. The decision behind it goes in the wiki.

Do I need a separate ADR tool? No. The decisions are marked sentences in markdown files in your repo, with an index page of all of them. Get started with the Claude Code guide or keep a project wiki with Codex.