Record What You Rejected, and Make Your Agent Check It: Lessons from 495 ADRs

In karasu, the architecture-diagram tool I develop, I keep design decisions as ADRs (Architecture Decision Records) under docs/adr/.
I started on day one in March 2026, and eight months later there are 495 of them.
Claude Code does most of the development, and 80% of the commits that added an ADR (395 of 495) carry a Claude Code co-author line.

In July I ran a controlled experiment, asking an agent to redo an already-rejected proposal, to find the conditions under which ADRs work.
This time I looked at the traces left by day-to-day use instead: where ADRs were cited, by whom, and what they changed.

What I learned

1. Keep the options you rejected. That is what the agent brings back. When I asked for something I had already ruled out months earlier, the agent found the rejection and the reason, and the reason ended up shaping the design.
2. Make "check past decisions, especially rejections" a required step in the skill you design with. In 15 of the 17 sessions that used my design-doc skill, the agent cited an ADR that had rejected the idea or conflicted with it. The one sentence that worked in July's experiment works in daily use in the same shape.
3. Expect a confirmation at every override. The same step makes the agent stop whenever a request overturns a past decision. Writing "when it's fine to overturn this" into the ADR helps, but I can rarely foresee that when the ADR is written.

What I looked at

• ADRs: the body and frontmatter of all 495 (2026-03-12 to 11-09)
• Issues and PRs: the bodies, comments, and reviews of 1,342 issues and 2,397 PRs
• Claude Code session logs: the last month (2026-10-13 to 11-10), 149 main sessions and the 442 subagents they launched

karasu has had ADRs since day one, so there is no before and after to compare.
What follows is the work ADRs are doing, as observed, not a claim that ADRs caused things to get better.

The agent brings your rejected ideas back

Where ADRs help me most is when I put something I want to build into a prompt.
The agent points out ideas I had already ruled out, with the history behind them.
Reconsidering in light of that gets me to a better spec and design.

The logs had exactly this scene.

karasu sorts PRs into risk tiers by what they change.
Low-tier PRs go in through auto-merge without a human reading them.
Claude Code turns on that auto-merge, and in auto mode, a classifier (an LLM) decides whether the command may run.
On November 2, I asked whether this could move to GitHub Actions.
Every ten minutes, look at the risk: low PRs and merge the ones whose CI has passed.
That way, I thought, merges would be reliable without going through the LLM classifier.

The agent agreed with the idea, and said that since it would replace ADR-3286, which set up the current risk tiers, the right start was a design doc.
Following the design-doc skill's step for checking past decisions, it stopped like this (the agent's messages here are my translations from Japanese):

Found an important prior decision. ADR-3416 rejected "having Actions enable auto-merge."

ADR-3416 records the decision about regenerating the ADR index every day.
The option it turned down failed on who the merge is attributed to.
When Actions merges, the merge is made as GITHUB_TOKEN, and that push to main does not trigger workflows such as deploy.
My idea also has Actions do the merge, so it walks into the same trap.
Even for Low PRs, changes to the documentation site would stop being published.

The rejection reason stayed in the finished design in three places:

• The design takes as a premise that merging with GITHUB_TOKEN does not trigger push workflows.
• Triggering them needs a new key (a GitHub App or a personal access token). That overturns "add no new keys," which ADR-3416 listed as a benefit, so it was split out as a decision for me to make.
• A new test perspective asks "does the path into main use an identity that triggers push workflows?", and records ADR-3416 as its root cause.

The implementation started with a workflow that only reports its verdict.
It doesn't merge or comment yet.
Without the rejection reason, I might first have noticed the breakage in production: merges working, the site not updating.

Make the check a required step

