Matteo
Vincenti
Menu

How to write an ADR your team can use in the next review

A worked Markdown architecture decision record that captures the choice, sets a release check, and shows when to link or supersede it.

A decision card stands beside queued jobs, a processing device and a magnifying glass over the resulting sheet.

In a fictional reporting app, the browser waits while the app generates a CSV for the month. If the request times out, the customer is left without a file. The team decides to queue the job and acknowledge the request immediately. A separate process called a worker takes the waiting job and generates the file.

The change works in staging, the environment where the team tries it out. During pull request review, someone checks the release plan and finds that it has no worker for the production export queue. The team had already agreed to use a queue. Exports stay off for customers while the reviewer works out what has to pass before opening access.

An architecture decision record (ADR) is a short document that captures a significant technical decision, the problem that led to it, and its consequences. For the CSV export, it can also tell the person running the release what they should see before enabling the feature. Michael Nygard’s ADR format.

When to write an ADR

The team could keep the old flow and cap the size of each report. It would have fewer components to run, while some customers would have to split the month across downloads. With a queue, a customer can request the full month, leave the page, and return for the file. The team has to run the worker, notice when jobs stay queued, and show the user what happened to the export.

Write an ADR when a choice like this changes a behavior users rely on or creates a responsibility the team will carry after the pull request. A local detail that the changed lines explain can go in the pull request description. Google Cloud’s guidance on ADR context, options, and decisions.

A Markdown example to reuse

Write the first ADR as a proposal while the options are still open. You can put it near the code, for example in docs/adr/0012-background-csv-exports.md, and ask the team to review it. This is the record after acceptance. Replace the bracketed references with links to your own evidence.

markdown
# ADR-012 — Generate CSV exports in the background

## Context
Generating a large report can exceed the request timeout.
Customers need to download a full month in a single file.

## Options
- Keep generating files during the request and cap report size.
  Fewer components to run, but some customers need several downloads.
- Queue the export. Customers get a single file for a large report,
  with a worker for the team to run and a status for users to see.

## Decision and approval
Accepted — [review where the team accepted the ADR].
The single-file requirement justifies operating a worker.
The request queues the job. The worker produces the file.
The user can find the outcome in the exports list.

## Consequences
The service team [operations reference] runs the worker and responds
when jobs stay queued. The exports list shows when a file is ready
or an export has failed.

## Checks before enabling exports for customers
- With the release candidate in staging, a synthetic report of
  representative size produces the full CSV within the agreed time.
- In production, a test account requests a fresh export through
  the customer path. The check passes if, within the agreed time, the expected worker
  handles that job ID and the downloaded file contains the expected data.
The release owner records both results in the [release issue].

## When to revisit
If urgent jobs wait longer than agreed during export batches,
check where the queue builds up before changing how work is assigned.

Markdown Architectural Decision Records (MADR) calls its optional section for checking the implementation Confirmation. If your team already runs an equivalent check, link to it. The ADR holds the expected result. The release issue records who ran the check, the configuration they used, and the result. MADR’s public decision about the Confirmation section.

At the UK Government Digital Service, a record on the main branch can indicate that the decision was accepted. The ADR lifecycle at the Government Digital Service.

The check that changes the review verdict

The CSV example calls for two checks. In staging, use a synthetic report the size of the ones that used to time out. Compare the file against the expected data and check that the export completes within the agreed time for that case. In production, a much smaller test can verify that the release path works before the team opens it to customers.

Before the production check, agree on how long the export can take. Submit a fresh export through the customer path using a test account with three known synthetic rows. The confirmation returns a job ID, which also appears in the exports list. Record the ID of the new request, close the page, and return to the list. Find the same ID in the deployed export worker’s logs and check that it processed the job. Download the file from the matching row and check the month and contents against the test data. If either the worker’s log entry or the expected CSV is missing at the deadline, record the job ID, state, and result in the release issue. Keep the feature closed to customers.

The check that changes the review verdict
ObservationWhat it demonstratesReview decision
The app confirms that the request is queuedThe system recorded the job.Check generation and download as well.
The large report produces the complete CSV in staging within the agreed timeThe representative case works for this version and test workload.Run the production path check as well.
The release plan has no worker for the production queueThe release is missing the process that should generate the file.Hold the step that would expose exports to customers.
Expected result in production. The intended worker processes the new job ID and the test account downloads the matching CSV with the expected data within the agreed timeThe path works for this deployment and test data.Record the result. Open access once the large-report check has passed too.

The release owner records the environment, application version, worker configuration, job ID, and result. A deployment reference can hold those details if it identifies the application, worker, and queue configuration that ran. If a relevant version or configuration changes before customers get access, repeat the check for the changed path.

A pull request comment could read like this.

The large report passes in staging. The production release plan is missing the export worker. Before enabling exports for customers, have the release owner add the worker and submit a fresh export through the customer path with the production test account. Within the agreed time, confirm in the logs that the intended worker completed the job and compare the CSV from the entry with that same ID against the expected data. Record the deployment, ID, and result in the release issue.

When the team can restrict the feature to the test account, it can merge the code and run the check before opening access. If deployment would make exports available immediately, hold the deployment until the team can test the candidate with restricted access and the check passes. If merging the pull request triggers that deployment, keep the pull request open. The guide to reviewing a pull request against its requirement works through another case where a specific check changes the verdict.

When to revisit the decision

If scheduled exports later arrive in batches and urgent jobs wait longer than agreed, compare the time from queueing to starting in batch and ordinary periods. Check whether reports are keeping the workers busy or whether the jobs are competing for another resource, such as the database. If the team gives reports a dedicated queue and worker, link the new ADR to ADR-012. Reports still run in the background. If the single-file requirement changes and the team goes back to generating reports during the request with a size cap, the new choice supersedes ADR-012. Mark the earlier record as superseded, link to the successor, and keep the original rationale. AWS guidance on preserving ADR history.

If an ADR calls for a check before enabling a feature, use it in the review. Look in the release issue for who will run it, the version to test, and the result. If the check is still open, say in the pull request which step must wait and what result would let it proceed.

Back to contents

Share this article

Have a question or a comment about this article?

Message me on LinkedIn
All articles