Stop Claude from re-arguing decisions: ADRs as agent memory
Every new Claude Code session starts with zero memory of what you decided last week. Ask it about your database architecture and it will suggest Postgres schemas. You rejected Postgres schemas three weeks ago. You just don’t remember that you did, and neither does it.
Architecture decision records solve this. They are short markdown files that each capture one decision: the problem, the options considered, the option chosen, and why the losers lost. The developer behind andrewconnell.com accumulated 141 of them in roughly four months of migrating 23 years of content with Claude Code as the primary coding agent. One rule file drives the whole system.
What an ADR actually contains
The format is minimal. Each record has a number, a status, an approval date, a problem statement, the options that were on the table, the chosen option, and a Rejected Alternatives row. That last field is the one that does the work: it is the reason the agent does not suggest the thing you already turned down.
Every record starts from the same template stored at docs/adrs/0000-adr-template.md. The records are numbered sequentially: 0001 through 0141 as of October 26, 2026. The first one landed on July 3, 2026, three months into the migration.
Why an AI agent specifically needs this
An agent has no persistent memory between sessions. It cannot keep the reasoning behind a decision in its context window, not across days of work. And the developer making the decisions does not keep it either. As the article puts it: I don’t keep the details of a decision in my head.
ADRs are not a memory the agent holds. They are a decision log the agent reads. The distinction matters. The reasoning lives in a file, not in anyone’s working memory, so it is available to every future session without any cost to the current context.
The analogy from the original write-up is clear: you do not remember the interest rate on a mortgage you refinanced a decade ago when rates were low. You do not need to. You made the decision, you trust the reasoning, and nothing on the horizon changes it. ADRs are the same thing for a codebase.
The four files that make the system work
The setup has four parts. None of them are Claude Code specific. Any agent that reads a project instructions file, such as an AGENTS.md, can follow the same rule.
- The template at
docs/adrs/0000-adr-template.md. Uniform structure across all 141 records. - The rule file at
.claude/rules/ADR.md. Claude Code loads every file in.claude/rules/at session start automatically, the same way it loadsCLAUDE.md. The rule tells the agent to scan for decisions worth recording at the end of every plan and ask for confirmation before writing anything. - The index at
docs/adrs/README.md. Grouped by area, with a one-line title, a status, and keywords for every record. The index is roughly 150 KB. The full set of records is about 1.1 MB. The agent opens full records only when a task touches their area, which keeps token costs down. - A pointer to the index in the rule file’s first line and in
CLAUDE.mdnext to the parts of the system each ADR governs.
How the agent proposes ADRs (and why you should not write them yourself)
The rule file instructs Claude to propose new ADRs at the end of each plan, not during it. The agent was present for the entire session. It saw every option considered and every one discarded. By the time a plan closes, it already has the raw material for the Context and Options sections. The developer’s job is to answer one question: is this worth a record?
Each proposal includes a justification for why the agent thinks the decision qualifies. The developer reports they could not find a single proposal they had turned down when reviewing their sessions for this article. The rule’s written criteria do the filtering, and a don’t over-generate instruction in the rule keeps the agent from proposing a record for every bug fix.
The system also works in reverse. The agent will flag when something is not worth a record. When it does, the developer still gets to decide, and that conversation has produced records too.
️ How to separate ADRs from your other project files
This is the part most people skip, and it causes confusion later. There are four document types in this workflow, and each one does a different job:
| File type | What it holds | Lifespan |
|---|---|---|
Rule file (.claude/rules/*.md) | Process: how the agent should do certain things | Until the process changes |
CLAUDE.md | Context: what the project is and how it fits together | Kept current with the project |
| Spec | The details of one body of work | The life of that work |
| ADR | One decision and why it won | Until a later decision replaces it |
| Plan | Step-by-step instructions for one pull request | Deleted when the PR merges |
CLAUDE.md tells the agent what is. It cannot carry the three options you compared, the tradeoffs, and the reason the loser lost without turning into a 5,000-line file that loads into every session. An ADR keeps that reasoning out of the way until it is needed.
Real examples of ADRs doing their job
Hybrid search instead of Azure AI Search (ADR 0132)
When semantic search came up, the first option was Azure AI Search as a separate store. The developer said no. ADR 0132 records why: the pgvector data alone, roughly 86 MB, blows past Azure AI Search’s 50 MB free tier, which would have cost about $75 a month on the Basic tier. It would have required a second copy of every comment that would have to follow moderation state. And it was no better at matching a version number written two ways, such as v1.12 and 1-12. The chosen option, hybrid full-text plus pgvector search inside the existing Postgres database, answered 21 of 22 test queries correctly. Re-embedding the whole site costs roughly six cents.
No Postgres schemas (ADR 0064)
When building the database, there was a decision about whether to use Postgres schemas to separate concerns. ADR 0064 rejected schemas for three concrete reasons: a trigger on a shared table already queries a comments table, so the two schemas could never actually be split apart; the one permission boundary the database needs sits inside the identity tables, not between comments and everything else; and every connection would have to get search_path right, forever. The agent reads this every time it touches the database. The developer reports they had forgotten the decision entirely until researching this article.
The highlight conflict (ADR 0003)
Two migrated articles used inline <mark> tags, and a check flagged them when generating markdown versions for AI agents. Instead of rewriting the articles, the agent stopped, cited ADR 0003, and asked how to proceed. ADR 0003 is from the first week the folder existed. The developer had long forgotten it. The agent had not, because it does not need to remember it. It just reads.
⚙️ What happens when a decision changes
You write a new ADR and mark the old one superseded. The biggest example: ADR 0107, approved September 28, 2026, superseded four ADRs that had been approved just two days earlier on September 26, 2026.
The original four (0101 through 0105, with 0105 covering two separate points) set up Microsoft Entra External ID as the identity provider for the comments system, including a self-operated OIDC bridge, a custom claims provider, keeping MSAL off normal page loads, and managing the External ID tenant as code. After deployment, the problems accumulated. The developer stopped and asked Claude directly what they were actually gaining from Entra as a user directory. The agent’s answer referenced the existing ADRs and made the tradeoffs visible. The developer’s next message was a one-word pivot.
ADR 0107 explains why Entra was dropped: the project does not need an identity provider storing reader profiles. It needs GitHub, Microsoft, Google, Discord, and LinkedIn to handle OIDC, and it needs to store a reader’s name and email to match them to their comments. That is all. Each of the four old records got a Superseded by 0107 banner and a status update in the index. ADR 0103, the decision that identity linking happens in the database rather than in Entra, survived because that part was correct. ADR 0107 amends it instead of replacing it.
The value of the superseded chain for an agent: if a future session asks whether Entra External ID would be a cleaner approach to sign-in, the answer is written down, including the fact that it was tried.
Common pitfalls
One gap surfaced while the developer was researching this article. A proposal the developer does not answer gets dropped. Claude lists ADR candidates at the end of a long session, the developer responds to the question they care about (usually to open the PR), and the agent reasonably reads silence as a no. At least once the agent said so explicitly: No answer on the ADR, so I’m skipping it. The developer caught it that time and asked for the ADR to be written. At least once they did not catch it, and those candidates were never recorded.
The suggested fix is one additional line in ADR.md: treat an unanswered proposal as still open, not declined.
Pro Tip: what the developer would do differently
Stop keeping superseded ADRs in the repo. The developer’s current preference: a superseded ADR would be rewritten to the current decision, with a short footnote pointing to the commit SHA of the version it replaced and one sentence on what changed. The agent still learns the prior approach was tried. It just does not have to read four retired records to find out. The full history stays available to anyone who wants to dig into git.
Of the 141 records as of October 26, 2026, 7 are fully superseded, 1 is deprecated, 6 are superseded in part or amended, and 6 reverse a decision recorded in a spec or issue rather than an earlier ADR.
Should you adopt this on your project?
The developer’s answer is yes, and start on day one. The one thing that made the system work: a rule that makes the agent propose ADRs at the end of every plan, with a justification, and wait for confirmation. The agent does the writing. You do the deciding.
If you are already past day one, do not backfill history. Add the rule and let the agent propose records for decisions you make from here. The ones you keep re-explaining will show up first.
One note on team dynamics: on a personal project the developer is the sole decision-maker and approves every ADR themselves. On a team with a Principal Architect, that person makes the call and writes or modifies the ADR proposal. The rule you give the agent should match who actually decides on your project.
I’m founder of BizStack at Cagri Sarigoz LLC and a passionate advocate for entrepreneurs.
With over 14 years in tech, marketing, and AI, including my role as Head of SEO at CitizenShipper and co-founder of TaleBot at Intale AI, I’m dedicated to sharing genuine, useful product insights and tips.
At BizStack, I aim to cut through the digital noise to provide clear, actionable advice.
And more than all else, I’m a father to a (always) little girl and a husband.
Contact me at [email protected] for assistance.
