Keep the reasons behind your architecture

A design doc proposes a change. An ADR preserves a decision future changes must understand. Linked decision records keep the context, considered options and outcome next to the objects they affect.

Start free Read the decisions guide

Plans: Decision records on every plan. Status changes and supersede chains on Business and Enterprise.

Superseded Tender loads over EDI 204 before carrier APIs decision, with a link to its replacement, considered EDI and REST options, and the decision outcome. — An architecture decision record

Find why a service works this way

Read the context, options and outcome in its linked decision records.

Follow a changed decision

Trace the supersede chain to the choice that replaced it.

Find decisions from the system

Open the records linked to a catalog object or architecture doc.

Write down the choice and its context

MADR fields give a decision enough structure to read later. Describe the problem before recording the outcome.

Context and deciders
Considered options and decision outcome
Consequences of the choice

Accepted carrier REST API decision with context, chosen and alternative options, trade-offs and the decision outcome. — Context, outcome and consequences

Keep the alternatives beside the outcome

Record the pros and cons of each option. Mark the chosen option so a future reader can see what the team considered and why it chose this path.

Compare the options in one record
Keep the reasons for choosing or rejecting an option

Considered option EDI 204 tenders, marked Chosen, with pros reach existing carrier integrations and reuse established tender workflows, and con delayed acknowledgements complicate the tender deadline. — Considered options with the chosen option marked

Follow a choice as the system changes

A decision can be Proposed, Accepted, Rejected, Deprecated or Superseded. A supersede chain connects an earlier decision to the one that replaced it.

Read the earlier context before replacing a decision
Follow the supersede chain to the replacement

Plans: Status changes and supersede chains on Business and Enterprise.

Architecture decisions list with accepted carrier REST API and Kafka decisions and a superseded EDI 204 tender decision. — Decision statuses and supersede history

Replace a decision without losing its constraint

ADR-0002 chose EDI 204 tendering; ADR-0003 superseded it with carrier REST APIs where available. The reason EDI acknowledgements arrive late still matters, so DD-0021 keeps a 15-minute window for EDI carriers. The supersede chain shows the replacement; the constraint survives in the records that still rely on it.

ADR-0002

Superseded by ADR-0003

Consequence: delayed acknowledgements complicate the tender deadline

ADR-0003

Accepted

Prefer carrier REST APIs over EDI where available

DD-0021 decision

Approved by a person

API carriers get 5 minutes to accept a tender. EDI carriers keep 15.

A superseded decision and the constraint that survivedRecreated from Archdocs views with sample data.

Find decisions from the service they affect

Link a decision to catalog objects and canvas docs. An object page lists the decisions that affect it, so people and agents can read the rationale before proposing a change.

Agents can read the decisions for an object over MCP
Agents can propose new decision records over MCP
The MCP server and decision records are on every plan

MCP capabilities Link decisions to records

Dispatch Service object with its Used in tab listing architecture documents that reference it. — An object and its linked records

One change can lead to a lasting choice

A design doc records one change: the spec, the plan and the recorded result. A decision record keeps a choice the team lives with, such as using a queue instead of an inline call.

Use the design doc to review the change
Use the decision record to preserve the choice and its consequences

Decision section of a design doc: each service named in the decision is a link to its catalog object. — The decision within a design doc

Screenshots are from a sample workspace. Recreated views are labeled.

Start free Read the docs