Writing an ADR

An Architecture Decision Record (ADR) captures a single significant decision: the context, the choice, and its consequences. ArchForge gives ADRs a template, a review lifecycle, and links to everything they affect.

1. Start from the template

Create a new Decisions / ADR artifact. It opens pre-filled with the standard sections so you only have to fill in the substance:

• Context — the forces at play and the problem being decided.
• Decision — what you are choosing to do, stated plainly.
• Consequences — the trade-offs, both positive and negative.
• Status — managed for you by the lifecycle (see below).

2. Write the decision

Keep it short and specific. A good decision statement reads as an imperative:

We will use Postgres row-level security for tenant isolation.

Use the Context to explain why now and why this matters, and Consequences to be honest about what the choice costs.

3. Move it through review

1. Draft — your working copy. Edit freely.
2. Proposed — submit for review. A reviewer is assigned.
3. The reviewer Accepts, Rejects, or Requests changes.
4. On acceptance the ADR becomes Published — the authoritative record.

4. Link it up

Connect the ADR to what it touches so it doesn't live in isolation:

• Supersedes an earlier ADR it replaces.
• Implements a standard or principle it follows.
• Relates to the reference architecture it affects.

These links make the decision discoverable from every direction later — which is the whole point of a system of record.

5. Keep it current

When a decision is overtaken by events, don't delete it. Mark it Superseded (linking the ADR that replaces it) or Deprecated. The history stays intact and the knowledge graph keeps telling the truth.