Concept guide
Architecture decision records that stay attached
An ADR is only worth writing if it can still answer “why does this exist?” a year later. That depends less on the template than on whether the record stays linked to the architecture it shaped.
What an ADR is actually for
An architecture decision record documents one material technical choice: the context that forced it, the options considered, the trade-off accepted, and the consequences that follow. The value is not historical. It is operational — it is what stops a settled question from being reopened every six months, and what tells a new engineer why the obvious simplification is not allowed.
Michael Nygard's original format is still a reasonable baseline: title, status, context, decision, consequences. Most teams that adopt it do not fail because the template is wrong. They fail because the record and the system drift apart.
The parts that make a record useful
- Context
- What constraint made this a decision at all — a requirement, a compliance boundary, a team-size reality, a load characteristic. A record without context cannot be re-evaluated when the constraint changes.
- Options considered
- The alternatives that were genuinely on the table, each with its trade-off. This is the section teams skip, and it is the one that prevents the same debate from restarting with a new participant.
- Decision and its reasoning
- The chosen option stated plainly, plus the reasoning that made it preferable here — not “best practice”, but the specific trade the team accepted.
- Consequences
- What becomes easier, what becomes harder, what must now be maintained. The cost side is the part that makes the record honest.
- Links to the model
- Which components, boundaries, or invariants this decision governs. This is the part a plain Markdown file cannot maintain on its own.
Where decision logs break down
A decision log in a repository is better than nothing, and it has three structural weaknesses that no template fixes.
- Writes stop when the pressure starts. Decisions are recorded during calm periods and skipped during the week the team is shipping — which is exactly when the consequential ones are made.
- Nothing enforces the link. A record can name “tenant data” in prose and nothing notices when that component is renamed, split, or removed.
- Reads happen at the wrong time. The person who needs the reason is usually mid-incident, not browsing a numbered folder of Markdown files.
The result is a folder that is technically complete and practically unconsulted. The decisions exist; the architecture no longer points at them.
How Avylo records a decision
Avylo treats a decision as part of the architecture, not a document beside it. During grounded discovery, the workspace surfaces one consequential choice at a time and shows what it inferred, what it is asking, and why the answer changes the design.
- The question is grounded in your context
It comes from the requirements and constraints you provided, not from a generic checklist of architecture topics.
- Options arrive with their trade-offs
A recommendation, at least one alternative, the impact of each, and the assumption being made — all reviewable before anything is published.
- You accept, change, or skip
The decision is persisted against the project. Skipping is a recorded choice too, which keeps unresolved uncertainty visible instead of hidden.
- The model keeps the link
Components carry the requirement they satisfy and the decision that shaped them, so Why? can answer from stored graph evidence rather than a regenerated guess.
- Changes are revisioned, not rewritten
A material change becomes a revision-bound proposal. The prior decision stays in history with the revision where it applied.
Avylo does not claim a decision is correct. It makes the reasoning, alternatives, and confidence visible so a reviewer can disagree with the reasoning instead of guessing at it.
A minimal example
Consider a fleet-tracking product where organizations need isolated data. The decision is not “use PostgreSQL”. It is how tenants are separated, and what that choice costs.
Chosen
- Shared database with row-level security
- Lower operational overhead
- Cost: policy coverage must be maintained as the model evolves
Rejected
- Database per organization
- Stronger isolation boundary
- Cost: provisioning, migrations, and recovery across databases
Both options are defensible. What makes the record valuable is that the next engineer can see the trade that was accepted and the component it governs — so changing it is a deliberate decision rather than an accidental drift.
Further reading
- What is an architecture operating system? — the wider structure the record belongs to.
- System design for early-stage startups — applying decision records while requirements are still moving.
Questions
What belongs in an architecture decision record?
The decision statement, the context that forced it, the options considered, the trade-off accepted, the consequences, and the status. A record without the rejected alternatives is a note, not a decision — it cannot stop the same debate from restarting.
How long should an ADR be?
Short enough that someone will actually read it during an incident. Most decisions need one page: context, decision, alternatives, consequences. Length is not the goal; the ability to answer why this exists and what it costs is.
Does Avylo generate ADRs automatically?
Avylo records each material architectural decision with its options, trade-offs, assumption, impact, and confidence while the creator resolves it. Decisions are captured during discovery rather than reconstructed from memory afterwards, and they remain linked to the components they shaped.
Capture the reason while it is still fresh.
Avylo records decisions during discovery, with options, trade-offs, and the components they affect. Request private alpha access.