How to keep architecture decision records and a decision log when Claude Code and Codex make decisions faster than anyone writes them down: the agent records each decision in the page it affects, with who decided, when, what was rejected and a quote from the session.
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:
- Looks at what the session changed, and finds the wiki pages that cover those files.
- Lists the decisions people made, with who, what was not chosen and why, plus the questions answered or left open.
- Drops routine progress and anything the code or
git logalready says. - Writes each decision into the page it affects, and updates or flags pages the change made stale.
- 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:
## 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.
Related pages #
-
Nimbalyst WikiA local wiki your coding agents write for you, so you can think, organize and set direction.
-
How to Keep a Project Wiki with Claude CodeInstall, setup, capture and recall with the Claude Code plugin.
-
Overwhelmed Working with Coding Agents?Why several agents outrun what one person can track, and how a wiki written for you helps.
-
Docs: Capture Decisions at the End of a SessionWhat capture writes, and how a decision is marked.
-
Nimbalyst Wiki vs Basic MemoryA project wiki in your repo, or a notes graph for your AI.
Related posts #
-
Overwhelmed Working with Coding Agents? Have Them Write You a WikiRunning several Claude Code or Codex sessions produces more decisions and open questions than one person can track. Here is the approach we use: the agents distill their work into a short wiki for you, and you read, think and set direction.
-
AGENTS.md vs CLAUDE.md: Where Instructions Go, and Where Decisions GoAGENTS.md and CLAUDE.md both hold instructions for coding agents. Here is how they differ, how Claude Code reads each one today, and where your decisions and open questions should live instead.
-
How to Keep a Project Wiki with CodexAdd the free Nimbalyst Wiki to Codex with the Codex CLI plugin or one codex mcp add command for the Codex app and IDE extension. Codex writes a markdown wiki of decisions and open questions in your repo that you read and edit in your browser.