Español

The ADR Alternatives Section Is Gold

The most valuable part of a decision doc is the options you did not choose. Your AI assistant inherits your codebase but not your reasoning: it sees only what you built, so it happily re-proposes the very thing you ruled out six months ago. One section in your Architecture Decision Records fixes that.

Why agents keep suggesting what you rejected

An ADR, in Michael Nygard's original 2011 format, has five parts: Title, Context, Decision, Status, Consequences. Notice what's missing — the losers. The doc records what you picked and why it's good, but not what you evaluated and why it lost. A human teammate can ask you in the hallway; a coding agent reading your repo cannot. To the agent, "we use Postgres" is a fact, not a verdict. Without the verdict, "have you considered MongoDB for this?" is a perfectly reasonable suggestion — for the fourth time.

AWS's prescriptive guidance on ADRs puts it plainly: the most powerful aspect of the structure is that it captures the reason for the decision, which is what prevents people who weren't in the room from re-litigating it later. Agents are the ultimate "not in the room" contributor.

The mechanism: Alternatives Considered

Add an Alternatives Considered section to every ADR. For each rejected option, write three things:

The MADR template (Markdown Any Decision Records) bakes this in as first-class sections — Considered Options and Pros and Cons of the Options — so if you're starting fresh, use it rather than inventing your own. A concrete example:

## Considered Options

* PostgreSQL
* MongoDB
* DynamoDB

## Pros and Cons of the Options

### MongoDB — rejected
* Good: flexible schema for the ingest prototypes
* Bad: our reporting queries are relational joins; we'd rebuild them in app code
* Why it lost: 80% of query load is multi-table aggregation — wrong shape for a document store

That last line is the guardrail. When your agent reads it, "switch to Mongo" stops being a plausible refactor and becomes a documented dead end.

Power-user moves

• Feed ADRs into agent context deliberately. Put the docs/adr/ folder in your agent's instruction file (CLAUDE.md, AGENTS.md, cursor rules) with one line: "Read relevant ADRs before proposing architecture changes; do not re-propose rejected alternatives."
• Rejected ADRs count too. In the AWS process, a team can reject an entire ADR — and the owner records the reason precisely "to prevent future discussions on the same topic". Keep rejected ADRs in the repo; they're guardrails, not garbage.
• Supersede, don't edit. Accepted ADRs are immutable. When the world changes (Mongo ships the feature that killed it), write a new ADR that supersedes the old one. Your agent then sees the timeline, not a silently rewritten history.
• Write the deciding factor as a testable condition. "Rejected: adds a second database to operate" ages better than "rejected: too complex" — the agent (and future you) can check whether the condition still holds.

Resources

• Documenting Architecture Decisions — Michael Nygard (2011)
• MADR — the Markdown Any Decision Records template
• Why write ADRs — GitHub Engineering blog
• ADR process — AWS Prescriptive Guidance
• Architecture decision record — template collection by Joel Parker Henderson