---
title: Decisions (ADR template)
slug: decisions-adr-template
icon: {"faIcon":"fa-solid fa-code-merge"}
docTags: 
createdAt: 2026-05-08T14:07:54.131Z
---

Use this page as a template for documenting important architectural or organizational decisions. A consistent ADR (Architecture Decision Record) format helps teams understand **why** decisions were made, what alternatives were considered, and how future work may be affected.

:::hint{type="info"}
Update ADRs whenever major technical or organizational decisions are proposed, accepted, or deprecated. Keeping this history clear reduces confusion and preserves long‑term context.
:::

## How to use this template

Each ADR should clearly describe:

- **Context** – What problem or situation led to this decision?
- **Decision** – What choice was made and why?
- **Alternatives** – What other options were considered?
- **Consequences** – How does this decision impact the system, team, or future work?
- **Status** – Proposed, accepted, deprecated, or superseded

Use the expandable section below to create a new ADR entry.

:::ExpandableHeading
## ADR title (replace this)

### Status

Proposed / Accepted / Deprecated / Superseded

### Context

Describe the background, constraints, and motivating factors behind this decision.

### Decision

State the decision that was made and provide reasoning behind the choice.

### Alternatives considered

Outline other options you evaluated and why they were not chosen.

### Consequences

Explain the impact of this decision–including risks, trade‑offs, and any long‑term implications.
:::

:::ExpandableHeading
## Examples

### Choosing an authentication method

- **Context:** Need secure API access that works for both internal tools and third‑party integrations.
- **Decision:** Use JWT‑based token authentication.
- **Alternatives:** API key headers, OAuth 2.0
- **Consequences:** Simple implementation, but tokens must be rotated regularly.

### Adopting a UI framework

- **Context:** Need consistent UI patterns across feature teams.
- **Decision:** Adopt a shared component library.
- **Alternatives:** Build components independently, use disparate frameworks.
- **Consequences:** More consistency and shared patterns, but requires centralized maintenance.
:::

## Best practices for ADRs

- Write decisions clearly and concisely
- Avoid implementation details–focus on reasoning
- Link related ADRs to show evolution of ideas
- Keep ADRs updated as decisions evolve or are replaced
- Encourage team discussions before accepting major decisions

## What to read next

Help teammates continue exploring internal documentation:

- [Team handbook](docId\:Lxwf_7iVQNLBou6NJiovD) – Culture and communication norms
- [Engineering docs](docId\:F7L6Z71MnR6RB72kObx7Y) – Architecture, development workflows, and runbooks
- [Onboarding checklist](docId\:HFxTrNxWva_E4_TnBt6W9) – Steps for new teammates