Skip to content

Decisions and constraints

The Architecture group: decisions record what was chosen and why, constraints state the qualities the system must keep, such as latency or audit rules.

Decisions and constraints make up the Architecture group of the sidebar. They are records about the model: why it has its shape, and what it must keep. Both belong to the project or to one bounded context, whose Decisions tab lists them in two sections.

Decisions

A decision is an architecture decision record: what the team chose, in which situation, and what follows from it, such as "Payments owns the refund ledger".

FieldWhat it holds
TitleThe decision in a few words. Required.
StatusProposed, Accepted or Superseded. Required; the New decision dialog starts it as Proposed. A rejected proposal is archived.
Superseded byThe decision that replaced it. Required when the status is Superseded, and only then.
SummaryOne line, 500 characters at most.
ContextThe forces and the problem, in Markdown.
DecisionWhat was chosen, in Markdown.
ConsequencesWhat follows from it, in Markdown.
Options consideredThe alternatives, each with the reason it was not chosen.
Applies toThe artefacts it concerns: any artefact of any kind, up to 50.
  • A decision page shows the decisions it supersedes, and the one that superseded it.
  • Naming a superseding decision that is itself Proposed or Superseded gets a warning.
  • A decision has no date field: the history records when its status became Accepted.

Note

Two kinds of decision

A decision artefact is written on purpose, like any other part of the spec. An answered question is also recorded as a decision when its task publishes; see Decisions. When an answer settles something worth keeping, write it down as a decision artefact too.

Constraints

A constraint states a quality the system must keep, a non-functional requirement such as "Checkout answers within 300 ms at p95 under 200 requests per second."

FieldWhat it holds
NameA short name, such as Checkout latency. Required.
CategoryPerformance, Security, Audit, Availability or Other. Required.
StatementThe constraint in one line, 500 characters at most. Required.
MeasureHow it is checked, such as "k6 checkout.js p95 < 300 ms". Without one, the constraint gets a warning.
DescriptionMore detail, in Markdown.
Applies toThe artefacts it concerns: any artefact of any kind, up to 50.

A decision can apply to a constraint, to say why it exists, or to another decision that it refines.

Where they show

  • The Decisions and Constraints pages list them, with Status or Category filters.
  • A bounded context's Decisions tab lists the decisions and constraints of that context.
  • In Git they are written under decisions/ and constraints/, at the top of the spec folder or in the folder of their context; see Spec files in your repository.
  • A constraint has a build status like the model and behaviour it constrains; a decision has none.

Next steps