Putting cost in architecture decision records
An ADR that compares options on latency and operability but not cost leaves the most durable consequence undocumented. Here is how to add a cost section that is specific, auditable, and worth revisiting later.
Quick answer
Add a cost section to every ADR with four elements: the estimated monthly cost of each option at current and projected scale, the unit cost (per request, per tenant, per gigabyte), the cost sensitivity (what happens at 10x volume), and the assumptions behind the numbers. Cite the source of the estimate and date it. The point is not precision; it is that the cost consequence is recorded alongside the other consequences and can be checked against reality six months later.
Architecture decision records capture context, options, the decision, and consequences. Most of them handle performance, operability, and team familiarity well, and then treat cost either as a sentence of hand waving or omit it entirely. That is a strange gap, because cost is often the consequence that persists longest and is hardest to reverse once a system is built around it.
The four-part cost section
| Element | Example |
|---|---|
| Monthly cost per option | Option A 3,100 USD, Option B 1,850 USD at current volume |
| Unit cost | A: 0.41 USD per 1k jobs, B: 0.24 USD per 1k jobs |
| Sensitivity at 10x | A: 24,000 USD (sublinear), B: 18,500 USD (linear) |
| Assumptions | 7.5M jobs/month, 400 KB payloads, 30-day retention, us-east-1 |
The sensitivity row is the one that most often changes a decision. Two designs that cost roughly the same today can diverge sharply at scale: an option that amortizes a fixed platform cost across growing volume gets cheaper per unit, while an option built on per-request pricing scales linearly forever. Recording both the current figure and the 10x figure forces that conversation while the decision is still open.
A worked example
A team is choosing between a managed serverless pipeline and a container-based worker pool for asynchronous processing. At 7.5 million jobs a month, serverless costs roughly 1,850 USD and the worker pool roughly 3,100 USD because the pool is provisioned for peak and idles overnight.
At 75 million jobs, serverless reaches roughly 18,500 USD because per-invocation pricing is linear, while the worker pool reaches roughly 24,000 USD but only because it now needs more nodes, and with better autoscaling it would land near 14,000 USD. If the roadmap says 10x within 18 months, the ADR should record both numbers and state which growth assumption the decision depends on. Written down, that assumption becomes checkable. Left unwritten, the team rediscovers it as a budget problem.
State the assumptions explicitly
Cost numbers without assumptions are unusable six months later, because nobody can tell whether a variance means the estimate was wrong or the workload changed. List the volume, the payload or record size, the retention period, the region, the availability topology (single zone, multi zone, multi region), and whether the figure is on-demand or assumes commitment coverage. Six lines of assumptions make the estimate auditable.
Date the estimate and name its source. "Priced from the Terraform plan on 2026-04-14" is verifiable. "Roughly 2k a month" is not, and will be quoted for years by people who do not know where it came from.
Include the options you rejected
The rejected options are the most valuable part of an ADR when someone revisits it. If a third option cost 900 USD but was rejected for an operational reason, record both the cost and the reason. When the estimate turns out to be wrong, or when the operational concern is resolved by a new platform capability, the rejected option becomes a live candidate again, and the record is what makes that reconsideration cheap.
Set a revisit trigger
Add a line stating what would invalidate the decision: "revisit if monthly volume exceeds 30 million jobs or if actual cost exceeds the estimate by more than 40 percent." That converts the ADR from a historical artifact into a control. A quarterly sweep comparing actual cost against ADR estimates surfaces both bad estimates and changed circumstances, and it is one of the cheapest sources of optimization work there is.
Keep the effort proportionate
Not every ADR needs a full cost analysis. Use a threshold: anything with an estimated monthly cost above some amount, commonly 500 or 1,000 USD, or any decision that is expensive to reverse, gets the full section. Everything else gets one line. Requiring detailed cost modeling for trivial decisions is how the practice gets abandoned.
Generate the numbers rather than guessing them
The reason cost sections stay empty is that producing the numbers used to mean an hour with a pricing calculator per option. Writing each candidate architecture as a Terraform plan and pricing it directly removes that friction: C3X prices the plan against a live catalog, so an ADR can cite real resource-level figures for each option in minutes. That also means the estimate can be regenerated later with the same method, which is what makes the revisit trigger meaningful. Seecost-aware architecture review for the review-time practice.
FAQ
What should the cost section of an ADR contain?
Four elements: estimated monthly cost of each option at current and projected scale, unit cost such as per thousand requests or per tenant, cost sensitivity showing what happens at roughly 10x volume, and the explicit assumptions behind the numbers. Cite the source of the estimate and date it, so a later reviewer can tell whether a variance means the estimate was wrong or the workload changed.
Why does cost sensitivity matter more than current cost in an ADR?
Because two designs that cost similarly today can diverge sharply at scale. A design amortizing a fixed platform cost across growing volume gets cheaper per unit, while one built on per-request pricing scales linearly forever. Recording both the current and the 10x figure forces that conversation while the decision is still open rather than after the system is built.
Which assumptions should be recorded with a cost estimate?
Volume, payload or record size, retention period, region, availability topology such as single zone versus multi region, and whether the figure assumes on-demand rates or commitment coverage. Six lines of assumptions turn an unverifiable number into an auditable one, and without them nobody can later distinguish a bad estimate from a changed workload.
Should rejected options include cost figures?
Yes, and they are often the most valuable part of the record. If a third option cost 900 USD but was rejected for an operational reason, document both. When the operational concern is later resolved by a new platform capability, or when the chosen option's estimate proves wrong, the rejected option becomes a live candidate and the record makes reconsidering it cheap.
How do I make ADR cost estimates useful later?
Add a revisit trigger stating what would invalidate the decision, for example volume exceeding 30 million jobs per month or actual cost exceeding the estimate by more than 40 percent. Then run a quarterly sweep comparing actual cost against ADR estimates. That surfaces both bad estimates and changed circumstances and is one of the cheapest sources of optimization work available.
Does every architecture decision need a cost analysis?
No, and requiring one is how the practice gets abandoned. Set a threshold: decisions with estimated monthly cost above roughly 500 to 1,000 USD, or any decision that is expensive to reverse, get the full section. Everything else gets a single line. Proportionate effort keeps the habit sustainable.
What to do next
Cite real numbers in your ADRs. C3X prices each candidate Terraform plan against a live catalog. See the resource catalog.
Share this post
Try C3X on your own Terraform
Free and open source. No API key required. One command to install, one command to estimate.