Clients change their minds. An ADR stops the argument starting over

Picture month three of a project. A new director on the client side joins a meeting and asks: “Why does the data sync overnight? It should be real-time.” Everyone in the room turns to look at you.

The person who signed off on that design has moved to another role, the old email is buried somewhere in an inbox, and you only vaguely remember that there was a very good reason at the time.

Microsoft Learn describes exactly this scene: a decision that was made but never recorded is easily forgotten, which leads to repeated debates or to later changes that unintentionally run against the original intent. The team either goes along because nobody can argue back, or clings to a decision that nobody remembers the reason for.

FDEs work on the client’s premises, where the people and the requirements can change mid-project, so this scene is common. The cheapest tool against it is the Architecture Decision Record, or ADR, and it needs only one or two pages.

An ADR records the reason, because the reason is what people forget first

Michael Nygard, in his 2011 post on documenting architecture decisions, argued that one of the hardest things to track over the life of a project is the motivation behind its decisions. He set a clear limit: the whole document should be one or two pages long. Martin Fowler is stricter still, advising that ADRs be kept short, usually a single page.

adr.github.io defines each ADR as capturing a single architectural decision and its rationale, with the collection of a project’s ADRs forming its decision log. AWS Prescriptive Guidance states the purpose plainly: to avoid discussing the same architectural topic over and over again.

Three minimum sections, two details people skip

According to AWS, every ADR must at minimum contain the context of the decision, the decision itself and its consequences for the project. The context should also list the options the team considered. Add a status and a change history, and you have a framework ready for the day the client changes its mind.

Two details separate a usable ADR from a box-ticking one. The first is the consequences section: record the downsides, not only the benefits. An ADR full of advantages reads like sales material and persuades nobody when someone objects.

The second is how the decision sentence is written. Make it firm, as in “The team uses…”, rather than “should use…”. “We should use batch” invites argument; “The team uses batch” is a commitment.

A sample ADR for the scenario above

Imagine you are deploying a record-search agent for an insurance company. Its IT department opens a read-only copy of the database (a read replica) only between midnight and 5am, because the core system is under load during the day. You choose an overnight sync. The ADR would look like this:

# ADR-0007: Sync records into the search index with a nightly batch

## Status
Accepted (confirmed by the client's IT representative)

## Context
- The agent needs record data from the client's core system.
- Client IT only allows reads from the read replica between 00:00 and 05:00.
- The main users are underwriters, who process the previous day's records.
- Options considered:
  1. Nightly batch from the read replica.
  2. Real-time via change data capture: not yet permitted by client IT.
  3. Calling the core system API on every query: risk of load at peak hours.
- Revisit this decision if IT enables CDC or underwriters need same-day records.

## Decision
The team uses a batch job that runs at 1am, reads the read replica and updates the index.

## Consequences
- Good: no load on the core system during business hours.
- Bad: records created during the day are not searchable until the next morning.
- Bad: if the job fails one night, data is a further day late; an alert is needed.
- Neutral: if IT enables CDC, a new ADR must be written.

Note the last line of the Context and the last line of the Consequences. They state the conditions which, if they change, mean the decision should be revisited. Those two lines turn the ADR from a memo into a negotiating tool.

When the client changes its mind, do not edit the old ADR

Back to the meeting in month three. You do not need to defend the old design, nor concede straight away. You open ADR-0007 and ask: has IT allowed change data capture yet? Or do underwriters now have to process records on the same day?

If the answer is no, the debate can end quickly, because the original reasoning still stands. If it is yes, the context really has changed and changing course is justified. At that point Fowler’s rule is strict: an accepted ADR is never reopened or edited; it must be replaced by a new one.

In practice, you write ADR-0012 for the real-time option, recording the new context and the change history. ADR-0007’s status becomes “Superseded by ADR-0012”.

Nygard wrote that when a decision is reversed, the old record is kept and simply marked as superseded. Microsoft Learn recommends linking the two records, and AWS Prescriptive Guidance stresses keeping the old one in the decision log.

Six months later, a newcomer reading this chain will understand what steps the project went through, and why.

ADRs belong in the handover package

A tidy approach is to keep ADRs in the same repository as the code they describe, in a docs/adr/ folder with numbered files. The biggest benefit for an FDE comes on handover day: the decision log travels with the code, next to the README and runbook, so the client’s operations team does not have to dig through a wiki they may not be able to access.

Treat that folder as part of the handover package, on a par with the installation docs. The runbook answers “how does this run?”; the ADRs answer the question a successor will ask when they want to change something: “why was it done this way?”

During the handover session, spend a few minutes walking through the list of Accepted ADRs and the conditions that would trigger a review of each.

Write each ADR as soon as the decision is made, while the reasoning is fresh in everyone’s mind, rather than saving them all for the final week. The AWS Architecture Blog advises that each ADR focus on a single decision. If you find yourself writing “and” in the title, split it into two files.

The mistakes that turn ADRs into waste paper

The most common mistake is writing too much. A five-page ADR is unlikely to be read in full, so it is unlikely to rescue any meeting. The second is leaving out the options considered: when the new director proposes real-time, you need to show that the option was examined and why it was rejected.

The third is listing only the advantages, which gives sceptics a reason to doubt the whole document. The fourth is editing the old ADR directly when minds change, erasing the history that ADRs exist to preserve.

The last is when only the engineering team knows the ADRs exist. An Accepted status is worth something only once the person with authority on the client side has read and confirmed it.

A skill worth putting on your CV

Technical documentation is real work in FDE job descriptions. Tungsten Automation’s Forward Deployed Engineer posting lists writing customer-specific technical documentation and best practices to limit knowledge loss. ADRs are a concrete way to do exactly that.

So when you read a job posting, look for the lines about documentation or knowledge loss and mention this habit there. A few ADRs with client details removed in a portfolio, or an interview story about using an ADR to settle a proposed architecture change, carry more weight than any adjective on a CV.

Clients will always change their minds, and that is their right. Your job is to make each change of mind cost one new page, not three weeks of arguing from scratch.