Architecture decision records

ADRs capture the why behind decisions that aren't obvious from reading the code — so short agent instruction files and guides can point here instead of re-explaining the reasoning every time.

When to write one

Write an ADR when a decision:

• Was debated (more than one reasonable option existed) and future you / an agent might otherwise re-litigate it
• Has a non-obvious consequence (a thing you deliberately gave up, or a constraint it imposes on future changes)
• Would otherwise get explained inline in project instructions every time it's relevant

Don't write one for choices the code already makes self-evident (e.g. "we use TypeScript") — that's what reading the repo is for.

Format

One file per decision, numbered sequentially: NNNN-short-title.md. Copy the template.

Field	Meaning
Status	Proposed / Accepted / Superseded by ADR-NNNN
Context	The problem/constraint that forced a decision
Decision	What was chosen
Consequences	What this makes easy, what it makes hard, what was traded away

Keep each ADR short (roughly half a page). Link to it from the relevant guide rather than duplicating the reasoning there.

Index

ADR	Title	Status
0001	App and nested package use separate lockfiles, not a workspace	Accepted
0003	Migrate styling from styled-components to Fluent UI v9	Accepted

CMS-specific content-model ADRs are kept in the full internal project docs, not on this public site.