The pointer was not luck.
In July's experiment, I added one sentence before the request:
"Before writing a design or implementation plan, search docs/adr/ and always check for related decisions or rejections."
That sentence flipped reaching the rejected ADR from 0/3 to 3/3.
After that result, I changed hane, my collection of Claude Code development skills.
The skill for writing design docs and the skill for starting development now have a required step: check for conflicts with past decisions, especially rejections (hane's ADR-63, 2026-07-09).

July's piece measured only the form where the sentence sits in a standing rule.
For the form where it is a step in a skill, I hadn't measured compliance.
These logs are a field record of that skill form.
In the last month, in 15 of the 17 sessions that used the design-doc skill, the agent cited an ADR that had rejected the idea or conflicted with it.
(I counted messages where an ADR ID appears together with words such as "rejected," "dropped," "conflict," or "overturn," and read six of them one by one, including the ones quoted here.)
In the other cases I read, too, the agent stopped before starting on the design:

Found an important precedent. ADR-2898 had already turned down auto_incremental_review: false in its "rejected options."

ADR-2249 and ADR-2262 have a record of "rejected putting a counter on the permalink page."

Rejections settle things in issues and reviews too

ADRs were also cited along the human-facing paths.
Leaving out each ADR's originating issue and PR, 408 of the 495 ADRs (82%) were cited by issues or PRs opened after the ADR was written.

One way they were cited was to close a proposal on the strength of a rejection.
A proposal to track post-merge verification items on the originating issue (#2957) was dropped because it was listed among the rejected options of ADR-3271.
A proposal to let usecases declare attribute-based authorization (#832) was dropped too.
ADR-834 had decided to keep security and threat modeling out of karasu's vocabulary and leave them to companion documents.
The same reasoning applies to authorization.

A rejection can also set the scope of a new feature.
In April, ADR-105 decided not to implement PNG export.
A PR in June (#1796) put PNG output in a single server-side function, and stated that it does not overturn ADR-105, which had dropped PNG for the CLI and the app.
The rejection record was used as the boundary of what to build.

In reviews, ADRs come up as grounds for declining a suggestion.
A typical case is replying to an AI code review (CodeRabbit) that applying the suggestion would make ADR-2693 inconsistent with the series it belongs to.
One caution: reviews posted under my name include ones Claude Code wrote, and I can't tell whether a person or the agent made a given citation.

Decisions also travel in code comments

ADR decisions are also copied into the code.
167 ADRs are cited from non-test code, and 76 from tests.

The copies keep a job after an ADR is replaced.
Of the 25 superseded ADRs, 15 are still cited from code or configuration.
In the ones I read, these weren't leftovers someone forgot to update.
For example, one file opens with this line:

 * The one direction of ADR-1990 decision 2 that survives.

Replacing an ADR is recorded one whole ADR at a time.
In practice, though, part of a decision can survive.
The code comments seem to fill in that finer grain by hand.
The agent sees these comments whenever it reads the code.
Part of the decision reaches it without opening the ADR.

The cost: a confirmation at every override

Where ADRs feel like a drag is when I want to overwrite past history.
Even when I ask for a change on purpose, the agent stops each time to confirm.

In the logs, confirmation questions that mention an ADR appeared 29 times in 27 of the 149 sessions.
Seven of them asked, in effect, "this changes an existing ADR, how do you want to proceed?"

Do you want High PRs automated all the way to merge too? Right now ADR-3286 only allows auto-merge for Low.

This is the procedure working as written.
The rule in July's experiment said: "If the proposal overturns a past decision, don't proceed silently; state that it overturns it and get confirmation."
The step that brings past rejections in and the step that stops at every override are two sides of the same thing.
One way to lighten the confirmation is to write into the ADR, as re-evaluation conditions, when it would be fine to overturn it.
In July's experiment, too, when re-evaluation conditions were written down, the agent built its confirmation question around them.
But at the time an ADR is written, I rarely can see far enough ahead to know the conditions for overturning it.
Writing them down when I can foresee them is about as far as it realistically goes.
Otherwise, the confirmation at every override stays.

Limits

This is observation and does not show cause.
The logs can't tell me what would have happened if the agent hadn't pointed out the rejection.
The session logs cover only the last month, the final one of the eight months of ADRs.

I also didn't count the cost of keeping ADRs.
ADR bodies keep getting longer: the median went from 2,308 characters in March to 6,941 in November.
When one ADR holds several decisions and a later ADR overturns only part of it, the list of current ADRs that I generate for people keeps showing the old decision as current.
I'm working on how to express that on the tooling side (kompiro/adr-tools#37).

Takeaways

The effect of ADRs showed up not when they were written but when they were cited later.
The sentence I found in July's experiment, check past decisions before you design, became a step in a skill, and in 15 of the 17 sessions that went through that step, the agent brought in past rejections.

If you keep a record of the options you rejected, the agent brings them to the next request.
A record of an idea I had considered and turned down became, when I made a request in the same direction, the occasion to rework the design.