Design documents, RFCs and ADRs

Most work needs none of these. Write one only when it is useful.

• A design document before implementation when the work takes more than a sprint or one engineer, changes the data model or a contract, adds an integration, involves money movement or regulatory reporting, or needs a staged rollout. Use the [TEMPLATE] Design Document. Its headings are a checklist. Do not skip Observability or Tests.
• An RFC when the approach is truly open or affects more than your team. Set a deadline. An RFC left open becomes the default decision. Duplicate the [TEMPLATE] RFC, or copy docs/rfc/template.md in the owning repository.
• An ADR when a decision is hard or costly to reverse, including an agreed exception to these standards. Keep it short and permanent. Supersede it instead of rewriting it. Duplicate the [TEMPLATE] ADR, or copy docs/adr/template.md in the owning repository.

Keep RFCs and ADRs in the owning repository under docs/rfc/ and docs/adr/. Each folder must have a template. Keep design documents in the owning team or squad’s section of this space. Each team page says where. If there is no owning repository, use this space. Link every document from the ticket and pull request.

What an ADR contains

An ADR records one decision. Keep it short. Use the four main headings from Michael Nygard’s original format: Context, Decision, Status, Consequences. You can write a good ADR without opening the template.

# ADR-0007: Use ScalaCheck for property tests

- Status: Accepted (2026-08-22)
- Supersedes: -
- Superseded by: -

## Context
Why this decision is needed now; the forces at play.

## Decision
What we will do, in one or two sentences.

## Consequences
What becomes easier, what becomes harder, what we accept.

The in-repo template at NT-NinjaTrader/strata (docs/adr/template.md and docs/rfc/template.md) is the reference supported by these standards. For design/status docs kept beside code, NT-NinjaTrader/ntc-core uses a per-project _TEMPLATE.md with a status field.

ADR status lifecycle

An accepted ADR is a permanent record. Never edit an accepted decision. To change it, write a new numbered ADR that supersedes it, and link the two ADRs both ways.

stateDiagram-v2
direction LR
[*] --> Proposed
Proposed --> Accepted
Accepted --> Superseded: a new ADR replaces it
Accepted --> Deprecated: no replacement
Superseded --> [*]
Deprecated --> [*]

Require a real alternative

Every RFC and design document must consider at least one real alternative. One alternative must be do nothing / status quo. Explain the cost of the status quo and why it is not enough. A decision without an alternative is not a decision. It is only a preference.

## Alternatives considered
1. Do nothing / status quo — the cost, and why it is insufficient.
2. Option B — trade-offs.
3. Option C (proposed) — why it wins.

## Decision deadline
2026-09-05. Decider: @squad-lead. If undecided by then, option 1 stands.

Time-box with a named decider

Give every RFC a clear decision deadline and one named decider. “A decision by default” must go to a real owner, not happen because time ran out. If the deadline passes without a decision, keep the status quo.

Numbering and index

Number decisions in order and use four digits: ADR-0001, RFC-0001. Keep an index at docs/adr/README.md so people can find decisions and cite them consistently. See adr.github.io for numbering rules and tools.

Decisions that deserve an ADR

Watch for these stack-specific triggers:

• A Scala effect-system or core library choice.
• A JDK version move (for example, 17 to 21).
• A GKE, Terraform, or Atlantis module pattern that other services will copy.
• A cross-service contract change, including any change to tradovate/master-scheme.
• An agreed exception to these standards.

Exceptions record an ADR

An agreed exception to these standards is hard or costly to reverse, so it needs an ADR. Add the ADR link to the exception itself. See exceptions for the process, and architecture for the standards these decisions implement.

Keeping documents current

Mark a design document or ADR as superseded instead of deleting it when the design changes in a major way. The record of why a past decision was made remains useful after the decision changes.

How to choose, and the Confluence templates: RFCs and ADRs.